SSL_CTX_ADD_EXTRA_CHAIN_CERT(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 SSL_CTX_ADD_EXTRA_CHAIN_CERT 💖

okay bestie, welcome to the 3ossl manual page, and no this is not the SSL one you're thinking of, this is the extra-chain-cert one, and it's lowkey iconic. sit down, hydrate, let's go 🫶

✨ NAME ✨

SSL_CTX_add_extra_chain_cert, SSL_CTX_get_extra_chain_certs, SSL_CTX_get_extra_chain_certs_only, SSL_CTX_clear_extra_chain_certs — add, get or clear extra chain certificates 🎀

🌸 SYNOPSIS 🌸

#include <openssl/ssl.h>

long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);
long SSL_CTX_get_extra_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
long SSL_CTX_get_extra_chain_certs_only(SSL_CTX *ctx, STACK_OF(X509) **sk);
long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx);

look at those four little lines. so tidy. so slay. 💅

🦋 DESCRIPTION 🦋

  • SSL_CTX_add_extra_chain_cert() — adds the certificate x509 to the extra chain certificates associated with ctx. and the bestie part? you can add several certificates, one after another, like stacking bracelets. obsessed. ✨
  • SSL_CTX_get_extra_chain_certs() — retrieves the extra chain certificates associated with ctx, OR, if the extra chain is empty, the chain associated with the current certificate of ctx. and here's the tea: the returned stack should not be freed by the caller. don't do it. it's not yours. 🙈
  • SSL_CTX_get_extra_chain_certs_only() — retrieves the extra chain certificates associated with ctx. just the extras, no substitutions, no surprises. and again: the returned stack should not be freed by the caller. periodt.
  • SSL_CTX_clear_extra_chain_certs() — clears ALL extra chain certificates associated with ctx. total reset. main character wipe-the-whiteboard energy. 💀
and the plot twist: these functions are implemented as macros. not real functions. macros. iykyk. 🧚

🌈 NOTES 🌈

when you're sending a certificate chain, the extra chain certificates go out in order following the end entity certificate. that's the lineup, respect the lineup. 👑

if no chain is specified, the library will try to complete the chain from the available CA certificates in the trusted CA storage — go check SSL_CTX_load_verify_locations(3). ✨

and the big one, the one you cannot skip: the x509 certificate you hand to SSL_CTX_add_extra_chain_cert() will be freed by the library when the SSL_CTX is destroyed. so an application should not free the x509 object. do not double free. i am literally begging. 😭

💜 RESTRICTIONS 💜

okay so. only one set of extra chain certificates can be specified per SSL_CTX structure. one. single. set.

which means different chains for different certificates — for example if both RSA and DSA certificates are specified by the same server — cannot be specified using this function. and neither can different SSL structures with the same parent SSL_CTX. nope. not happening here. 💀

want more flexibility? use functions such as SSL_add1_chain_cert() instead. that's your upgrade path, bestie. 🦋

⭐ RETURN VALUES ⭐

SSL_CTX_add_extra_chain_cert() and SSL_CTX_clear_extra_chain_certs() return 1 on success and 0 for failure. 🎀

and if you get a 0? check out the error stack to find out the reason for failure. don't just sit there guessing, the answer is right there. 💅

🔥 SEE ALSO 🔥

the whole friend group fr fr. go say hi. 🫶

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. 💖

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. 🌸

okay that's the whole page, you ate it, no crumbs left. this was OpenSSL 3.5.9, dated 2026-09-2, signing off — go build a chain, bestie, and remember: don't free that stack. 💅✨🎀

📦 where this page comes from