Debian Codegraph @

deps/libneon/doc/man/ne_ssl_set_verify.3

raw
1 '\" t
2 .\" Title: ne_ssl_set_verify
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NE_SSL_SET_VERIFY" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ne_ssl_set_verify \- register an SSL certificate verification callback
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <ne_session\&.h>
37 .fi
38 .ft
39 .HP \w'typedef\ int\ ne_ssl_verify_fn('u
40 .BI "typedef int ne_ssl_verify_fn(void\ *" "userdata" ", int\ " "failures" ", const\ ne_ssl_certificate\ *" "cert" ");"
41 .HP \w'void\ ne_ssl_set_verify('u
42 .BI "void ne_ssl_set_verify(ne_session\ *" "session" ", ne_ssl_verify_fn\ " "verify_fn" ", void\ *" "userdata" ");"
43 .SH "DESCRIPTION"
44 .PP
45 To enable manual SSL certificate verification, a callback can be registered using
46 \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
47 ne_ssl_trust_cert), or if the certificate presented is invalid in some way, the connection will fail\&.
48 .PP
49 When the callback is invoked, the
50 \fIfailures\fR
51 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):
52 .PP
53 \fBNE_SSL_NOTYETVALID\fR
54 .RS 4
55 The certificate is not yet valid\&.
56 .RE
57 .PP
58 \fBNE_SSL_EXPIRED\fR
59 .RS 4
60 The certificate has expired\&.
61 .RE
62 .PP
63 \fBNE_SSL_IDMISMATCH\fR
64 .RS 4
65 The hostname used for the session does not match the hostname to which the certificate was issued\&.
66 .RE
67 .PP
68 \fBNE_SSL_UNTRUSTED\fR
69 .RS 4
70 The Certificate Authority which signed the certificate is not trusted\&.
71 .RE
72 .PP
73 Note that if either of the
74 \fBNE_SSL_IDMISMATCH\fR
75 or
76 \fBNE_SSL_UNTRUSTED\fR
77 failures is given, the connection may have been intercepted by a third party, and must not be presumed to be
78 \(lqsecure\(rq\&.
79 .PP
80 The
81 \fIcert\fR
82 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
83 ne_ssl_cert_signedby\&. The
84 \fIcert\fR
85 object given is not valid after the callback returns\&.
86 .SH "RETURN VALUE"
87 .PP
88 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)\&.
89 .SH "EXAMPLES"
90 .PP
91 The following code implements an example verification callback, using the
92 \fBdump_cert\fR
93 function from
94 ne_ssl_cert_subject
95 to display certification information\&. Notice that the hostname of the server used for the session is passed as the
96 \fIuserdata\fR
97 parameter to the callback\&.
98 .sp
99 .if n \{\
100 .RS 4
101 .\}
102 .nf
103 static int
104 my_verify(void *userdata, int failures, const ne_ssl_certificate *cert)
105 {
106 const char *hostname = userdata;
107
108 dump_cert(cert);
109
110 puts("Certificate verification failed \- the connection may have been "
111 "intercepted by a third party!");
112
113 if (failures & NE_SSL_IDMISMATCH) {
114 const char *id = ne_ssl_cert_identity(cert);
115 if (id)
116 printf("Server certificate was issued to \*(Aq%s\*(Aq not \*(Aq%s\*(Aq\&.\en",
117 id, hostname);
118 else
119 printf("The certificate was not issued for \*(Aq%s\*(Aq\en", hostname);
120 }
121
122 if (failures & NE_SSL_UNTRUSTED)
123 puts("The certificate is not signed by a trusted Certificate Authority\&.");
124
125 /* \&.\&.\&. check for validity failures \&.\&.\&. */
126
127 if (prompt_user())
128 return 1; /* fail verification */
129 else
130 return 0; /* trust the certificate anyway */
131 }
132
133 int
134 main(\&.\&.\&.)
135 {
136 ne_session *sess = ne_session_create("https", "some\&.host\&.name", 443);
137 ne_ssl_set_verify(sess, my_verify, "some\&.host\&.name");
138 \&.\&.\&.
139 }
140 .fi
141 .if n \{\
142 .RE
143 .\}
144 .SH "SEE ALSO"
145 .PP
146 ne_ssl_trust_cert,
147 ne_ssl_readable_dname,
148 ne_ssl_cert_subject
149 .SH "AUTHOR"
150 .PP
151 \fBJoe Orton\fR <\&[email protected]\&>
152 .RS 4
153 Author.
154 .RE
155 .SH "COPYRIGHT"
156 .br