1289848Sjkim=pod 2289848Sjkim 3289848Sjkim=head1 NAME 4289848Sjkim 5289848SjkimSSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, 6289848SjkimSSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs, 7289848SjkimSSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert, 8289848SjkimSSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain, 9289848SjkimSSL_build_cert_chain, SSL_CTX_select_current_cert, 10289848SjkimSSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra 11289848Sjkimchain certificate processing 12289848Sjkim 13289848Sjkim=head1 SYNOPSIS 14289848Sjkim 15289848Sjkim #include <openssl/ssl.h> 16289848Sjkim 17289848Sjkim int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); 18289848Sjkim int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); 19289848Sjkim int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509); 20289848Sjkim int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); 21289848Sjkim int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk); 22289848Sjkim int SSL_CTX_clear_chain_certs(SSL_CTX *ctx); 23289848Sjkim 24289848Sjkim int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk); 25289848Sjkim int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk); 26289848Sjkim int SSL_add0_chain_cert(SSL *ssl, X509 *x509); 27289848Sjkim int SSL_add1_chain_cert(SSL *ssl, X509 *x509); 28289848Sjkim int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk); 29289848Sjkim int SSL_clear_chain_certs(SSL *ssl); 30289848Sjkim 31289848Sjkim int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags); 32289848Sjkim int SSL_build_cert_chain(SSL *ssl, flags); 33289848Sjkim 34289848Sjkim int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509); 35289848Sjkim int SSL_select_current_cert(SSL *ssl, X509 *x509); 36289848Sjkim int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op); 37289848Sjkim int SSL_set_current_cert(SSL *ssl, long op); 38289848Sjkim 39289848Sjkim=head1 DESCRIPTION 40289848Sjkim 41289848SjkimSSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain 42289848Sjkimassociated with the current certificate of B<ctx> to B<sk>. 43289848Sjkim 44289848SjkimSSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single 45289848Sjkimcertificate B<x509> to the chain associated with the current certificate of 46289848SjkimB<ctx>. 47289848Sjkim 48289848SjkimSSL_CTX_get0_chain_certs() retrieves the chain associated with the current 49289848Sjkimcertificate of B<ctx>. 50289848Sjkim 51289848SjkimSSL_CTX_clear_chain_certs() clears any existing chain associated with the 52289848Sjkimcurrent certificate of B<ctx>. (This is implemented by calling 53289848SjkimSSL_CTX_set0_chain() with B<sk> set to B<NULL>). 54289848Sjkim 55289848SjkimSSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally 56289848Sjkimthis uses the chain store or the verify store if the chain store is not set. 57289848SjkimIf the function is successful the built chain will replace any existing chain. 58289848SjkimThe B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use 59289848Sjkimexisting chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT> 60289848Sjkimto omit the root CA from the built chain, B<SSL_BUILD_CHAIN_FLAG_CHECK> to 61289848Sjkimuse all existing chain certificates only to build the chain (effectively 62289848Sjkimsanity checking and rearranging them if necessary), the flag 63289848SjkimB<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification: 64289848Sjkimif flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors 65289848Sjkimare cleared from the error queue. 66289848Sjkim 67289848SjkimEach of these functions operates on the I<current> end entity 68289848Sjkim(i.e. server or client) certificate. This is the last certificate loaded or 69289848Sjkimselected on the corresponding B<ctx> structure. 70289848Sjkim 71289848SjkimSSL_CTX_select_current_cert() selects B<x509> as the current end entity 72289848Sjkimcertificate, but only if B<x509> has already been loaded into B<ctx> using a 73289848Sjkimfunction such as SSL_CTX_use_certificate(). 74289848Sjkim 75289848SjkimSSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(), 76289848SjkimSSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(), 77289848SjkimSSL_build_cert_chain(), SSL_select_current_cert() and SSL_set_current_cert() 78289848Sjkimare similar except they apply to SSL structure B<ssl>. 79289848Sjkim 80289848SjkimSSL_CTX_set_current_cert() changes the current certificate to a value based 81289848Sjkimon the B<op> argument. Currently B<op> can be B<SSL_CERT_SET_FIRST> to use 82289848Sjkimthe first valid certificate or B<SSL_CERT_SET_NEXT> to set the next valid 83289848Sjkimcertificate after the current certificate. These two operations can be 84289848Sjkimused to iterate over all certificates in an B<SSL_CTX> structure. 85289848Sjkim 86289848SjkimSSL_set_current_cert() also supports the option B<SSL_CERT_SET_SERVER>. 87289848SjkimIf B<ssl> is a server and has sent a certificate to a connected client 88289848Sjkimthis option sets that certificate to the current certificate and returns 1. 89289848SjkimIf the negotiated ciphersuite is anonymous (and thus no certificate will 90289848Sjkimbe sent) 2 is returned and the current certificate is unchanged. If B<ssl> 91289848Sjkimis not a server or a certificate has not been sent 0 is returned and 92289848Sjkimthe current certificate is unchanged. 93289848Sjkim 94289848SjkimAll these functions are implemented as macros. Those containing a B<1> 95289848Sjkimincrement the reference count of the supplied certificate or chain so it must 96289848Sjkimbe freed at some point after the operation. Those containing a B<0> do 97289848Sjkimnot increment reference counts and the supplied certificate or chain 98289848SjkimB<MUST NOT> be freed after the operation. 99289848Sjkim 100289848Sjkim=head1 NOTES 101289848Sjkim 102289848SjkimThe chains associate with an SSL_CTX structure are copied to any SSL 103289848Sjkimstructures when SSL_new() is called. SSL structures will not be affected 104289848Sjkimby any chains subsequently changed in the parent SSL_CTX. 105289848Sjkim 106289848SjkimOne chain can be set for each key type supported by a server. So, for example, 107289848Sjkiman RSA and a DSA certificate can (and often will) have different chains. 108289848Sjkim 109289848SjkimThe functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can 110289848Sjkimbe used to check application configuration and to ensure any necessary 111289848Sjkimsubordinate CAs are sent in the correct order. Misconfigured applications 112289848Sjkimsending incorrect certificate chains often cause problems with peers. 113289848Sjkim 114289848SjkimFor example an application can add any set of certificates using 115289848SjkimSSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain() 116289848Sjkimwith the option B<SSL_BUILD_CHAIN_FLAG_CHECK> to check and reorder them. 117289848Sjkim 118289848SjkimApplications can issue non fatal warnings when checking chains by setting 119289848Sjkimthe flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS> and checking the return 120289848Sjkimvalue. 121289848Sjkim 122289848SjkimCalling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more 123289848Sjkimefficient than the automatic chain building as it is only performed once. 124289848SjkimAutomatic chain building is performed on each new session. 125289848Sjkim 126289848SjkimIf any certificates are added using these functions no certificates added 127289848Sjkimusing SSL_CTX_add_extra_chain_cert() will be used. 128289848Sjkim 129289848Sjkim=head1 RETURN VALUES 130289848Sjkim 131289848SjkimSSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if 132289848Sjkimno server certificate is used because the ciphersuites is anonymous and 0 133289848Sjkimfor failure. 134289848Sjkim 135289848SjkimSSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success 136289848Sjkimand 0 for failure. If the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> and 137289848Sjkima verification error occurs then 2 is returned. 138289848Sjkim 139289848SjkimAll other functions return 1 for success and 0 for failure. 140289848Sjkim 141289848Sjkim 142289848Sjkim=head1 SEE ALSO 143289848Sjkim 144289848SjkimL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> 145289848Sjkim 146289848Sjkim=head1 HISTORY 147289848Sjkim 148289848SjkimThese functions were first added to OpenSSL 1.0.2. 149289848Sjkim 150289848Sjkim=cut 151