.\" ** You probably do not want to edit this file directly **
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
.TH "NE_SSL_SET_VERIFY" "3" "23 May 2006" "neon 0.26.1" "neon API reference"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
ne_ssl_set_verify \- register an SSL certificate verification callback
.SH "SYNOPSIS"
.PP
\fB#include <ne_session.h>\fR
.HP 29
\fBtypedef\ int\ \fBne_ssl_verify_fn\fR\fR\fB(\fR\fBvoid\ *\fR\fB\fIuserdata\fR\fR\fB, \fR\fBint\ \fR\fB\fIfailures\fR\fR\fB, \fR\fBconst\ ne_ssl_certificate\ *\fR\fB\fIcert\fR\fR\fB);\fR
.HP 23
\fBvoid\ \fBne_ssl_set_verify\fR\fR\fB(\fR\fBne_session\ *\fR\fB\fIsession\fR\fR\fB, \fR\fBne_ssl_verify_fn\ \fR\fB\fIverify_fn\fR\fR\fB, \fR\fBvoid\ *\fR\fB\fIuserdata\fR\fR\fB);\fR
.SH "DESCRIPTION"
.PP
To enable manual SSL certificate verification, a callback can be registered using
\fBne_ssl_set_verify\fR. 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
ne_ssl_trust_cert), or if the certificate presented is invalid in some way, the connection will fail.
.PP
When the callback is invoked, the
\fIfailures\fR
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):
.TP
\fBNE_SSL_NOTYETVALID\fR
The certificate is not yet valid.
.TP
\fBNE_SSL_EXPIRED\fR
The certificate has expired.
.TP
\fBNE_SSL_IDMISMATCH\fR
The hostname used for the session does not match the hostname to which the certificate was issued.
.TP
\fBNE_SSL_UNTRUSTED\fR
The Certificate Authority which signed the certificate is not trusted.
.PP
Note that if either of the
\fBNE_SSL_IDMISMATCH\fR
or
\fBNE_SSL_UNTRUSTED\fR
failures is given, the connection may have been intercepted by a third party, and must not be presumed to be
\(lqsecure\(rq.
.PP
The
\fIcert\fR
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
ne_ssl_cert_signedby. The
\fIcert\fR
object given is not valid after the callback returns.
.SH "RETURN VALUE"
.PP
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).
.SH "EXAMPLES"
.PP
The following code implements an example verification callback, using the
\fBdump_cert\fR
function from
ne_ssl_cert_subject
to display certification information. Notice that the hostname of the server used for the session is passed as the
\fIuserdata\fR
parameter to the callback.
.sp
.nf
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");
  ...
}
.fi
.SH "SEE ALSO"
.PP
ne_ssl_trust_cert,
ne_ssl_readable_dname,
ne_ssl_cert_subject