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 less than or equal to 0, the handshake will
40fail.
41
42In client mode I<callback> may also call the L<SSL_set_retry_verify(3)>
43function on the B<SSL> object set in the I<x509_store_ctx> ex data (see
44L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>) and return 1. This would be
45typically done in case the certificate verification was not yet able
46to succeed. This makes the handshake suspend and return control to the
47calling application with B<SSL_ERROR_WANT_RETRY_VERIFY>. The app can for
48instance fetch further certificates or cert status information needed for
49the verification. Calling L<SSL_connect(3)> again resumes the connection
50attempt by retrying the server certificate verification step.
51This process may even be repeated if need be.
52
53In any case a viable verification result value must be reflected
54in the B<error> member of I<x509_store_ctx>,
55which can be done using L<X509_STORE_CTX_set_error(3)>.
56This is particularly important in case
57the I<callback> allows the connection to continue (by returning 1).
58Note that the verification status in the store context is a possibly durable
59indication of the chain's validity!
60This gets recorded in the SSL session (and thus also in session tickets)
61and the validity of the originally presented chain is then visible
62on resumption, even though no chain is presented int that case.
63Moreover, the calling application will be informed about the detailed result of
64the verification procedure and may elect to base further decisions on it.
65
66Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
67function set using L<SSL_CTX_set_verify(3)>.
68
69=head1 RETURN VALUES
70
71SSL_CTX_set_cert_verify_callback() does not return a value.
72
73=head1 WARNINGS
74
75Do not mix the verification callback described in this function with the
76B<verify_callback> function called during the verification process. The
77latter is set using the L<SSL_CTX_set_verify(3)>
78family of functions.
79
80Providing a complete verification procedure including certificate purpose
81settings etc is a complex task. The built-in procedure is quite powerful
82and in most cases it should be sufficient to modify its behaviour using
83the B<verify_callback> function.
84
85=head1 BUGS
86
87SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
88
89=head1 SEE ALSO
90
91L<ssl(7)>, L<SSL_CTX_set_verify(3)>,
92L<X509_STORE_CTX_set_error(3)>,
93L<SSL_get_verify_result(3)>,
94L<SSL_set_retry_verify(3)>,
95L<SSL_CTX_load_verify_locations(3)>
96
97=head1 COPYRIGHT
98
99Copyright 2001-2022 The OpenSSL Project Authors. All Rights Reserved.
100
101Licensed under the Apache License 2.0 (the "License").  You may not use
102this file except in compliance with the License.  You can obtain a copy
103in the file LICENSE in the source distribution or at
104L<https://www.openssl.org/source/license.html>.
105
106=cut
107