SSL_CTX_add1_chain_cert(3) OpenSSL SSL_CTX_add1_chain_cert(3) NNAAMMEE 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, SSL_CTX_set_cur- rent_cert, SSL_set_current_cert - extra chain certificate processing SSYYNNOOPPSSIISS #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, 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); int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op); int SSL_set_current_cert(SSL *ssl, long op); DDEESSCCRRIIPPTTIIOONN _S_S_L___C_T_X___s_e_t_0___c_h_a_i_n_(_) and _S_S_L___C_T_X___s_e_t_1___c_h_a_i_n_(_) set the certificate chain associated with the current certificate of ccttxx to sskk. _S_S_L___C_T_X___a_d_d_0___c_h_a_i_n___c_e_r_t_(_) and _S_S_L___C_T_X___a_d_d_1___c_h_a_i_n___c_e_r_t_(_) append the sin- gle certificate xx550099 to the chain associated with the current certifi- cate of ccttxx. _S_S_L___C_T_X___g_e_t_0___c_h_a_i_n___c_e_r_t_s_(_) retrieves the chain associated with the cur- rent certificate of ccttxx. _S_S_L___C_T_X___c_l_e_a_r___c_h_a_i_n___c_e_r_t_s_(_) clears any existing chain associated with the current certificate of ccttxx. (This is implemented by calling _S_S_L___C_T_X___s_e_t_0___c_h_a_i_n_(_) with sskk set to NNUULLLL). _S_S_L___C_T_X___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) builds the certificate chain for ccttxx nor- mally this uses the chain store or the verify store if the chain store is not set. If the function is successful the built chain will replace any existing chain. The ffllaaggss parameter can be set to SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__UUNNTTRRUUSSTTEEDD to use existing chain certificates as untrusted CAs, SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__NNOO__RROOOOTT to omit the root CA from the built chain, SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__CCHHEECCKK to use all existing chain certificates only to build the chain (effectively sanity checking and rearranging them if necessary), the flag SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__IIGGNNOORREE__EERRRROORR ignores any errors during verifica- tion: if flag SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__CCLLEEAARR__EERRRROORR is also set verification errors are cleared from the error queue. Each of these functions operates on the _c_u_r_r_e_n_t end entity (i.e. server or client) certificate. This is the last certificate loaded or selected on the corresponding ccttxx structure. _S_S_L___C_T_X___s_e_l_e_c_t___c_u_r_r_e_n_t___c_e_r_t_(_) selects xx550099 as the current end entity certificate, but only if xx550099 has already been loaded into ccttxx using a function such as _S_S_L___C_T_X___u_s_e___c_e_r_t_i_f_i_c_a_t_e_(_). _S_S_L___s_e_t_0___c_h_a_i_n_(_), _S_S_L___s_e_t_1___c_h_a_i_n_(_), _S_S_L___a_d_d_0___c_h_a_i_n___c_e_r_t_(_), _S_S_L___a_d_d_1___c_h_a_i_n___c_e_r_t_(_), _S_S_L___g_e_t_0___c_h_a_i_n___c_e_r_t_s_(_), _S_S_L___c_l_e_a_r___c_h_a_i_n___c_e_r_t_s_(_), _S_S_L___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_), _S_S_L___s_e_l_e_c_t___c_u_r_r_e_n_t___c_e_r_t_(_) and _S_S_L___s_e_t___c_u_r_- _r_e_n_t___c_e_r_t_(_) are similar except they apply to SSL structure ssssll. _S_S_L___C_T_X___s_e_t___c_u_r_r_e_n_t___c_e_r_t_(_) changes the current certificate to a value based on the oopp argument. Currently oopp can be SSSSLL__CCEERRTT__SSEETT__FFIIRRSSTT to use the first valid certificate or SSSSLL__CCEERRTT__SSEETT__NNEEXXTT to set the next valid certificate after the current certificate. These two operations can be used to iterate over all certificates in an SSSSLL__CCTTXX structure. _S_S_L___s_e_t___c_u_r_r_e_n_t___c_e_r_t_(_) also supports the option SSSSLL__CCEERRTT__SSEETT__SSEERRVVEERR. If ssssll is a server and has sent a certificate to a connected client this option sets that certificate to the current certificate and returns 1. If the negotiated ciphersuite is anonymous (and thus no certificate will be sent) 2 is returned and the current certificate is unchanged. If ssssll is not a server or a certificate has not been sent 0 is returned and the current certificate is unchanged. All these functions are implemented as macros. Those containing a 11 increment the reference count of the supplied certificate or chain so it must be freed at some point after the operation. Those containing a 00 do not increment reference counts and the supplied certificate or chain MMUUSSTT NNOOTT be freed after the operation. NNOOTTEESS The chains associate with an SSL_CTX structure are copied to any SSL structures when _S_S_L___n_e_w_(_) 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 differ- ent chains. The functions _S_S_L___C_T_X___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) and _S_S_L___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) can be used to check application configuration and to ensure any necessary subordinate CAs are sent in the correct order. Misconfigured applica- tions sending incorrect certificate chains often cause problems with peers. For example an application can add any set of certificates using _S_S_L___C_T_X___u_s_e___c_e_r_t_i_f_i_c_a_t_e___c_h_a_i_n___f_i_l_e_(_) then call _S_S_L___C_T_X___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) with the option SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__CCHHEECCKK to check and reorder them. Applications can issue non fatal warnings when checking chains by set- ting the flag SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__IIGGNNOORREE__EERRRROORRSS and checking the return value. Calling _S_S_L___C_T_X___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) or _S_S_L___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) 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 _S_S_L___C_T_X___a_d_d___e_x_t_r_a___c_h_a_i_n___c_e_r_t_(_) will be used. RREETTUURRNN VVAALLUUEESS _S_S_L___s_e_t___c_u_r_r_e_n_t___c_e_r_t_(_) with SSSSLL__CCEERRTT__SSEETT__SSEERRVVEERR return 1 for success, 2 if no server certificate is used because the ciphersuites is anonymous and 0 for failure. _S_S_L___C_T_X___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) and _S_S_L___b_u_i_l_d___c_e_r_t___c_h_a_i_n_(_) return 1 for suc- cess and 0 for failure. If the flag SSSSLL__BBUUIILLDD__CCHHAAIINN__FFLLAAGG__IIGGNNOORREE__EERRRROORR and a verification error occurs then 2 is returned. All other functions return 1 for success and 0 for failure. SSEEEE AALLSSOO _S_S_L___C_T_X___a_d_d___e_x_t_r_a___c_h_a_i_n___c_e_r_t(3) HHIISSTTOORRYY These functions were first added to OpenSSL 1.0.2. 1.0.2u 2019-12-20 SSL_CTX_add1_chain_cert(3)