LIBRESSL-SSL_CTX_SET_MAX_CERT_LIST(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 SSL_CTX_SET_MAX_CERT_LIST(3) 💅

okay so this is a page from the Library Functions Manual, and it's all about the libssl / libcrypto girlies — the four functions SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list and SSL_get_max_cert_list, which are literally just here to "manipulate allowed size for the peer's certificate chain". periodt.

✨ SYNOPSIS ✨

like, first you gotta pull in the library and the header, bestie:

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

then the actual function signatures, no cap, exactly like this:

long
SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size);

long
SSL_CTX_get_max_cert_list(SSL_CTX *ctx);

long
SSL_set_max_cert_list(SSL *ssl, long size);

long
SSL_get_max_cert_list(SSL *ctx);

(and yes, SSL_get_max_cert_list takes SSL *ctx up there — that's what the page says, so we're keeping it, iykyk 🫶)

🎀 DESCRIPTION 🎀

the setters and getters, one by one

  • SSL_CTX_set_max_cert_list() — sets the maximum size allowed for the peer's certificate chain, for all the SSL objects created from ctx, to size bytes. And the way inheritance works: those SSL objects pick up whatever setting was valid for ctx at the exact time SSL_new(3) gets called. so timing matters, bestie ⏰
  • SSL_CTX_get_max_cert_list() — just tells you the currently set maximum size for ctx. a little peek, no drama.
  • SSL_set_max_cert_list() — sets the maximum size allowed for the peer's certificate chain for ssl to size bytes. and this setting stays valid until you set a new value. it's giving committed 💅
  • SSL_get_max_cert_list() — returns the currently set maximum size for ssl. that's it, that's the whole vibe.

okay but why does this exist tho

so during the handshake process, the peer may send a certificate chain. and the TLS/SSL standard is out here giving us no maximum size for that chain. like, zero guidance 😭. the OpenSSL library handles incoming data with a dynamically allocated buffer, and to prevent that buffer from growing without bound (because a faulty or malicious peer is out there and will absolutely try it), a maximum size for the certificate chain is set. protective queen behavior 👑

the defaults, and why they're actually fine

the default value for the maximum certificate chain size is 100kB — and heads up, it's 30kB on the 16bit DOS platform 🕹️. this should be sufficient for usual certificate chains, and here's the receipts:

  • OpenSSL's default maximum chain length is 10 (see SSL_CTX_set_verify(3))
  • certificates without special extensions have a typical size of 1-2kB

so like... the math is mathing, she's fine 🌸

when you might actually want to go bigger

for special applications it can be necessary to extend the maximum certificate chain size allowed to be sent by the peer. see for example the work on Internet X.509 Public Key Infrastructure Proxy Certificate Profile and TLS Delegation Protocol at https://www.ietf.org/ and http://www.globus.org/. niche but iconic.

under normal conditions it should never be necessary to set a value smaller than the default, because the buffer is handled dynamically and only uses the memory actually required by the data sent by the peer. so like, don't be weird about it 🙈

what happens if you exceed it

if the maximum certificate chain size allowed is exceeded, the handshake will fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error. handshake cancelled, party's over, everybody go home 💀

💖 RETURN VALUES 💖

  • SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously set value. (yes, they remember the ex 💅)
  • SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently set value.

🦋 SEE ALSO 🦋

go read these next, bestie, they're all connected:

🌈 HISTORY 🌈

these functions first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2. generational icons, literally 👑

and that's the whole page, bestie — mwah 💋 this cutie was brought to you by Debian, dated June 8, 2025, and it lives at SSL_CTX_SET_MAX_CERT_LIST(3). slay, stay safe, and don't set your cert list size to something silly 🎀✨

📦 where this page comes from