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