X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FSSL_CTX_set_verify.pod;h=799349892c3f999a5de7c15b4451bbaae2e4759b;hp=96a98acaacab94ad66bac580db2c2f67babedad1;hb=800b5dac006344896a3aa947ab13cd9f63e3fc4c;hpb=99d63d4662e16afbeff49f29b48f1c87d5558ed0

diff --git a/doc/man3/SSL_CTX_set_verify.pod b/doc/man3/SSL_CTX_set_verify.pod
index 96a98acaac..799349892c 100644
--- a/doc/man3/SSL_CTX_set_verify.pod
+++ b/doc/man3/SSL_CTX_set_verify.pod
@@ -2,20 +2,25 @@
 
 =head1 NAME
 
-SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
+SSL_get_ex_data_X509_STORE_CTX_idx,
+SSL_CTX_set_verify, SSL_set_verify,
+SSL_CTX_set_verify_depth, SSL_set_verify_depth,
+SSL_verify_cb
+- set peer certificate verification parameters
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
- void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
-                         int (*verify_callback)(int, X509_STORE_CTX *));
- void SSL_set_verify(SSL *s, int mode,
-                     int (*verify_callback)(int, X509_STORE_CTX *));
+ void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback);
+ void SSL_set_verify(SSL *s, int mode, SSL_verify_cb verify_callback);
+ SSL_get_ex_data_X509_STORE_CTX_idx(void);
+
  void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth);
  void SSL_set_verify_depth(SSL *s, int depth);
 
- int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
+
+ typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx);
 
 =head1 DESCRIPTION
 
@@ -29,13 +34,15 @@ shall be specified, the NULL pointer can be used for B<verify_callback>. In
 this case last B<verify_callback> set specifically for this B<ssl> remains. If
 no special B<callback> was set before, the default callback for the underlying
 B<ctx> is used, that was valid at the time B<ssl> was created with
-L<SSL_new(3)>.
+L<SSL_new(3)>. Within the callback function,
+B<SSL_get_ex_data_X509_STORE_CTX_idx> can be called to get the data index
+of the current SSL object that is doing the verification.
 
 SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
-verification that shall be allowed for B<ctx>. (See the BUGS section.)
+verification that shall be allowed for B<ctx>.
 
 SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
-verification that shall be allowed for B<ssl>. (See the BUGS section.)
+verification that shall be allowed for B<ssl>.
 
 =head1 NOTES
 
@@ -100,16 +107,19 @@ 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
-above the limit are ignored. Error messages are generated as if these
-certificates would not be present, most likely a
-X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
+SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set a limit on the
+number of certificates between the end-entity and trust-anchor certificates.
+Neither the
+end-entity nor the trust-anchor certificates count against B<depth>. If the
+certificate chain needed to reach a trusted issuer is longer than B<depth+2>,
+X509_V_ERR_CERT_CHAIN_TOO_LONG will be issued.
 The depth count is "level 0:peer certificate", "level 1: CA certificate",
 "level 2: higher level CA certificate", and so on. Setting the maximum
-depth to 2 allows the levels 0, 1, and 2. The default depth limit is 100,
-allowing for the peer certificate and additional 100 CA certificates.
+depth to 2 allows the levels 0, 1, 2 and 3 (0 being the end-entity and 3 the
+trust-anchor).
+The default depth limit is 100,
+allowing for the peer certificate, at most 100 intermediate CA certificates and
+a final trust anchor certificate.
 
 The B<verify_callback> function is used to control the behaviour when the
 SSL_VERIFY_PEER flag is set. It must be supplied by the application and
@@ -145,6 +155,13 @@ Its return value is identical to B<preverify_ok>, so that any verification
 failure will lead to a termination of the TLS/SSL handshake with an
 alert message, if SSL_VERIFY_PEER is set.
 
+=head1 BUGS
+
+In client mode, it is not checked whether the SSL_VERIFY_PEER flag
+is set, but whether any flags are set. This can lead to
+unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as
+required.
+
 =head1 RETURN VALUES
 
 The SSL*_set_verify*() functions do not provide diagnostic information.
@@ -163,7 +180,7 @@ certificates.
 
 The example makes use of the ex_data technique to store application data
 into/retrieve application data from the SSL structure
-(see L<SSL_get_ex_new_index(3)>,
+(see L<CRYPTO_get_ex_new_index(3)>,
 L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
 
  ...
@@ -269,18 +286,18 @@ L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
 
 =head1 SEE ALSO
 
-L<ssl(3)>, L<SSL_new(3)>,
+L<ssl(7)>, L<SSL_new(3)>,
 L<SSL_CTX_get_verify_mode(3)>,
 L<SSL_get_verify_result(3)>,
 L<SSL_CTX_load_verify_locations(3)>,
 L<SSL_get_peer_certificate(3)>,
 L<SSL_CTX_set_cert_verify_callback(3)>,
 L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
-L<SSL_get_ex_new_index(3)>
+L<CRYPTO_get_ex_new_index(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy