Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_verify.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
e056f0e0 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
e056f0e0 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
e056f0e0 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
e056f0e0
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
e056f0e0 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
e056f0e0
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
e056f0e0
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
e056f0e0 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
e056f0e0 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
e056f0e0
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
e056f0e0
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
e056f0e0
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
e056f0e0
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
e056f0e0
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
e056f0e0
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
e056f0e0 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
e056f0e0
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
e056f0e0
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
e056f0e0 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
e056f0e0
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
e056f0e0
JR
124.\" ========================================================================
125.\"
126.IX Title "SSL_CTX_set_verify 3"
e3261593 127.TH SSL_CTX_set_verify 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth \- set peer certificate verification parameters
134.SH "SYNOPSIS"
e056f0e0 135.IX Header "SYNOPSIS"
984263bc
MD
136.Vb 1
137\& #include <openssl/ssl.h>
e257b235 138\&
984263bc
MD
139\& void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
140\& int (*verify_callback)(int, X509_STORE_CTX *));
141\& void SSL_set_verify(SSL *s, int mode,
142\& int (*verify_callback)(int, X509_STORE_CTX *));
143\& void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth);
144\& void SSL_set_verify_depth(SSL *s, int depth);
e257b235 145\&
984263bc
MD
146\& int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
147.Ve
148.SH "DESCRIPTION"
e056f0e0
JR
149.IX Header "DESCRIPTION"
150\&\fISSL_CTX_set_verify()\fR sets the verification flags for \fBctx\fR to be \fBmode\fR and
984263bc 151specifies the \fBverify_callback\fR function to be used. If no callback function
e056f0e0 152shall be specified, the \s-1NULL\s0 pointer can be used for \fBverify_callback\fR.
984263bc 153.PP
e056f0e0 154\&\fISSL_set_verify()\fR sets the verification flags for \fBssl\fR to be \fBmode\fR and
984263bc 155specifies the \fBverify_callback\fR function to be used. If no callback function
e056f0e0 156shall be specified, the \s-1NULL\s0 pointer can be used for \fBverify_callback\fR. In
984263bc
MD
157this case last \fBverify_callback\fR set specifically for this \fBssl\fR remains. If
158no special \fBcallback\fR was set before, the default callback for the underlying
405d0527 159\&\fBctx\fR is used, that was valid at the time \fBssl\fR was created with
e056f0e0 160\&\fISSL_new\fR\|(3).
984263bc 161.PP
e056f0e0
JR
162\&\fISSL_CTX_set_verify_depth()\fR sets the maximum \fBdepth\fR for the certificate chain
163verification that shall be allowed for \fBctx\fR. (See the \s-1BUGS\s0 section.)
984263bc 164.PP
e056f0e0
JR
165\&\fISSL_set_verify_depth()\fR sets the maximum \fBdepth\fR for the certificate chain
166verification that shall be allowed for \fBssl\fR. (See the \s-1BUGS\s0 section.)
984263bc 167.SH "NOTES"
e056f0e0 168.IX Header "NOTES"
984263bc
MD
169The verification of certificates can be controlled by a set of logically
170or'ed \fBmode\fR flags:
e056f0e0
JR
171.IP "\s-1SSL_VERIFY_NONE\s0" 4
172.IX Item "SSL_VERIFY_NONE"
173\&\fBServer mode:\fR the server will not send a client certificate request to the
984263bc
MD
174client, so the client will not send a certificate.
175.Sp
e056f0e0 176\&\fBClient mode:\fR if not using an anonymous cipher (by default disabled), the
984263bc
MD
177server will send a certificate which will be checked. The result of the
178certificate verification process can be checked after the \s-1TLS/SSL\s0 handshake
e056f0e0 179using the \fISSL_get_verify_result\fR\|(3) function.
984263bc 180The handshake will be continued regardless of the verification result.
e056f0e0
JR
181.IP "\s-1SSL_VERIFY_PEER\s0" 4
182.IX Item "SSL_VERIFY_PEER"
183\&\fBServer mode:\fR the server sends a client certificate request to the client.
984263bc
MD
184The certificate returned (if any) is checked. If the verification process
185fails, the \s-1TLS/SSL\s0 handshake is
186immediately terminated with an alert message containing the reason for
187the verification failure.
188The behaviour can be controlled by the additional
e056f0e0 189\&\s-1SSL_VERIFY_FAIL_IF_NO_PEER_CERT\s0 and \s-1SSL_VERIFY_CLIENT_ONCE\s0 flags.
984263bc 190.Sp
e056f0e0 191\&\fBClient mode:\fR the server certificate is verified. If the verification process
984263bc
MD
192fails, the \s-1TLS/SSL\s0 handshake is
193immediately terminated with an alert message containing the reason for
194the verification failure. If no server certificate is sent, because an
195anonymous cipher is used, \s-1SSL_VERIFY_PEER\s0 is ignored.
e056f0e0
JR
196.IP "\s-1SSL_VERIFY_FAIL_IF_NO_PEER_CERT\s0" 4
197.IX Item "SSL_VERIFY_FAIL_IF_NO_PEER_CERT"
198\&\fBServer mode:\fR if the client did not return a certificate, the \s-1TLS/SSL\s0
984263bc
MD
199handshake is immediately terminated with a \*(L"handshake failure\*(R" alert.
200This flag must be used together with \s-1SSL_VERIFY_PEER\s0.
201.Sp
e056f0e0
JR
202\&\fBClient mode:\fR ignored
203.IP "\s-1SSL_VERIFY_CLIENT_ONCE\s0" 4
204.IX Item "SSL_VERIFY_CLIENT_ONCE"
205\&\fBServer mode:\fR only request a client certificate on the initial \s-1TLS/SSL\s0
984263bc
MD
206handshake. Do not ask for a client certificate again in case of a
207renegotiation. This flag must be used together with \s-1SSL_VERIFY_PEER\s0.
208.Sp
e056f0e0 209\&\fBClient mode:\fR ignored
984263bc
MD
210.PP
211Exactly one of the \fBmode\fR flags \s-1SSL_VERIFY_NONE\s0 and \s-1SSL_VERIFY_PEER\s0 must be
212set at any time.
213.PP
214The actual verification procedure is performed either using the built-in
215verification procedure or using another application provided verification
216function set with
e056f0e0 217\&\fISSL_CTX_set_cert_verify_callback\fR\|(3).
984263bc
MD
218The following descriptions apply in the case of the built-in procedure. An
219application provided procedure also has access to the verify depth information
220and the \fIverify_callback()\fR function, but the way this information is used
221may be different.
222.PP
e056f0e0 223\&\fISSL_CTX_set_verify_depth()\fR and \fISSL_set_verify_depth()\fR set the limit up
984263bc
MD
224to which depth certificates in a chain are used during the verification
225procedure. If the certificate chain is longer than allowed, the certificates
226above the limit are ignored. Error messages are generated as if these
227certificates would not be present, most likely a
228X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
229The depth count is \*(L"level 0:peer certificate\*(R", \*(L"level 1: \s-1CA\s0 certificate\*(R",
e056f0e0 230\&\*(L"level 2: higher level \s-1CA\s0 certificate\*(R", and so on. Setting the maximum
984263bc
MD
231depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9,
232allowing for the peer certificate and additional 9 \s-1CA\s0 certificates.
233.PP
234The \fBverify_callback\fR function is used to control the behaviour when the
e056f0e0 235\&\s-1SSL_VERIFY_PEER\s0 flag is set. It must be supplied by the application and
984263bc
MD
236receives two arguments: \fBpreverify_ok\fR indicates, whether the verification of
237the certificate in question was passed (preverify_ok=1) or not
238(preverify_ok=0). \fBx509_ctx\fR is a pointer to the complete context used
239for the certificate chain verification.
240.PP
241The certificate chain is checked starting with the deepest nesting level
242(the root \s-1CA\s0 certificate) and worked upward to the peer's certificate.
243At each level signatures and issuer attributes are checked. Whenever
244a verification error is found, the error number is stored in \fBx509_ctx\fR
245and \fBverify_callback\fR is called with \fBpreverify_ok\fR=0. By applying
246X509_CTX_store_* functions \fBverify_callback\fR can locate the certificate
247in question and perform additional steps (see \s-1EXAMPLES\s0). If no error is
248found for a certificate, \fBverify_callback\fR is called with \fBpreverify_ok\fR=1
249before advancing to the next level.
250.PP
251The return value of \fBverify_callback\fR controls the strategy of the further
252verification process. If \fBverify_callback\fR returns 0, the verification
253process is immediately stopped with \*(L"verification failed\*(R" state. If
e056f0e0 254\&\s-1SSL_VERIFY_PEER\s0 is set, a verification failure alert is sent to the peer and
984263bc
MD
255the \s-1TLS/SSL\s0 handshake is terminated. If \fBverify_callback\fR returns 1,
256the verification process is continued. If \fBverify_callback\fR always returns
a7d27d5a
JR
2571, the \s-1TLS/SSL\s0 handshake will not be terminated with respect to verification
258failures and the connection will be established. The calling process can
259however retrieve the error code of the last verification error using
e056f0e0 260\&\fISSL_get_verify_result\fR\|(3) or by maintaining its
984263bc
MD
261own error storage managed by \fBverify_callback\fR.
262.PP
263If no \fBverify_callback\fR is specified, the default callback will be used.
264Its return value is identical to \fBpreverify_ok\fR, so that any verification
265failure will lead to a termination of the \s-1TLS/SSL\s0 handshake with an
266alert message, if \s-1SSL_VERIFY_PEER\s0 is set.
267.SH "BUGS"
e056f0e0
JR
268.IX Header "BUGS"
269In client mode, it is not checked whether the \s-1SSL_VERIFY_PEER\s0 flag
270is set, but whether \s-1SSL_VERIFY_NONE\s0 is not set. This can lead to
271unexpected behaviour, if the \s-1SSL_VERIFY_PEER\s0 and \s-1SSL_VERIFY_NONE\s0 are not
984263bc
MD
272used as required (exactly one must be set at any time).
273.PP
274The certificate verification depth set with SSL[_CTX]\fI_verify_depth()\fR
275stops the verification at a certain depth. The error message produced
276will be that of an incomplete certificate chain and not
277X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected.
278.SH "RETURN VALUES"
e056f0e0 279.IX Header "RETURN VALUES"
984263bc
MD
280The SSL*_set_verify*() functions do not provide diagnostic information.
281.SH "EXAMPLES"
e056f0e0 282.IX Header "EXAMPLES"
984263bc 283The following code sequence realizes an example \fBverify_callback\fR function
e056f0e0 284that will always continue the \s-1TLS/SSL\s0 handshake regardless of verification
984263bc
MD
285failure, if wished. The callback realizes a verification depth limit with
286more informational output.
287.PP
288All verification errors are printed, informations about the certificate chain
289are printed on request.
290The example is realized for a server that does allow but not require client
291certificates.
292.PP
293The example makes use of the ex_data technique to store application data
e056f0e0
JR
294into/retrieve application data from the \s-1SSL\s0 structure
295(see \fISSL_get_ex_new_index\fR\|(3),
296\&\fISSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3)).
984263bc 297.PP
e257b235 298.Vb 10
984263bc
MD
299\& ...
300\& typedef struct {
301\& int verbose_mode;
302\& int verify_depth;
303\& int always_continue;
304\& } mydata_t;
305\& int mydata_index;
306\& ...
307\& static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
308\& {
309\& char buf[256];
310\& X509 *err_cert;
311\& int err, depth;
312\& SSL *ssl;
313\& mydata_t *mydata;
e257b235 314\&
984263bc
MD
315\& err_cert = X509_STORE_CTX_get_current_cert(ctx);
316\& err = X509_STORE_CTX_get_error(ctx);
317\& depth = X509_STORE_CTX_get_error_depth(ctx);
e257b235 318\&
984263bc
MD
319\& /*
320\& * Retrieve the pointer to the SSL of the connection currently treated
321\& * and the application specific data stored into the SSL object.
322\& */
323\& ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
324\& mydata = SSL_get_ex_data(ssl, mydata_index);
e257b235 325\&
984263bc 326\& X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
e257b235 327\&
984263bc
MD
328\& /*
329\& * Catch a too long certificate chain. The depth limit set using
330\& * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
331\& * that whenever the "depth>verify_depth" condition is met, we
332\& * have violated the limit and want to log this error condition.
333\& * We must do it here, because the CHAIN_TOO_LONG error would not
334\& * be found explicitly; only errors introduced by cutting off the
335\& * additional certificates would be logged.
336\& */
e257b235 337\& if (depth > mydata\->verify_depth) {
984263bc
MD
338\& preverify_ok = 0;
339\& err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
340\& X509_STORE_CTX_set_error(ctx, err);
341\& }
342\& if (!preverify_ok) {
343\& printf("verify error:num=%d:%s:depth=%d:%s\en", err,
344\& X509_verify_cert_error_string(err), depth, buf);
345\& }
e257b235 346\& else if (mydata\->verbose_mode)
984263bc
MD
347\& {
348\& printf("depth=%d:%s\en", depth, buf);
349\& }
e257b235 350\&
984263bc
MD
351\& /*
352\& * At this point, err contains the last verification error. We can use
353\& * it for something special
354\& */
355\& if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT))
356\& {
e257b235 357\& X509_NAME_oneline(X509_get_issuer_name(ctx\->current_cert), buf, 256);
984263bc
MD
358\& printf("issuer= %s\en", buf);
359\& }
e257b235
PA
360\&
361\& if (mydata\->always_continue)
984263bc
MD
362\& return 1;
363\& else
364\& return preverify_ok;
365\& }
366\& ...
e257b235 367\&
984263bc 368\& mydata_t mydata;
e257b235 369\&
984263bc
MD
370\& ...
371\& mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
e257b235 372\&
984263bc
MD
373\& ...
374\& SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
375\& verify_callback);
e257b235 376\&
984263bc
MD
377\& /*
378\& * Let the verify_callback catch the verify_depth error so that we get
379\& * an appropriate error in the logfile.
380\& */
381\& SSL_CTX_set_verify_depth(verify_depth + 1);
e257b235 382\&
984263bc
MD
383\& /*
384\& * Set up the SSL specific data into "mydata" and store it into th SSL
385\& * structure.
386\& */
387\& mydata.verify_depth = verify_depth; ...
388\& SSL_set_ex_data(ssl, mydata_index, &mydata);
e257b235 389\&
984263bc
MD
390\& ...
391\& SSL_accept(ssl); /* check of success left out for clarity */
392\& if (peer = SSL_get_peer_certificate(ssl))
393\& {
394\& if (SSL_get_verify_result(ssl) == X509_V_OK)
395\& {
396\& /* The client sent a certificate which verified OK */
397\& }
398\& }
399.Ve
400.SH "SEE ALSO"
a7d27d5a 401.IX Header "SEE ALSO"
e056f0e0
JR
402\&\fIssl\fR\|(3), \fISSL_new\fR\|(3),
403\&\fISSL_CTX_get_verify_mode\fR\|(3),
404\&\fISSL_get_verify_result\fR\|(3),
405\&\fISSL_CTX_load_verify_locations\fR\|(3),
406\&\fISSL_get_peer_certificate\fR\|(3),
407\&\fISSL_CTX_set_cert_verify_callback\fR\|(3),
408\&\fISSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3),
409\&\fISSL_get_ex_new_index\fR\|(3)