mirror of
https://github.com/openssl/openssl.git
synced 2025-01-12 13:36:28 +08:00
0c3eb2793b
The client-side cert verification callback function may not only return as usual for success or 0 for failure, but also -1, typically on failure verifying the server certificate. This makes the handshake suspend and return control to the calling application with SSL_ERROR_WANT_RETRY_VERIFY. The app can for instance fetch further certificates or cert status information needed for the verification. Calling SSL_connect() again resumes the connection attempt by retrying the server certificate verification step. This process may even be repeated if need be. The core implementation of the feature is in ssl/statem/statem_clnt.c, splitting tls_process_server_certificate() into a preparation step that just copies the certificates received from the server to s->session->peer_chain (rather than having them in a local variable at first) and returns to the state machine, and a post-processing step in tls_post_process_server_certificate() that can be repeated: Try verifying the current contents of s->session->peer_chain basically as before, but give the verification callback function the chance to pause connecting and make the TLS state machine later call tls_post_process_server_certificate() again. Otherwise processing continues as usual. The documentation of the new feature is added to SSL_CTX_set_cert_verify_callback.pod and SSL_want.pod. This adds two tests: * A generic test in test/helpers/handshake.c on the usability of the new server cert verification retry feature. It is triggered via test/ssl-tests/03-custom_verify.cnf.in (while the bulky auto- generated changes to test/ssl-tests/03-custom_verify.cnf can be basically ignored). * A test in test/sslapitest.c that demonstrates the effectiveness of the approach for augmenting the cert chain provided by the server in between SSL_connect() calls. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/13906)
93 lines
3.4 KiB
Plaintext
93 lines
3.4 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/ssl.h>
|
|
|
|
void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx,
|
|
int (*callback)(X509_STORE_CTX *, void *),
|
|
void *arg);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
SSL_CTX_set_cert_verify_callback() sets the verification callback function for
|
|
I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at
|
|
the time when L<SSL_new(3)> is called.
|
|
|
|
=head1 NOTES
|
|
|
|
Whenever a certificate is verified during a SSL/TLS handshake, a verification
|
|
function is called. If the application does not explicitly specify a
|
|
verification callback function, the built-in verification function is used.
|
|
If a verification callback I<callback> is specified via
|
|
SSL_CTX_set_cert_verify_callback(), the supplied callback function is called
|
|
instead. By setting I<callback> to NULL, the default behaviour is restored.
|
|
|
|
When the verification must be performed, I<callback> will be called with
|
|
the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The
|
|
argument I<arg> is specified by the application when setting I<callback>.
|
|
|
|
I<callback> should return 1 to indicate verification success and 0 to
|
|
indicate verification failure. If SSL_VERIFY_PEER is set and I<callback>
|
|
returns 0, the handshake will fail.
|
|
|
|
In client mode I<callback> may also return -1,
|
|
typically on failure verifying the server certificate.
|
|
This makes the handshake suspend and return control to the calling application
|
|
with B<SSL_ERROR_WANT_RETRY_VERIFY>.
|
|
The app can for instance fetch further certificates or cert status information
|
|
needed for the verification.
|
|
Calling L<SSL_connect(3)> again resumes the connection attempt
|
|
by retrying the server certificate verification step.
|
|
This process may even be repeated if need be.
|
|
|
|
As the verification procedure may
|
|
allow the connection to continue in the case of failure (by always
|
|
returning 1) the verification result must be set in any case using the
|
|
B<error> member of I<x509_store_ctx> so that the calling application
|
|
will be informed about the detailed result of the verification procedure!
|
|
|
|
Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
|
|
function set using L<SSL_CTX_set_verify(3)>.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
SSL_CTX_set_cert_verify_callback() does not return a value.
|
|
|
|
=head1 WARNINGS
|
|
|
|
Do not mix the verification callback described in this function with the
|
|
B<verify_callback> function called during the verification process. The
|
|
latter is set using the L<SSL_CTX_set_verify(3)>
|
|
family of functions.
|
|
|
|
Providing a complete verification procedure including certificate purpose
|
|
settings etc is a complex task. The built-in procedure is quite powerful
|
|
and in most cases it should be sufficient to modify its behaviour using
|
|
the B<verify_callback> function.
|
|
|
|
=head1 BUGS
|
|
|
|
SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<ssl(7)>, L<SSL_CTX_set_verify(3)>,
|
|
L<SSL_get_verify_result(3)>,
|
|
L<SSL_CTX_load_verify_locations(3)>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|