164 lines
5.2 KiB
XML
164 lines
5.2 KiB
XML
<refentry id="refsslvfy"> <!-- -*- xml-mode -*- -->
|
|
|
|
<refmeta>
|
|
<refentrytitle>ne_ssl_set_verify</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname id="ne_ssl_set_verify">ne_ssl_set_verify</refname>
|
|
<refpurpose>register an SSL certificate verification callback</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<funcsynopsis>
|
|
|
|
<funcsynopsisinfo>#include <ne_session.h></funcsynopsisinfo>
|
|
|
|
<!-- hard to put data type declarations here -->
|
|
|
|
<funcprototype>
|
|
<funcdef>typedef int <function>ne_ssl_verify_fn</function></funcdef>
|
|
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
|
<paramdef>int <parameter>failures</parameter></paramdef>
|
|
<paramdef>const ne_ssl_certificate *<parameter>cert</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>void <function>ne_ssl_set_verify</function></funcdef>
|
|
<paramdef>ne_session *<parameter>session</parameter></paramdef>
|
|
<paramdef>ne_ssl_verify_fn <parameter>verify_fn</parameter></paramdef>
|
|
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>To enable manual SSL certificate verification, a
|
|
callback can be registered using
|
|
<function>ne_ssl_set_verify</function>. If such a callback is not
|
|
registered, when a connection is established to an SSL server which
|
|
does not present a certificate signed by a trusted CA (see <xref
|
|
linkend="ne_ssl_trust_cert"/>), or if the certificate presented is invalid in
|
|
some way, the connection will fail.</para>
|
|
|
|
<para>When the callback is invoked, the
|
|
<parameter>failures</parameter> parameter gives a bitmask indicating
|
|
in what way the automatic certificate verification failed. The value
|
|
is equal to the bit-wise OR of one or more of the following
|
|
constants (and is guaranteed to be non-zero):</para>
|
|
|
|
<variablelist>
|
|
<varlistentry><term><constant>NE_SSL_NOTYETVALID</constant></term>
|
|
<listitem>
|
|
<simpara>The certificate is not yet valid.</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><constant>NE_SSL_EXPIRED</constant></term>
|
|
<listitem>
|
|
<simpara>The certificate has expired.</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><constant>NE_SSL_IDMISMATCH</constant></term>
|
|
<listitem>
|
|
<simpara>The hostname used for the session does not match
|
|
the hostname to which the certificate was issued.</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><constant>NE_SSL_UNTRUSTED</constant></term>
|
|
<listitem>
|
|
<simpara>The Certificate Authority which signed the certificate
|
|
is not trusted.</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>Note that if either of the
|
|
<constant>NE_SSL_IDMISMATCH</constant> or
|
|
<constant>NE_SSL_UNTRUSTED</constant> failures is given, the
|
|
connection may have been intercepted by a third party, and
|
|
must not be presumed to be <quote>secure</quote>.</para>
|
|
|
|
<para>The <parameter>cert</parameter> parameter passed to the
|
|
callback represents the certificate which was presented by the server.
|
|
If the server presented a chain of certificates, the chain can be
|
|
accessed using <xref linkend="ne_ssl_cert_signedby"/>. The
|
|
<parameter>cert</parameter> object given is not valid after the
|
|
callback returns.</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return value</title>
|
|
|
|
<para>The verification callback must return zero to indicate
|
|
that the certificate should be trusted; and non-zero otherwise (in
|
|
which case, the connection will fail).</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>The following code implements an example verification
|
|
callback, using the <function>dump_cert</function> function
|
|
from <xref linkend="ne_ssl_cert_subject"/> to display
|
|
certification information. Notice that the hostname of the
|
|
server used for the session is passed as the
|
|
<parameter>userdata</parameter> parameter to the
|
|
callback.</para>
|
|
|
|
<programlisting>
|
|
static int
|
|
my_verify(void *userdata, int failures, const ne_ssl_certificate *cert)
|
|
{
|
|
const char *hostname = userdata;
|
|
|
|
dump_cert(cert);
|
|
|
|
puts("Certificate verification failed - the connection may have been "
|
|
"intercepted by a third party!");
|
|
|
|
if (failures & NE_SSL_IDMISMATCH) {
|
|
const char *id = ne_ssl_cert_identity(cert);
|
|
if (id)
|
|
printf("Server certificate was issued to '%s' not '%s'.\n",
|
|
id, hostname);
|
|
else
|
|
printf("The certificate was not issued for '%s'\n", hostname);
|
|
}
|
|
|
|
if (failures & NE_SSL_UNTRUSTED)
|
|
puts("The certificate is not signed by a trusted Certificate Authority.");
|
|
|
|
/* ... check for validity failures ... */
|
|
|
|
if (prompt_user())
|
|
return 1; /* fail verification */
|
|
else
|
|
return 0; /* trust the certificate anyway */
|
|
}
|
|
|
|
int
|
|
main(...)
|
|
{
|
|
ne_session *sess = ne_session_create("https", "some.host.name", 443);
|
|
ne_ssl_set_verify(sess, my_verify, "some.host.name");
|
|
...
|
|
}</programlisting>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
|
|
<para><xref linkend="ne_ssl_trust_cert"/>, <xref
|
|
linkend="ne_ssl_readable_dname"/>, <xref linkend="ne_ssl_cert_subject"/></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|