diff options
author | Lutz Jänicke <jaenicke@openssl.org> | 2001-08-23 15:00:11 +0000 |
---|---|---|
committer | Lutz Jänicke <jaenicke@openssl.org> | 2001-08-23 15:00:11 +0000 |
commit | c4068186acec0f5cd370f7b5772b41f215903234 (patch) | |
tree | cd807084397cc768682f36e9a67da1988e97e051 | |
parent | 0a93a68020b45454bbd6fc48339748fd3ac0042c (diff) |
As discussed recently on openssl-users.
-rw-r--r-- | doc/ssl/SSL_CTX_set_cert_verify_callback.pod | 75 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_verify.pod | 14 | ||||
-rw-r--r-- | doc/ssl/ssl.pod | 3 |
3 files changed, 89 insertions, 3 deletions
diff --git a/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 0000000000..723fc140d4 --- /dev/null +++ b/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 diff --git a/doc/ssl/SSL_CTX_set_verify.pod b/doc/ssl/SSL_CTX_set_verify.pod index fc0b76118f..5bb21ca535 100644 --- a/doc/ssl/SSL_CTX_set_verify.pod +++ b/doc/ssl/SSL_CTX_set_verify.pod @@ -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. @@ -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 @@ -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)> diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index e88256a8d7..816f1f6f87 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -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); @@ -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)>, |