From eeb15452a053c14305210522be0e7313cb763bac Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Fri, 16 Aug 2013 18:11:29 +0100 Subject: [PATCH] Add documentation. Preliminary documentation for chain and verify stores and certificate chain setting functions. --- doc/ssl/SSL_CTX_add1_chain_cert.pod | 92 +++++++++++++++++++++ doc/ssl/SSL_CTX_add_extra_chain_cert.pod | 19 +++++ doc/ssl/SSL_CTX_set1_verify_cert_store.pod | 93 ++++++++++++++++++++++ doc/ssl/SSL_CTX_set_cert_store.pod | 7 ++ 4 files changed, 211 insertions(+) create mode 100644 doc/ssl/SSL_CTX_add1_chain_cert.pod create mode 100644 doc/ssl/SSL_CTX_set1_verify_cert_store.pod diff --git a/doc/ssl/SSL_CTX_add1_chain_cert.pod b/doc/ssl/SSL_CTX_add1_chain_cert.pod new file mode 100644 index 0000000000..ef26c9f86b --- /dev/null +++ b/doc/ssl/SSL_CTX_add1_chain_cert.pod @@ -0,0 +1,92 @@ +=pod + +=head1 NAME + +SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, +SSL_CTX_add1_chain_cert, SSL_set0_chain, SSL_set1_chain, +SSL_add0_chain_cert, SSL_add1_chain_cert, SSL_CTX_build_cert_chain, +SSL_build_cert_chain - extra chain certificate processing + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); + int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); + int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, STACK_OF(X509) *x509); + int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); + + int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk); + int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk); + int SSL_add0_chain_cert(SSL *ssl, STACK_OF(X509) *x509); + int SSL_add1_chain_cert(SSL *ssl, X509 *x509); + + int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags); + int SSL_build_cert_chain(SSL_CTX *ctx, flags); + +=head1 DESCRIPTION + +SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain +associated with the current certificate of B to B. If B is set +to B any existing chain is cleared. + +SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single +certificate B to the chain associated with the current certificate of +B. + +SSL_CTX_build_cert_chain() builds the certificate chain for B using the +chain store. Any existing chain certificates are used as untrusted CAs. +If the function is successful the built chain will replace any existing chain. +The B parameter can be set to B to omit +the root CA from the built chain. + +SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(), SSL_add0_chain_cert() +and SSL_build_cert_chain() are similar except they apply to SSL structure +B. + +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 +not increment reference counts and the supplied certificate or chain +B be freed after the operation. + +=head1 NOTES + +The chains associate with an SSL_CTX structure are copied to any SSL +structures when SSL_new() is called. SSL structures will not be affected +by any chains subsequently changed in the parent SSL_CTX. + +Each of these functions operates on the I end entity +(i.e. server or client) certificate. This is the last certificate set +on the corresponding B or B structure. + +One chain can be set for each key type supported by a server. So, for example, +an RSA and a DSA certificate can (and often will) have different chains. + +The functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can +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. + +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. + +If any certificates are added using these functions no certificates added +using SSL_CTX_add_extra_chain_cert() will be used. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + +=back + +=head1 SEE ALSO + +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=cut diff --git a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod index ee28f5ccc3..11b3b4bbe3 100644 --- a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod +++ b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod @@ -24,6 +24,15 @@ the library will try to complete the chain from the available CA certificates in the trusted CA storage, see L. +=head1 RESTRICTIONS + +Only one set of extra chain certificates can be specified per SSL_CTX +structure. Different chains for different certificates (for example if both +RSA and DSA certificates are specified by the same server) or different SSL +structures with the same parent SSL_CTX cannot be specified using this +function. For more flexibility functions such as SSL_add1_chain_cert() should +be used instead. + =head1 RETURN VALUES SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the @@ -35,5 +44,15 @@ L, L, L, L +L +L +L +L +L +L +L +L +L +L =cut diff --git a/doc/ssl/SSL_CTX_set1_verify_cert_store.pod b/doc/ssl/SSL_CTX_set1_verify_cert_store.pod new file mode 100644 index 0000000000..a30ae93cf9 --- /dev/null +++ b/doc/ssl/SSL_CTX_set1_verify_cert_store.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store, +SSL_CTX_set0_chain_cert_store, SSL_CTX_set1_chain_cert_store, +SSL_set0_verify_cert_store, SSL_set1_verify_cert_store, +SSL_set0_chain_cert_store, SSL_set1_chain_cert_store - set certificate +verification or chain store + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + + int SSL_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + +=head1 DESCRIPTION + +SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store() +set the certificate store used for certificate verification to B. + +SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store() +set the certificate store used for certificate chain building to B. + +SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(), +SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar +except they apply to SSL structure B. + +All these functions are implemented as macros. Those containing a B<1> +increment the reference count of the supplied store so it must +be freed at some point after the operation. Those containing a B<0> do +not increment reference counts and the supplied store B be freed +after the operation. + +=head1 NOTES + +The stores pointers associated with an SSL_CTX structure are copied to any SSL +structures when SSL_new() is called. As a result SSL structures will not be +affected if the parent SSL_CTX store pointer is set to a new value. + +The verification store is used to verify the certificate chain sent by the +peer: that is an SSL/TLS client will use the verification store to verify +the server's certificate chain and a SSL/TLS server will use it to verify +any client certificate chain. + +The chain store is used to build the certificate chain. + +If the mode B is set or a certificate chain is +configured already (for example using the functions such as +L or +L) then +automatic chain building is disabled. + +If the mode B is set then automatic chain building +is disabled. + +If the chain or the verification store is not set then the store associated +with the parent SSL_CTX is used instead to retain compatibility with previous +versions of OpenSSL. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + +=back + +=head1 SEE ALSO + +L +L +L +L +L +L +L +L +L +L +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=cut diff --git a/doc/ssl/SSL_CTX_set_cert_store.pod b/doc/ssl/SSL_CTX_set_cert_store.pod index 6acf0d9f9b..846416e069 100644 --- a/doc/ssl/SSL_CTX_set_cert_store.pod +++ b/doc/ssl/SSL_CTX_set_cert_store.pod @@ -42,6 +42,13 @@ L family of functions. This document must therefore be updated when documentation about the X509_STORE object and its handling becomes available. +=head1 RESTRICTIONS + +The X509_STORE structure used by an SSL_CTX is used for verifying peer +certificates and building certificate chains, it is also shared by +every child SSL structure. Applications wanting finer control can use +functions such as SSL_CTX_set1_verify_cert_store() instead. + =head1 RETURN VALUES SSL_CTX_set_cert_store() does not return diagnostic output.