diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2013-08-16 18:11:29 +0100 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2013-08-18 13:53:32 +0100 |
commit | df430489cf46a2a0734b63fd3879c7721efcaa16 (patch) | |
tree | 0a0cc8e96983f9f94b31607dcce3f3a9736d4d5b /doc/ssl/SSL_CTX_add1_chain_cert.pod | |
parent | 5085e57fb5d65c0ab271a307fc3364547e687f6a (diff) |
Add documentation.
Preliminary documentation for chain and verify stores and certificate chain
setting functions.
(cherry picked from commit eeb15452a053c14305210522be0e7313cb763bac)
Diffstat (limited to 'doc/ssl/SSL_CTX_add1_chain_cert.pod')
-rw-r--r-- | doc/ssl/SSL_CTX_add1_chain_cert.pod | 92 |
1 files changed, 92 insertions, 0 deletions
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 <openssl/ssl.h> + + 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<ctx> to B<sk>. If B<sk> is set +to B<NULL> any existing chain is cleared. + +SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single +certificate B<x509> to the chain associated with the current certificate of +B<ctx>. + +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. +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. + +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<ssl>. + +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<MUST NOT> 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<current> end entity +(i.e. server or client) certificate. This is the last certificate set +on the corresponding B<ctx> or B<ssl> 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<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=cut |