1=pod
2
3=head1 NAME
4
5SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure
6
7=head1 SYNOPSIS
8
9 #include <openssl/ssl.h>
10
11 void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx,
12                                       int (*callback)(X509_STORE_CTX *, void *),
13                                       void *arg);
14
15=head1 DESCRIPTION
16
17SSL_CTX_set_cert_verify_callback() sets the verification callback function for
18I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at
19the time when L<SSL_new(3)> is called.
20
21=head1 NOTES
22
23When a peer certificate has been received during a SSL/TLS handshake,
24a verification function is called regardless of the verification mode.
25If the application does not explicitly specify a verification callback function,
26the built-in verification function is used.
27If a verification callback I<callback> is specified via
28SSL_CTX_set_cert_verify_callback(), the supplied callback function is called
29instead with the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg).
30The argument I<arg> is specified by the application when setting I<callback>.
31By setting I<callback> to NULL, the default behaviour is restored.
32
33I<callback> should return 1 to indicate verification success
34and 0 to indicate verification failure.
35In server mode, a return value of 0 leads to handshake failure.
36In client mode, the behaviour is as follows.
37All values, including 0, are ignored
38if the verification mode is B<SSL_VERIFY_NONE>.
39Otherwise, when the return value is 0, the handshake will fail.
40
41In client mode I<callback> may also return -1,
42typically on failure verifying the server certificate.
43This makes the handshake suspend and return control to the calling application
44with B<SSL_ERROR_WANT_RETRY_VERIFY>.
45The app can for instance fetch further certificates or cert status information
46needed for the verification.
47Calling L<SSL_connect(3)> again resumes the connection attempt
48by retrying the server certificate verification step.
49This process may even be repeated if need be.
50
51In any case a viable verification result value must be reflected
52in the B<error> member of I<x509_store_ctx>,
53which can be done using L<X509_STORE_CTX_set_error(3)>.
54This is particularly important in case
55the I<callback> allows the connection to continue (by returning 1).
56Note that the verification status in the store context is a possibly durable
57indication of the chain's validity!
58This gets recorded in the SSL session (and thus also in session tickets)
59and the validity of the originally presented chain is then visible
60on resumption, even though no chain is presented int that case.
61Moreover, the calling application will be informed about the detailed result of
62the verification procedure and may elect to base further decisions on it.
63
64Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
65function set using L<SSL_CTX_set_verify(3)>.
66
67=head1 RETURN VALUES
68
69SSL_CTX_set_cert_verify_callback() does not return a value.
70
71=head1 WARNINGS
72
73Do not mix the verification callback described in this function with the
74B<verify_callback> function called during the verification process. The
75latter is set using the L<SSL_CTX_set_verify(3)>
76family of functions.
77
78Providing a complete verification procedure including certificate purpose
79settings etc is a complex task. The built-in procedure is quite powerful
80and in most cases it should be sufficient to modify its behaviour using
81the B<verify_callback> function.
82
83=head1 BUGS
84
85SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
86
87=head1 SEE ALSO
88
89L<ssl(7)>, L<SSL_CTX_set_verify(3)>,
90L<X509_STORE_CTX_set_error(3)>,
91L<SSL_get_verify_result(3)>,
92L<SSL_CTX_load_verify_locations(3)>
93
94=head1 COPYRIGHT
95
96Copyright 2001-2021 The OpenSSL Project Authors. All Rights Reserved.
97
98Licensed under the Apache License 2.0 (the "License").  You may not use
99this file except in compliance with the License.  You can obtain a copy
100in the file LICENSE in the source distribution or at
101L<https://www.openssl.org/source/license.html>.
102
103=cut
104