Debian Codegraph @

deps/libneon/doc/ref/sslvfy.xml

raw
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
43 callback can be registered using
44 <function>ne_ssl_set_verify</function>. If such a callback is not
45 registered, when a connection is established to an SSL server which
46 does not present a certificate signed by a trusted CA (see <xref
47 linkend="ne_ssl_trust_cert"/>), or if the certificate presented is invalid in
48 some way, the connection will fail.</para>
49
50 <para>When the callback is invoked, the
51 <parameter>failures</parameter> parameter gives a bitmask indicating
52 in what way the automatic certificate verification failed. The value
53 is equal to the bit-wise OR of one or more of the following
54 constants (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
70 the 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
76 is 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
88 callback represents the certificate which was presented by the server.
89 If the server presented a chain of certificates, the chain can be
90 accessed using <xref linkend="ne_ssl_cert_signedby"/>. The
91 <parameter>cert</parameter> object given is not valid after the
92 callback returns.</para>
93
94 </refsect1>
95
96 <refsect1>
97 <title>Return value</title>
98
99 <para>The verification callback must return zero to indicate
100 that the certificate should be trusted; and non-zero otherwise (in
101 which 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>
116 static int
117 my_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
146 int
147 main(...)
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>