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
12       typedef int ne_ssl_verify_fn (void *userdata, int failures,
13                                      const ne_ssl_certificate *cert);
14
15       void ne_ssl_set_verify (ne_session *session,
16                               ne_ssl_verify_fn verify_fn, void *userdata);
17
18

DESCRIPTION

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

RETURN VALUE

64       The verification callback must return zero to indicate  that  the  cer‐
65       tificate  should be trusted; and non-zero otherwise (in which case, the
66       connection will fail).
67
68

EXAMPLES

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

SEE ALSO

116       ne_ssl_trust_cert(3), ne_ssl_readable_dname(3), ne_ssl_cert_subject(3)
117
118

AUTHOR

120       Joe Orton <neon@webdav.org>.
121
122
123
124neon 0.25.5                     20 January 2006           NE_SSL_SET_VERIFY(3)
Impressum