1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimSSL_CTX_set_cert_verify_callback - set peer certificate verification procedure 6e71b7053SJung-uk Kim 7e71b7053SJung-uk Kim=head1 SYNOPSIS 8e71b7053SJung-uk Kim 9e71b7053SJung-uk Kim #include <openssl/ssl.h> 10e71b7053SJung-uk Kim 11e71b7053SJung-uk Kim void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, 12e71b7053SJung-uk Kim int (*callback)(X509_STORE_CTX *, void *), 13e71b7053SJung-uk Kim void *arg); 14e71b7053SJung-uk Kim 15e71b7053SJung-uk Kim=head1 DESCRIPTION 16e71b7053SJung-uk Kim 17e71b7053SJung-uk KimSSL_CTX_set_cert_verify_callback() sets the verification callback function for 18e71b7053SJung-uk KimI<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at 19e71b7053SJung-uk Kimthe time when L<SSL_new(3)> is called. 20e71b7053SJung-uk Kim 21e71b7053SJung-uk Kim=head1 NOTES 22e71b7053SJung-uk Kim 23*b077aed3SPierre ProncheryWhen a peer certificate has been received during a SSL/TLS handshake, 24*b077aed3SPierre Proncherya verification function is called regardless of the verification mode. 25*b077aed3SPierre ProncheryIf the application does not explicitly specify a verification callback function, 26*b077aed3SPierre Proncherythe built-in verification function is used. 27e71b7053SJung-uk KimIf a verification callback I<callback> is specified via 28e71b7053SJung-uk KimSSL_CTX_set_cert_verify_callback(), the supplied callback function is called 29*b077aed3SPierre Proncheryinstead with the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). 30*b077aed3SPierre ProncheryThe argument I<arg> is specified by the application when setting I<callback>. 31*b077aed3SPierre ProncheryBy setting I<callback> to NULL, the default behaviour is restored. 32e71b7053SJung-uk Kim 33*b077aed3SPierre ProncheryI<callback> should return 1 to indicate verification success 34*b077aed3SPierre Proncheryand 0 to indicate verification failure. 35*b077aed3SPierre ProncheryIn server mode, a return value of 0 leads to handshake failure. 36*b077aed3SPierre ProncheryIn client mode, the behaviour is as follows. 37*b077aed3SPierre ProncheryAll values, including 0, are ignored 38*b077aed3SPierre Proncheryif the verification mode is B<SSL_VERIFY_NONE>. 39*b077aed3SPierre ProncheryOtherwise, when the return value is less than or equal to 0, the handshake will 40*b077aed3SPierre Proncheryfail. 41e71b7053SJung-uk Kim 42*b077aed3SPierre ProncheryIn client mode I<callback> may also call the L<SSL_set_retry_verify(3)> 43*b077aed3SPierre Proncheryfunction on the B<SSL> object set in the I<x509_store_ctx> ex data (see 44*b077aed3SPierre ProncheryL<SSL_get_ex_data_X509_STORE_CTX_idx(3)>) and return 1. This would be 45*b077aed3SPierre Proncherytypically done in case the certificate verification was not yet able 46*b077aed3SPierre Proncheryto succeed. This makes the handshake suspend and return control to the 47*b077aed3SPierre Proncherycalling application with B<SSL_ERROR_WANT_RETRY_VERIFY>. The app can for 48*b077aed3SPierre Proncheryinstance fetch further certificates or cert status information needed for 49*b077aed3SPierre Proncherythe verification. Calling L<SSL_connect(3)> again resumes the connection 50*b077aed3SPierre Proncheryattempt by retrying the server certificate verification step. 51*b077aed3SPierre ProncheryThis process may even be repeated if need be. 52*b077aed3SPierre Pronchery 53*b077aed3SPierre ProncheryIn any case a viable verification result value must be reflected 54*b077aed3SPierre Proncheryin the B<error> member of I<x509_store_ctx>, 55*b077aed3SPierre Proncherywhich can be done using L<X509_STORE_CTX_set_error(3)>. 56*b077aed3SPierre ProncheryThis is particularly important in case 57*b077aed3SPierre Proncherythe I<callback> allows the connection to continue (by returning 1). 58*b077aed3SPierre ProncheryNote that the verification status in the store context is a possibly durable 59*b077aed3SPierre Proncheryindication of the chain's validity! 60*b077aed3SPierre ProncheryThis gets recorded in the SSL session (and thus also in session tickets) 61*b077aed3SPierre Proncheryand the validity of the originally presented chain is then visible 62*b077aed3SPierre Proncheryon resumption, even though no chain is presented int that case. 63*b077aed3SPierre ProncheryMoreover, the calling application will be informed about the detailed result of 64*b077aed3SPierre Proncherythe verification procedure and may elect to base further decisions on it. 65e71b7053SJung-uk Kim 66e71b7053SJung-uk KimWithin I<x509_store_ctx>, I<callback> has access to the I<verify_callback> 67e71b7053SJung-uk Kimfunction set using L<SSL_CTX_set_verify(3)>. 68e71b7053SJung-uk Kim 69e71b7053SJung-uk Kim=head1 RETURN VALUES 70e71b7053SJung-uk Kim 71e71b7053SJung-uk KimSSL_CTX_set_cert_verify_callback() does not return a value. 72e71b7053SJung-uk Kim 73e71b7053SJung-uk Kim=head1 WARNINGS 74e71b7053SJung-uk Kim 75e71b7053SJung-uk KimDo not mix the verification callback described in this function with the 76e71b7053SJung-uk KimB<verify_callback> function called during the verification process. The 77e71b7053SJung-uk Kimlatter is set using the L<SSL_CTX_set_verify(3)> 78e71b7053SJung-uk Kimfamily of functions. 79e71b7053SJung-uk Kim 80e71b7053SJung-uk KimProviding a complete verification procedure including certificate purpose 81e71b7053SJung-uk Kimsettings etc is a complex task. The built-in procedure is quite powerful 82e71b7053SJung-uk Kimand in most cases it should be sufficient to modify its behaviour using 83e71b7053SJung-uk Kimthe B<verify_callback> function. 84e71b7053SJung-uk Kim 85e71b7053SJung-uk Kim=head1 BUGS 86e71b7053SJung-uk Kim 87e71b7053SJung-uk KimSSL_CTX_set_cert_verify_callback() does not provide diagnostic information. 88e71b7053SJung-uk Kim 89e71b7053SJung-uk Kim=head1 SEE ALSO 90e71b7053SJung-uk Kim 91e71b7053SJung-uk KimL<ssl(7)>, L<SSL_CTX_set_verify(3)>, 92*b077aed3SPierre ProncheryL<X509_STORE_CTX_set_error(3)>, 93e71b7053SJung-uk KimL<SSL_get_verify_result(3)>, 94*b077aed3SPierre ProncheryL<SSL_set_retry_verify(3)>, 95e71b7053SJung-uk KimL<SSL_CTX_load_verify_locations(3)> 96e71b7053SJung-uk Kim 97e71b7053SJung-uk Kim=head1 COPYRIGHT 98e71b7053SJung-uk Kim 99*b077aed3SPierre ProncheryCopyright 2001-2022 The OpenSSL Project Authors. All Rights Reserved. 100e71b7053SJung-uk Kim 101*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 102e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 103e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 104e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 105e71b7053SJung-uk Kim 106e71b7053SJung-uk Kim=cut 107