Update chain building function.

[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 0c977aa1a722d318cb23de062b51ce91aa801cb1..a4ffde1304031a163c21e999a2faf18139440790 100644 (file)
--- a/doc/ssl/SSL_CTX_add1_chain_cert.pod
+++ b/doc/ssl/SSL_CTX_add1_chain_cert.pod
@@ -52,11 +52,17 @@ 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:
+if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors
+are cleared from the error queue.
 
 Each of these functions operates on the I<current> end entity
 (i.e. server or client) certificate. This is the last certificate loaded or
@@ -77,6 +83,14 @@ the first valid certificate or B<SSL_CERT_SET_NEXT> to set the next valid
 certificate after the current certificate. These two operations can be
 used to iterate over all certificates in an B<SSL_CTX> structure.
 
+SSL_set_current_cert() also supports the option B<SSL_CERT_SET_SERVER>.
+If B<ssl> is a server and has sent a certificate to a connected client
+this option sets that certificate to the current certificate and returns 1.
+If the negotiated ciphersuite is anonymous (and thus no certificate will
+be sent) 2 is returned and the current certificate is unchanged. If B<ssl>
+is not a server or a certificate has not been sent 0 is returned and
+the current certificate is unchanged.
+
 All these functions are implemented as macros. Those containing a B<1>
 increment the reference count of the supplied certificate or chain so it must
 be freed at some point after the operation. Those containing a B<0> do
@@ -97,6 +111,14 @@ 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.
+
+Applications can issue non fatal warnings when checking chains by setting
+the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS> and checking the return
+value.
+
 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.
@@ -106,7 +128,15 @@ 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.
+
+SSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success
+and 0 for failure. If the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> and
+a verification error occurs then 2 is returned.
+
+All other functions return 1 for success and 0 for failure.
 
 =back