LIBRESSL-SSL_CTX_ADD_EXTRA_CHAIN_CERT(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💖 NAME — the squad 💖

Okay so bestie, this is the SSL_CTX_ADD_EXTRA_CHAIN_(3) page from the Library Functions Manual, and it is giving “certificate chain management but make it group chat.” ✨ The main characters are SSL_CTX_add_extra_chain_cert, SSL_CTX_get_extra_chain_certs_only, SSL_CTX_get_extra_chain_certs, and SSL_CTX_clear_extra_chain_certs — they add, retrieve, and clear extra chain certificates. Periodt. 💅

🌸 SYNOPSIS — the call sheet 🌸

No cap, here is exactly how these look:

       library “libssl” libcrypto #include <openssl/ssl.h>

       long
       SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);

       long
       SSL_CTX_get_extra_chain_certs_only(SSL_CTX *ctx,
           STACK_OF(X509) **certs);

       long
       SSL_CTX_get_extra_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **certs);

       long
       SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx);

🦋 DESCRIPTION — the tea 🦋

  • SSL_CTX_add_extra_chain_cert() — adds the certificate x509 to the extra chain certificates associated with ctx. Several certificates can be added one after another, like stacking cute little charms on a bracelet. 🎀
  • SSL_CTX_get_extra_chain_certs_only() — retrieves an internal pointer to the stack of extra chain certificates associated with ctx, or set *certs to NULL if there are none. Very “here is the pointer, bestie” energy. 🫶
  • SSL_CTX_get_extra_chain_certs() — does the same except that it retrieves an internal pointer to the chain associated with the certificate if there are no extra chain certificates. Lowkey the fallback friend. 💜
  • SSL_CTX_clear_extra_chain_certs() — clears all extra chain certificates associated with ctx. Poof, gone, iconic cleanup. ✨

Plot twist: these functions are implemented as macros. 🪄

When sending a certificate chain, extra chain certificates are sent in order following the end entity certificate. So the order matters, bestie — no chaotic random shuffle. 💅

If no chain is specified, the library will try to complete the chain from the available CA certificates in the trusted CA storage, see SSL_CTX_load_verify_locations(3).

Memory tea ☕: the x509 certificate provided to SSL_CTX_add_extra_chain_cert() will be freed by the library when the SSL_CTX is destroyed. An application should not free the x509 object, nor the *certs object retrieved by SSL_CTX_get_extra_chain_certs(). Do not be the friend who double-frees. 😭

🔥 RETURN VALUES — the vibe check 🔥

These functions return 1 on success or 0 for failure. Check out the error stack to find out the reason for failure. Bestie, 0 is not the slay outcome — go read the error stack. 💀

💜 SEE ALSO — go read these next 💜

🌈 HISTORY — the lore 🌈

  • SSL_CTX_add_extra_chain_cert() — first appeared in SSLeay 0.9.1 and has been available since OpenBSD 2.6.
  • SSL_CTX_get_extra_chain_certs() and SSL_CTX_clear_extra_chain_certs() — first appeared in OpenSSL 1.0.1 and have been available since OpenBSD 5.3.
  • SSL_CTX_get_extra_chain_certs_only() — first appeared in OpenSSL 1.0.2 and has been available since OpenBSD 6.7.

⚠️ CAVEATS — real talk ⚠️

Certificates added with SSL_CTX_add_extra_chain_cert() are ignored when certificates are also available that have been added using the functions documented in SSL_CTX_set1_chain(3). That is a big “not me being ignored” moment. 🙈

Only one set of extra chain certificates can be specified per SSL_CTX structure using SSL_CTX_add_extra_chain_cert(). Different chains for different certificates (for example if both RSA and ECDSA certificates are specified by the same server) or different SSL structures with the same parent SSL_CTX require using the functions documented in SSL_CTX_set1_chain(3) instead. So if you need multiple chains, this single-set situation is not it — use the SSL_CTX_set1_chain(3) functions. 💅

Okay that is the whole page, bestie 🫶 — this one is from Debian, dated June 8, 2025, and the footer tag is SSL_CTX_ADD_EXTRA_CHAIN_CERT(3). Stay iconic and chain on. 🌈💖

📦 where this page comes from