diff options
Diffstat (limited to 'crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod')
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 0000000..723fc14 --- /dev/null +++ b/crypto/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)(), + char *arg); + int (*callback)(); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_verify_callback() sets the verification callback function for +B<ctx>. SSL objects, that are created from B<ctx> inherit the setting valid at +the time, L<SSL_new(3)|SSL_new(3)> is called. B<arg> is currently ignored. + +=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 B<callback> is specified via +SSL_CTX_set_cert_verify_callback(), the supplied callback function is called +instead. By setting B<callback> to NULL, the default behaviour is restored. + +When the verification must be performed, B<callback> will be called with +the argument callback(X509_STORE_CTX *x509_store_ctx). The arguments B<arg> +that can be specified when setting B<callback> are currently ignored. + +B<callback> should return 1 to indicate verification success and 0 to +indicate verification failure. If SSL_VERIFY_PEER is set and B<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 B<x509_store_ctx>, so that the calling application will be informed +about the detailed result of the verification procedure! + +Within B<x509_store_ctx>, B<callback> has access to the B<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 + +It is possible to specify arguments to be passed to the verification callback. +Currently they are however not passed but ignored. + +The B<callback> function is not specified via a prototype, so that no +type checking takes place. + +=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)> + +=cut |