Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_cert_verify_callback.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_CERT_VERIFY_CALLBACK 3SSL"
58 .TH SSL_CTX_SET_CERT_VERIFY_CALLBACK 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_cert_verify_callback \- set peer certificate verification procedure
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx,
71 \& int (*callback)(X509_STORE_CTX *, void *),
72 \& void *arg);
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 \&\fBSSL_CTX_set_cert_verify_callback()\fR sets the verification callback function for
77 \&\fIctx\fR. SSL objects that are created from \fIctx\fR inherit the setting valid at
78 the time when \fBSSL_new\fR\|(3) is called.
79 .SH NOTES
80 .IX Header "NOTES"
81 When a peer certificate has been received during an SSL/TLS handshake,
82 a verification function is called regardless of the verification mode.
83 If the application does not explicitly specify a verification callback function,
84 the built-in verification function is used.
85 If a verification callback \fIcallback\fR is specified via
86 \&\fBSSL_CTX_set_cert_verify_callback()\fR, the supplied callback function is called
87 instead with the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg).
88 The argument \fIarg\fR is specified by the application when setting \fIcallback\fR.
89 By setting \fIcallback\fR to NULL, the default behaviour is restored.
90 .PP
91 \&\fIcallback\fR should return 1 to indicate verification success
92 and 0 to indicate verification failure.
93 In server mode, a return value of 0 leads to handshake failure.
94 In client mode, the behaviour is as follows.
95 All values, including 0, are ignored
96 if the verification mode is \fBSSL_VERIFY_NONE\fR.
97 Otherwise, when the return value is less than or equal to 0, the handshake will
98 fail.
99 .PP
100 In client mode \fIcallback\fR may also call the \fBSSL_set_retry_verify\fR\|(3)
101 function on the \fBSSL\fR object set in the \fIx509_store_ctx\fR ex data (see
102 \&\fBSSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3)) and return 1. This would be
103 typically done in case the certificate verification was not yet able
104 to succeed. This makes the handshake suspend and return control to the
105 calling application with \fBSSL_ERROR_WANT_RETRY_VERIFY\fR. The app can for
106 instance fetch further certificates or cert status information needed for
107 the verification. Calling \fBSSL_connect\fR\|(3) again resumes the connection
108 attempt by retrying the server certificate verification step.
109 This process may even be repeated if need be.
110 .PP
111 In any case a viable verification result value must be reflected
112 in the \fBerror\fR member of \fIx509_store_ctx\fR,
113 which can be done using \fBX509_STORE_CTX_set_error\fR\|(3).
114 This is particularly important in case
115 the \fIcallback\fR allows the connection to continue (by returning 1).
116 Note that the verification status in the store context is a possibly durable
117 indication of the chain's validity!
118 This gets recorded in the SSL session (and thus also in session tickets)
119 and the validity of the originally presented chain is then visible
120 on resumption, even though no chain is presented int that case.
121 Moreover, the calling application will be informed about the detailed result of
122 the verification procedure and may elect to base further decisions on it.
123 .PP
124 \&\fIcallback\fR may call \fBX509_verify_cert\fR\|(3) to run the built-in verification
125 function. This may be useful if application wishes to dynamically reconfigure
126 \&\fIx509_store_ctx\fR before verification, or postprocess the result. In this case,
127 \&\fBX509_verify_cert\fR\|(3) will set the \fBerror\fR member as described above.
128 .PP
129 Within \fIx509_store_ctx\fR, \fIcallback\fR has access to the \fIverify_callback\fR
130 function set using \fBSSL_CTX_set_verify\fR\|(3).
131 .SH "RETURN VALUES"
132 .IX Header "RETURN VALUES"
133 \&\fBSSL_CTX_set_cert_verify_callback()\fR does not return a value.
134 .SH WARNINGS
135 .IX Header "WARNINGS"
136 Do not mix the verification callback described in this function with the
137 \&\fBverify_callback\fR function called during the verification process. The
138 latter is set using the \fBSSL_CTX_set_verify\fR\|(3)
139 family of functions.
140 .PP
141 Providing a complete verification procedure including certificate purpose
142 settings etc is a complex task. The built-in procedure is quite powerful
143 and in most cases it should be sufficient to modify its behaviour using
144 the \fBverify_callback\fR function.
145 .SH BUGS
146 .IX Header "BUGS"
147 \&\fBSSL_CTX_set_cert_verify_callback()\fR does not provide diagnostic information.
148 .SH "SEE ALSO"
149 .IX Header "SEE ALSO"
150 \&\fBssl\fR\|(7), \fBSSL_CTX_set_verify\fR\|(3),
151 \&\fBX509_STORE_CTX_set_error\fR\|(3),
152 \&\fBSSL_get_verify_result\fR\|(3),
153 \&\fBSSL_set_retry_verify\fR\|(3),
154 \&\fBSSL_CTX_load_verify_locations\fR\|(3)
155 .SH COPYRIGHT
156 .IX Header "COPYRIGHT"
157 Copyright 2001\-2022 The OpenSSL Project Authors. All Rights Reserved.
158 .PP
159 Licensed under the Apache License 2.0 (the "License"). You may not use
160 this file except in compliance with the License. You can obtain a copy
161 in the file LICENSE in the source distribution or at
162 <https://www.openssl.org/source/license.html>.