ne_ssl_set_verify.3

linux subdivision ying gai ke yi le ba

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "NE_SSL_SET_VERIFY" 3 "5 July 2004" "neon 0.24.7" "neon API reference"
.SH NAME
ne_ssl_set_verify \- register an SSL certificate verification callback
.SH "SYNOPSIS"
.ad l
.hy 0

#include <ne_session\&.h>
.sp
.HP 31
typedef\ int\ \fBne_ssl_verify_fn\fR\ (void\ *\fIuserdata\fR, int\ \fIfailures\fR, const\ ne_ssl_certificate\ *\fIcert\fR);
.HP 24
void\ \fBne_ssl_set_verify\fR\ (ne_session\ *\fIsession\fR, ne_ssl_verify_fn\ \fIverify_fn\fR, void\ *\fIuserdata\fR);
.ad
.hy

.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 \fBne_ssl_trust_cert\fR(3)), 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 ``secure''\&.

.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 \fBne_ssl_cert_signedby\fR(3)\&. 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 \fBne_ssl_cert_subject\fR(3) 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\&.

.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
\fBne_ssl_trust_cert\fR(3), \fBne_ssl_readable_dname\fR(3), \fBne_ssl_cert_subject\fR(3)

.SH AUTHOR
Joe Orton <neon@webdav\&.org>.