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 — extra chain certificate processing

SYNOPSIS

#include <openssl/ssl.h>

int
SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *chain);

int
SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *chain);

int
SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *cert);

int
SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *cert);

int
SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **chain);

int
SSL_CTX_clear_chain_certs(SSL_CTX *ctx);

int
SSL_set0_chain(SSL *ssl, STACK_OF(X509) *chain);

int
SSL_set1_chain(SSL *ssl, STACK_OF(X509) *chain);

int
SSL_add0_chain_cert(SSL *ssl, X509 *cert);

int
SSL_add1_chain_cert(SSL *ssl, X509 *cert);

int
SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **chain);

int
SSL_clear_chain_certs(SSL *ssl);

DESCRIPTION

SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain associated with the current certificate of ctx to chain. The chain is not supposed to include the current certificate itself.

SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single certificate cert to the chain associated with the current certificate of ctx.

SSL_CTX_get0_chain_certs() retrieves the chain associated with the current certificate of ctx.

SSL_CTX_clear_chain_certs() clears the existing chain associated with the current certificate of ctx, if any. This is equivalent to calling SSL_CTX_set0_chain() with chain set to NULL.

Each of these functions operates on the current end entity (i.e. server or client) certificate. This is the last certificate loaded or selected on the corresponding ctx structure, for example using SSL_CTX_use_certificate(3).

SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(), SSL_add1_chain_cert(), SSL_get0_chain_certs(), and SSL_clear_chain_certs() are similar except that they operate on the ssl connection.

The functions containing a 1 in their name increment the reference count of the supplied certificate or chain, so it must be freed at some point after the operation. Those containing a 0 do not increment reference counts and the supplied certificate or chain must not be freed after the operation.

The chains associated with an SSL_CTX structure are copied to the new SSL structure when SSL_new(3) is called. Existing SSL structures are not 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 an ECDSA certificate can have different chains.

If any certificates are added using these functions, no certificates added using SSL_CTX_add_extra_chain_cert(3) will be used.

RETURN VALUES

These functions return 1 for success or 0 for failure.

SEE ALSO

ssl(3), SSL_CTX_add_extra_chain_cert(3), SSL_CTX_use_certificate(3)

HISTORY

These functions first appeared in OpenSSL 1.0.2 and have been available since OpenBSD 6.5.