1 <refentry id="refsslvfy"> <!-- -*- xml-mode -*- --> 2 3 <refmeta> 4 <refentrytitle>ne_ssl_set_verify</refentrytitle> 5 <manvolnum>3</manvolnum> 6 </refmeta> 7 8 <refnamediv> 9 <refname id="ne_ssl_set_verify">ne_ssl_set_verify</refname> 10 <refpurpose>register an SSL certificate verification callback</refpurpose> 11 </refnamediv> 12 13 <refsynopsisdiv> 14 15 <funcsynopsis> 16 17 <funcsynopsisinfo>#include <ne_session.h></funcsynopsisinfo> 18 19 <!-- hard to put data type declarations here --> 20 21 <funcprototype> 22 <funcdef>typedef int <function>ne_ssl_verify_fn</function></funcdef> 23 <paramdef>void *<parameter>userdata</parameter></paramdef> 24 <paramdef>int <parameter>failures</parameter></paramdef> 25 <paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef> 26 </funcprototype> 27 28 <funcprototype> 29 <funcdef>void <function>ne_ssl_set_verify</function></funcdef> 30 <paramdef>ne_session *<parameter>session</parameter></paramdef> 31 <paramdef>ne_ssl_verify_fn <parameter>verify_fn</parameter></paramdef> 32 <paramdef>void *<parameter>userdata</parameter></paramdef> 33 </funcprototype> 34 35 </funcsynopsis> 36 37 </refsynopsisdiv> 38 39 <refsect1> 40 <title>Description</title> 41 42 <para>To enable manual SSL certificate verification, a 43callback can be registered using 44<function>ne_ssl_set_verify</function>. If such a callback is not 45registered, when a connection is established to an SSL server which 46does not present a certificate signed by a trusted CA (see <xref 47linkend="ne_ssl_trust_cert"/>), or if the certificate presented is invalid in 48some way, the connection will fail.</para> 49 50 <para>When the callback is invoked, the 51<parameter>failures</parameter> parameter gives a bitmask indicating 52in what way the automatic certificate verification failed. The value 53is equal to the bit-wise OR of one or more of the following 54constants (and is guaranteed to be non-zero):</para> 55 56 <variablelist> 57 <varlistentry><term><constant>NE_SSL_NOTYETVALID</constant></term> 58 <listitem> 59 <simpara>The certificate is not yet valid.</simpara> 60 </listitem> 61 </varlistentry> 62 <varlistentry><term><constant>NE_SSL_EXPIRED</constant></term> 63 <listitem> 64 <simpara>The certificate has expired.</simpara> 65 </listitem> 66 </varlistentry> 67 <varlistentry><term><constant>NE_SSL_IDMISMATCH</constant></term> 68 <listitem> 69 <simpara>The hostname used for the session does not match 70the hostname to which the certificate was issued.</simpara> 71 </listitem> 72 </varlistentry> 73 <varlistentry><term><constant>NE_SSL_UNTRUSTED</constant></term> 74 <listitem> 75 <simpara>The Certificate Authority which signed the certificate 76is not trusted.</simpara> 77 </listitem> 78 </varlistentry> 79 </variablelist> 80 81 <para>Note that if either of the 82 <constant>NE_SSL_IDMISMATCH</constant> or 83 <constant>NE_SSL_UNTRUSTED</constant> failures is given, the 84 connection may have been intercepted by a third party, and 85 must not be presumed to be <quote>secure</quote>.</para> 86 87 <para>The <parameter>cert</parameter> parameter passed to the 88callback represents the certificate which was presented by the server. 89If the server presented a chain of certificates, the chain can be 90accessed using <xref linkend="ne_ssl_cert_signedby"/>. The 91<parameter>cert</parameter> object given is not valid after the 92callback returns.</para> 93 94 </refsect1> 95 96 <refsect1> 97 <title>Return value</title> 98 99 <para>The verification callback must return zero to indicate 100that the certificate should be trusted; and non-zero otherwise (in 101which case, the connection will fail).</para> 102 </refsect1> 103 104 <refsect1> 105 <title>Examples</title> 106 107 <para>The following code implements an example verification 108 callback, using the <function>dump_cert</function> function 109 from <xref linkend="ne_ssl_cert_subject"/> to display 110 certification information. Notice that the hostname of the 111 server used for the session is passed as the 112 <parameter>userdata</parameter> parameter to the 113 callback.</para> 114 115 <programlisting> 116static int 117my_verify(void *userdata, int failures, const ne_ssl_certificate *cert) 118{ 119 const char *hostname = userdata; 120 121 dump_cert(cert); 122 123 puts("Certificate verification failed - the connection may have been " 124 "intercepted by a third party!"); 125 126 if (failures & NE_SSL_IDMISMATCH) { 127 const char *id = ne_ssl_cert_identity(cert); 128 if (id) 129 printf("Server certificate was issued to '%s' not '%s'.\n", 130 id, hostname); 131 else 132 printf("The certificate was not issued for '%s'\n", hostname); 133 } 134 135 if (failures & NE_SSL_UNTRUSTED) 136 puts("The certificate is not signed by a trusted Certificate Authority."); 137 138 /* ... check for validity failures ... */ 139 140 if (prompt_user()) 141 return 1; /* fail verification */ 142 else 143 return 0; /* trust the certificate anyway */ 144} 145 146int 147main(...) 148{ 149 ne_session *sess = ne_session_create("https", "some.host.name", 443); 150 ne_ssl_set_verify(sess, my_verify, "some.host.name"); 151 ... 152}</programlisting> 153 154 </refsect1> 155 156 <refsect1> 157 <title>See also</title> 158 159 <para><xref linkend="ne_ssl_trust_cert"/>, <xref 160 linkend="ne_ssl_readable_dname"/>, <xref linkend="ne_ssl_cert_subject"/></para> 161 </refsect1> 162 163 </refentry> 164