7b6b246fd3
PR#3169 This patch, which currently applies successfully against master and 1_0_2, adds the following functions: SSL_[CTX_]select_current_cert() - set the current certificate without disturbing the existing structure. SSL_[CTX_]get0_chain_certs() - get the current certificate's chain. SSL_[CTX_]clear_chain_certs() - clear the current certificate's chain. The patch also adds these functions to, and fixes some existing errors in, SSL_CTX_add1_chain_cert.pod.
110 lines
4.3 KiB
Text
110 lines
4.3 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
|
|
SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs,
|
|
SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert,
|
|
SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain,
|
|
SSL_build_cert_chain, SSL_CTX_select_current_cert,
|
|
SSL_select_current_cert - 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, X509 *x509);
|
|
int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
|
|
int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
|
|
int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
|
|
|
|
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, X509 *x509);
|
|
int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
|
|
int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
|
|
int SSL_clear_chain_certs(SSL *ssl);
|
|
|
|
int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
|
|
int SSL_build_cert_chain(SSL *ssl, flags);
|
|
|
|
int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
|
|
int SSL_select_current_cert(SSL *ssl, X509 *x509);
|
|
|
|
=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>.
|
|
|
|
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_get0_chain_certs() retrieves the chain associated with the current
|
|
certificate of B<ctx>.
|
|
|
|
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.
|
|
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.
|
|
|
|
Each of these functions operates on the I<current> end entity
|
|
(i.e. server or client) certificate. This is the last certificate loaded or
|
|
selected on the corresponding B<ctx> structure.
|
|
|
|
SSL_CTX_select_current_cert() selects B<x509> as the current end entity
|
|
certificate, but only if B<x509> has already been loaded into B<ctx> using a
|
|
function such as SSL_CTX_use_certificate().
|
|
|
|
SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(),
|
|
SSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(),
|
|
SSL_build_cert_chain() and SSL_select_current_cert() 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.
|
|
|
|
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.
|
|
|
|
=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
|