SSL_CTX_ADD_EXTRA_CHAIN_CERT(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 NAME 💖

okay so bestie, gather round, because today we're talking about the girlies that handle extra chain certificates: SSL_CTX_add_extra_chain_cert, SSL_CTX_get_extra_chain_certs, SSL_CTX_get_extra_chain_certs_only, and SSL_CTX_clear_extra_chain_certs. Their whole thing? add, get, or clear those extra chain certs. that's it, that's the job, and they ate 💅

this is all part of the OpenSSL 3SSL manual, so you already know it's iconic.

✨ SYNOPSIS ✨

like, here's the actual shape of it, no notes:

#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);

🌸 DESCRIPTION 🌸

okay so like, one by one, here's the tea:

  • SSL_CTX_add_extra_chain_cert() — this one adds the certificate x509 to the extra chain certificates that are associated with ctx. and the vibe? you can add several certificates, one after another. stack 'em up bestie 🫶
  • SSL_CTX_get_extra_chain_certs() — this one retrieves the extra chain certificates associated with ctx. but plot twist: if the extra chain is empty, it hands you the chain associated with the current certificate of ctx instead. and important — the returned stack should not be freed by the caller. do not touch, do not free, it's not yours 💀
  • SSL_CTX_get_extra_chain_certs_only() — this one retrieves just the extra chain certificates associated with ctx. no fallback, no surprises. and same rule, bestie: the returned stack should not be freed by the caller.
  • SSL_CTX_clear_extra_chain_certs() — and this one? it clears all the extra chain certificates associated with ctx. clean slate, fresh start, slay ✨

oh and also, lowkey important: all of these functions are implemented as macros.

🦋 NOTES 🦋

when you're sending a certificate chain, the extra chain certificates get sent in order, following the end entity certificate. so like, order matters, don't be chaotic about it.

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

⚠️ okay this part is so important: 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. not you. not ever. the library has custody, periodt 😭

🎀 RESTRICTIONS 🎀

and now the fine print, because there is always fine print:

only one set of extra chain certificates can be specified per SSL_CTX structure. so like, different chains for different certificates — for example, if both RSA and DSA certificates are specified by the same server — or different SSL structures with the same parent SSL_CTX? yeah, none of that can be specified using this function. it's giving limited range 💀

for more flexibility, functions such as SSL_add1_chain_cert() should be used instead.

💜 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 failure? check out the error stack to find out the reason. the error stack will tell you what went wrong, bestie, it's the group chat receipts 🔥

⭐ SEE ALSO ⭐

go read these next, iykyk:

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>.

and that's the whole page bestie, no cap 💖 this was OpenSSL 4.0.3, dated 2026-09-29, the SSL_CTX_ADD_EXTRA_CHAIN_CERT(3SSL) page — go forth and manage your chains responsibly, mwah 🎀✨

📦 where this page comes from