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 &lt;ne_session.h&gt;</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 &amp; 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 &amp; 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