ne_ssl_set_verify
3

# ne_ssl_set_verify

register an SSL certificate verification callback

    	  #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 ), 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 . 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 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'.\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");
      ...
    }

## See also

, ,