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