New chain building flags.

[openssl.git] / doc / ssl / SSL_CTX_add1_chain_cert.pod

diff --git a/doc/ssl/SSL_CTX_add1_chain_cert.pod b/doc/ssl/SSL_CTX_add1_chain_cert.pod
index e294afe253b866fa4b086e8a4d3d3804dd5cfdd6..b508a342a5f29127a6bd0b74242b38c8451374e4 100644 (file)
--- a/doc/ssl/SSL_CTX_add1_chain_cert.pod
+++ b/doc/ssl/SSL_CTX_add1_chain_cert.pod
@@ -52,11 +52,15 @@ SSL_CTX_clear_chain_certs() clears any existing chain associated with the
 current certificate of B<ctx>.  (This is implemented by calling
 SSL_CTX_set0_chain() with B<sk> set to B<NULL>).
 
-SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> using the
-chain store. Any existing chain certificates are used as untrusted CAs.
+SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally
+this uses the chain store or the verify store if the chain store is not set.
 If the function is successful the built chain will replace any existing chain.
-The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_NO_ROOT> to omit
-the root CA from the built chain.
+The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use
+existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT>
+to omit the root CA from the built chain, B<SSL_BUILD_CHAIN_FLAG_CHECK> to
+use all existing chain certificates only to build the chain (effectively
+sanity checking and rearranging them if necessary), the flag
+B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification.
 
 Each of these functions operates on the I<current> end entity
 (i.e. server or client) certificate. This is the last certificate loaded or
@@ -105,6 +109,10 @@ be used to check application configuration and to ensure any necessary
 subordinate CAs are sent in the correct order. Misconfigured applications
 sending incorrect certificate chains often cause problems with peers.
 
+For example an application can add any set of certificates using
+SSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain()
+with the option B<SSL_BUILD_CHAIN_FLAG_CHECK> to check and reorder them.
+
 Calling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more
 efficient than the automatic chain building as it is only performed once.
 Automatic chain building is performed on each new session.
@@ -114,7 +122,11 @@ using SSL_CTX_add_extra_chain_cert() will be used.
 
 =head1 RETURN VALUES
 
-All these functions return 1 for success and 0 for failure.
+SSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if
+no server certificate is used because the ciphersuites is anonymous and 0
+for failure.
+
+All other functions return 1 for success and 0 for failure.
 
 =head1 SEE ALSO