From c4068186acec0f5cd370f7b5772b41f215903234 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Lutz=20J=C3=A4nicke?= Date: Thu, 23 Aug 2001 15:00:11 +0000 Subject: [PATCH] As discussed recently on openssl-users. --- doc/ssl/SSL_CTX_set_cert_verify_callback.pod | 75 ++++++++++++++++++++ doc/ssl/SSL_CTX_set_verify.pod | 14 +++- doc/ssl/ssl.pod | 3 +- 3 files changed, 89 insertions(+), 3 deletions(-) create mode 100644 doc/ssl/SSL_CTX_set_cert_verify_callback.pod 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 + + 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. SSL objects, that are created from B inherit the setting valid at +the time, L is called. B 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 is specified via +SSL_CTX_set_cert_verify_callback(), the supplied callback function is called +instead. By setting B to NULL, the default behaviour is restored. + +When the verification must be performed, B will be called with +the argument callback(X509_STORE_CTX *x509_store_ctx). The arguments B +that can be specified when setting B are currently ignored. + +B should return 1 to indicate verification success and 0 to +indicate verification failure. If SSL_VERIFY_PEER is set and B +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 +member of B, so that the calling application will be informed +about the detailed result of the verification procedure! + +Within B, B has access to the B +function set using L. + +=head1 WARNINGS + +Do not mix the verification callback described in this function with the +B function called during the verification process. The +latter is set using the L +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 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 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, L, +L, +L + +=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 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, 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 the server certificate is verified. If the verification process -fails as indicated by B, 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 ignored Exactly one of the B 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. +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, L, L, L, +L, L, L 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 structure. =item void B(SSL_CTX *ctx, X509_STORE *cs); -=item void B(SSL_CTX *ctx, int (*cb)(SSL_CTX *), char *arg) +=item void B(SSL_CTX *ctx, int (*cb)(), char *arg) =item int B(SSL_CTX *ctx, char *str); @@ -663,6 +663,7 @@ L, L, L, L, +L, L, L, L, -- 2.25.1