Loading doc/ssl/SSL_CTX_set_cert_verify_callback.pod 0 → 100644 +75 −0 Original line number Diff line number Diff line =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 doc/ssl/SSL_CTX_set_verify.pod +12 −2 Original line number Diff line number Diff line Loading @@ -59,14 +59,14 @@ The handshake will be continued regardless of the verification result. B<Server mode:> the server sends a client certificate request to the client. The certificate returned (if any) is checked. If the verification process fails as indicated by B<verify_callback>, the TLS/SSL handshake is fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. The behaviour can be controlled by the additional SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. B<Client mode:> the server certificate is verified. If the verification process fails as indicated by B<verify_callback>, the TLS/SSL handshake is fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. If no server certificate is sent, because an anonymous cipher is used, SSL_VERIFY_PEER is ignored. Loading @@ -92,6 +92,15 @@ B<Client mode:> ignored Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be set at any time. The actual verification procedure is performed either using the built-in verification procedure or using another application provided verification function set with L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>. The following descriptions apply in the case of the built-in procedure. An application provided procedure also has access to the verify depth information and the verify_callback() function, but the way this information is used may be different. SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up to which depth certificates in a chain are used during the verification procedure. If the certificate chain is longer than allowed, the certificates Loading Loading @@ -278,6 +287,7 @@ L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(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)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> Loading doc/ssl/ssl.pod +2 −1 Original line number Diff line number Diff line Loading @@ -299,7 +299,7 @@ protocol context defined in the B<SSL_CTX> structure. =item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); =item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(SSL_CTX *), char *arg) =item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg) =item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); Loading Loading @@ -663,6 +663,7 @@ L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, L<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>, L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>, L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, Loading Loading
doc/ssl/SSL_CTX_set_cert_verify_callback.pod 0 → 100644 +75 −0 Original line number Diff line number Diff line =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
doc/ssl/SSL_CTX_set_verify.pod +12 −2 Original line number Diff line number Diff line Loading @@ -59,14 +59,14 @@ The handshake will be continued regardless of the verification result. B<Server mode:> the server sends a client certificate request to the client. The certificate returned (if any) is checked. If the verification process fails as indicated by B<verify_callback>, the TLS/SSL handshake is fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. The behaviour can be controlled by the additional SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. B<Client mode:> the server certificate is verified. If the verification process fails as indicated by B<verify_callback>, the TLS/SSL handshake is fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. If no server certificate is sent, because an anonymous cipher is used, SSL_VERIFY_PEER is ignored. Loading @@ -92,6 +92,15 @@ B<Client mode:> ignored Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be set at any time. The actual verification procedure is performed either using the built-in verification procedure or using another application provided verification function set with L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>. The following descriptions apply in the case of the built-in procedure. An application provided procedure also has access to the verify depth information and the verify_callback() function, but the way this information is used may be different. SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up to which depth certificates in a chain are used during the verification procedure. If the certificate chain is longer than allowed, the certificates Loading Loading @@ -278,6 +287,7 @@ L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(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)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> Loading
doc/ssl/ssl.pod +2 −1 Original line number Diff line number Diff line Loading @@ -299,7 +299,7 @@ protocol context defined in the B<SSL_CTX> structure. =item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); =item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(SSL_CTX *), char *arg) =item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg) =item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); Loading Loading @@ -663,6 +663,7 @@ L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, L<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>, L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>, L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, Loading
