1NE_SSL_SET_VERIFY(3)          neon API reference          NE_SSL_SET_VERIFY(3)
2
3
4

NAME

6       ne_ssl_set_verify - register an SSL certificate verification callback
7

SYNOPSIS

9       #include <ne_session.h>
10
11       typedef int ne_ssl_verify_fn(void *userdata, int failures,
12                                    const ne_ssl_certificate *cert);
13
14       void ne_ssl_set_verify(ne_session *session, ne_ssl_verify_fn verify_fn,
15                              void *userdata);
16

DESCRIPTION

18       To enable manual SSL certificate verification, a callback can be
19       registered using ne_ssl_set_verify. If such a callback is not
20       registered, when a connection is established to an SSL server which
21       does not present a certificate signed by a trusted CA (see
22       ne_ssl_trust_cert), or if the certificate presented is invalid in some
23       way, the connection will fail.
24
25       When the callback is invoked, the failures parameter gives a bitmask
26       indicating in what way the automatic certificate verification failed.
27       The value is equal to the bit-wise OR of one or more of the following
28       constants (and is guaranteed to be non-zero):
29
30       NE_SSL_NOTYETVALID
31           The certificate is not yet valid.
32
33       NE_SSL_EXPIRED
34           The certificate has expired.
35
36       NE_SSL_IDMISMATCH
37           The hostname used for the session does not match the hostname to
38           which the certificate was issued.
39
40       NE_SSL_UNTRUSTED
41           The Certificate Authority which signed the certificate is not
42           trusted.
43
44       Note that if either of the NE_SSL_IDMISMATCH or NE_SSL_UNTRUSTED
45       failures is given, the connection may have been intercepted by a third
46       party, and must not be presumed to be “secure”.
47
48       The cert parameter passed to the callback represents the certificate
49       which was presented by the server. If the server presented a chain of
50       certificates, the chain can be accessed using ne_ssl_cert_signedby. The
51       cert object given is not valid after the callback returns.
52

RETURN VALUE

54       The verification callback must return zero to indicate that the
55       certificate should be trusted; and non-zero otherwise (in which case,
56       the connection will fail).
57

EXAMPLES

59       The following code implements an example verification callback, using
60       the dump_cert function from ne_ssl_cert_subject to display
61       certification information. Notice that the hostname of the server used
62       for the session is passed as the userdata parameter to the callback.
63
64           static int
65           my_verify(void *userdata, int failures, const ne_ssl_certificate *cert)
66           {
67             const char *hostname = userdata;
68
69             dump_cert(cert);
70
71             puts("Certificate verification failed - the connection may have been "
72                  "intercepted by a third party!");
73
74             if (failures & NE_SSL_IDMISMATCH) {
75               const char *id = ne_ssl_cert_identity(cert);
76               if (id)
77                 printf("Server certificate was issued to '%s' not '%s'.\n",
78                        id, hostname);
79               else
80                 printf("The certificate was not issued for '%s'\n", hostname);
81             }
82
83             if (failures & NE_SSL_UNTRUSTED)
84               puts("The certificate is not signed by a trusted Certificate Authority.");
85
86             /* ... check for validity failures ... */
87
88             if (prompt_user())
89               return 1; /* fail verification */
90             else
91               return 0; /* trust the certificate anyway */
92           }
93
94           int
95           main(...)
96           {
97             ne_session *sess = ne_session_create("https", "some.host.name", 443);
98             ne_ssl_set_verify(sess, my_verify, "some.host.name");
99             ...
100           }
101

SEE ALSO

103       ne_ssl_trust_cert, ne_ssl_readable_dname, ne_ssl_cert_subject
104

AUTHOR

106       Joe Orton
107           Author.
108

110neon 0.32.5                     21 January 2023           NE_SSL_SET_VERIFY(3)
Impressum