ne_ssl_set_verify(3) [redhat man page]

NE_SSL_SET_VERIFY(3)						neon API reference					      NE_SSL_SET_VERIFY(3)

NAME

       ne_ssl_set_verify - register an SSL certificate verification callback

SYNOPSIS

       #include <ne_session.h>

       typedef int (*ne_ssl_verify_fn) (void *userdata, int failures, const ne_ssl_certificate *cert);

       void ne_ssl_set_verify (ne_session *session, ne_ssl_verify_fn verify_fn, void *userdata);

DESCRIPTION

       To  enable manual SSL certificate verification, a callback can be registered using ne_ssl_set_verify. 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_load_ca(3)),	or
       if the certificate presented is invalid in some way, the connection will fail.

       When  the callback is invoked, the failures 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):

       NE_SSL_NOTYETVALID
	      The certificate is not yet valid.

       NE_SSL_EXPIRED
	      The certificate has expired.

       NE_SSL_CNMISMATCH
	      The hostname used for the session does not match the hostname to which the certificate was issued: this could mean that the  connec-
	      tion has been intercepted.

       NE_SSL_UNKNOWNCA
	      The Certificate Authority which signed the certificate is not trusted.

       The  cert  parameter passed to the callback describes the certificate which was presented by the server, see ne_ssl_certificate(3) for more
       details. The certificate object given is only valid until the callback returns.

RETURN VALUE

       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).

EXAMPLES

       Manual certificate verification:

       static int
       my_verify(void *userdata, int failures, const ne_ssl_certificate *cert)
       {
	  /* leak the return values of ne_ssl_readable_dname for simplicity! */
	  printf("Issuer: %s
", ne_ssl_readable_dname(cert->issuer);
	  printf("Subject: %s
", ne_ssl_readable_dname(cert->subject);
	  if (failures & NE_SSL_CNMISMATCH) {
	     printf("Server certificate was issued to `%s'; "
		    "connection may have been intercepted!
",
		    cert->subject->commonName);
	  }
	  if (failures & NE_SSL_EXPIRED) {
	     printf("Server certificate expired on %s!", cert->until);
	  }
	  /* ... check for other failures ... */
	  if (prompt_user())
	     return 1; /* fail verification */
	  else
	     return 0; /* trust certificate */
       }

       int
       main(...)
       {
	   ne_session *sess = ne_session_create("https", "some.host.name", 443);
	   ne_ssl_set_verify(sess, my_verify, NULL);
	   ...
       }

SEE ALSO

       ne_ssl_certificate(3), ne_ssl_load_ca(3), ne_ssl_dname(3), ne_ssl_readable_dname(3)

AUTHOR

       Joe Orton <neon@webdav.org>.

neon 0.23.5							   8 October 2002					      NE_SSL_SET_VERIFY(3)

NE_SSL_SET_VERIFY(3)						neon API reference					      NE_SSL_SET_VERIFY(3)

NAME

       ne_ssl_set_verify - register an SSL certificate verification callback

SYNOPSIS

       #include <ne_session.h>

       typedef int ne_ssl_verify_fn(void *userdata, int failures, const ne_ssl_certificate *cert);

       void ne_ssl_set_verify(ne_session *session, ne_ssl_verify_fn verify_fn, void *userdata);

DESCRIPTION

       To enable manual SSL certificate verification, a callback can be registered using ne_ssl_set_verify. 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.

       When the callback is invoked, the failures 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):

       NE_SSL_NOTYETVALID
	   The certificate is not yet valid.

       NE_SSL_EXPIRED
	   The certificate has expired.

       NE_SSL_IDMISMATCH
	   The hostname used for the session does not match the hostname to which the certificate was issued.

       NE_SSL_UNTRUSTED
	   The Certificate Authority which signed the certificate is not trusted.

       Note that if either of the NE_SSL_IDMISMATCH or NE_SSL_UNTRUSTED failures is given, the connection may have been intercepted by a third
       party, and must not be presumed to be "secure".

       The cert 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 cert object given is not valid after the callback returns.

RETURN VALUE

       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).

EXAMPLES

       The following code implements an example verification callback, using the dump_cert 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 userdata parameter to the callback.

	   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'.
",
			id, hostname);
	       else
		 printf("The certificate was not issued for '%s'
", 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");
	     ...
	   }

SEE ALSO

       ne_ssl_trust_cert, ne_ssl_readable_dname, ne_ssl_cert_subject

AUTHOR

       Joe Orton <neon@lists.manyfish.co.uk>
	   Author.

COPYRIGHT

neon 0.29.6							    3 May 2011						      NE_SSL_SET_VERIFY(3)