diff options
Diffstat (limited to 'openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod')
-rw-r--r-- | openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 000000000..c0f4f8570 --- /dev/null +++ b/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod @@ -0,0 +1,75 @@ +=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)|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. As the verification procedure may +allow to continue the connection in 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)|SSL_CTX_set_verify(3)>. + +=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)|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 + +=head1 RETURN VALUES + +SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, +L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> + +=head1 HISTORY + +Previous to OpenSSL 0.9.7, the I<arg> argument to B<SSL_CTX_set_cert_verify_callback> +was ignored, and I<callback> was called simply as + int (*callback)(X509_STORE_CTX *) +To compile software written for previous versions of OpenSSL, a dummy +argument will have to be added to I<callback>. + +=cut |