SSL_CTX_SET0_CA_LIST(3SSL)

📦

version 4.0.3 · 14 versions

💖 SSL_CTX_SET0_CA_LIST 💖

(that's the `3SSL` manual, bestie — OpenSSL's CA-list gang)

okay so. you know how TLS servers be like "hey show me your ID" and the client's like "which ID tho"? that's literally this whole page. it's the get-or-set-CA-list lore. buckle up 🎀

✨ NAME ✨

SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_get_client_CA_list, SSL_CTX_get_client_CA_list, SSL_CTX_add_client_CA, SSL_add_client_CA, SSL_set0_CA_list, SSL_CTX_set0_CA_list, SSL_get0_CA_list, SSL_CTX_get0_CA_list, SSL_add1_to_CA_list, SSL_CTX_add1_to_CA_list, SSL_get0_peer_CA_list — get or set CA list 💅

like. it's the CA list. getting it, setting it. that's the vibe.

🌸 SYNOPSIS 🌸

#include <openssl/ssl.h>

void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
int SSL_add_client_CA(SSL *ssl, X509 *cacert);

void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
int SSL_CTX_add1_to_CA_list(SSL_CTX *ctx, const X509 *x);
int SSL_add1_to_CA_list(SSL *ssl, const X509 *x);

const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);

look at all those little STACK_OF(X509_NAME)s. iconic. no notes. 👑

🦋 DESCRIPTION 🦋

so these functions here? they set and manage the list of CA names that get sent between two communicating peers. two peers. communicating. we love a handshake.

TLS 1.2 and earlier — the CA name list only goes from server to client, and only when the server is requesting a client certificate. so any list you set is never sent from client to server, and the list you'd get back from SSL_get0_peer_CA_list() is always NULL. yeah. always. you're not getting anything. 🙈

TLS 1.3 — now the CA name list gets sent using the certificate_authorities extension, and it may be sent by a client (in the ClientHello message) or by a server (when requesting a certificate). glow up fr fr ✨

in most cases you do not need to set CA names on the client side. the list of CA names that are acceptable to the client will be sent in plaintext to the server. this has privacy implications and may also have performance implications if the list is large. this optional capability was introduced as part of TLSv1.3, so setting CA names on the client side will have no impact if that protocol version has been disabled. most servers do not need this, and so this should be avoided unless required.

💜 the "client CA list" functions 💜

heads up bestie: these ones only have an effect when called on the server side.

SSL_CTX_set_client_CA_list() — sets the list of CAs sent to the client when requesting a client certificate for ctx. ownership of list is transferred to ctx and it should not be freed by the caller. it's not yours anymore, it's ctx's now. 🫶
SSL_set_client_CA_list() — sets the list of CAs sent to the client when requesting a client certificate for the chosen ssl, overriding the setting valid for ssl's SSL_CTX object. ownership of list is transferred to s and it should not be freed by the caller. also!! passing NULL for list does not clear the CA list — instead, the setting from ssl's SSL_CTX object will be used. and also also!! passing an empty stack created with sk_X509_NAME_new_null() will clear the per-connection client CA list, but during the handshake the generic CA list (set via SSL_CTX_set0_CA_list(3)) may still be used as a fallback. sneaky little fallback 😭
SSL_CTX_get_client_CA_list() — returns the list of client CAs explicitly set for ctx using SSL_CTX_set_client_CA_list(). the returned list should not be freed by the caller.
SSL_get_client_CA_list() — returns the list of client CAs explicitly set for ssl using SSL_set_client_CA_list() or ssl's SSL_CTX object with SSL_CTX_set_client_CA_list(), when in server mode. in client mode, SSL_get_client_CA_list returns the list of client CAs sent from the server, if any. the returned list should not be freed by the caller.
SSL_CTX_add_client_CA() — adds the CA name extracted from cacert to the list of CAs sent to the client when requesting a client certificate for ctx.
SSL_add_client_CA() — adds the CA name extracted from cacert to the list of CAs sent to the client when requesting a client certificate for the chosen ssl, overriding the setting valid for ssl's SSL_CTX object.
SSL_get0_peer_CA_list() — retrieves the list of CA names (if any) the peer has sent. this can be called on either the server or the client side. the returned list should not be freed by the caller.

🌈 the "generic CA list" functions 🌈

these are very similar to the "client CA list" functions except they hit both the server and client sides. main character energy, honestly.

the lists of CA names they manage are separate — so you cannot (for example) set CA names using the "client CA list" functions and then get them using the "generic CA list" functions. two different friend groups, no crossover episodes. 💀

where a mix of the two types of functions has been used on the server side, then the "client CA list" functions take precedence. typically, on the server side, the "client CA list" functions should be used in preference. and as noted above, in most cases it is not necessary to set CA names on the client side.

SSL_CTX_set0_CA_list() — sets the list of CAs to be sent to the peer to name_list. ownership of name_list is transferred to ctx and it should not be freed by the caller.
SSL_set0_CA_list() — sets the list of CAs to be sent to the peer to name_list, overriding any list set in the parent SSL_CTX of s. ownership of name_list is transferred to s and it should not be freed by the caller.
SSL_CTX_get0_CA_list() — retrieves any previously set list of CAs set for ctx. the returned list should not be freed by the caller.
SSL_get0_CA_list() — retrieves any previously set list of CAs set for s, or if none are set, the list from the parent SSL_CTX is retrieved. the returned list should not be freed by the caller.
SSL_CTX_add1_to_CA_list() — appends the CA subject name extracted from x to the list of CAs sent to peer for ctx.
SSL_add1_to_CA_list() — appends the CA subject name extracted from x to the list of CAs sent to the peer for s, overriding the setting in the parent SSL_CTX.

🎀 NOTES 🎀

when a TLS/SSL server requests a client certificate (peep SSL_CTX_set_verify(3)), it sends a list of CAs — the ones it will accept certificates for — to the client. like a guest list. but for certs. 💌

this list must explicitly be set using SSL_CTX_set_client_CA_list() or SSL_CTX_set0_CA_list() for ctx, and SSL_set_client_CA_list() or SSL_set0_CA_list() for the specific ssl. the list specified overrides the previous setting. and listen — the CAs listed do not become trusted. the list only contains the names, not the complete certificates. if you actually want them trusted for verification, use SSL_CTX_load_verify_locations(3) to additionally load them. names ≠ trust, bestie, that's the whole lesson 😤

if the list of acceptable CAs is compiled in a file, the SSL_load_client_CA_file(3) function can be used to help import the necessary data. helping hand. we love her.

SSL_CTX_add_client_CA(), SSL_CTX_add1_to_CA_list(), SSL_add_client_CA() and SSL_add1_to_CA_list() can be used to add additional items to the list of CAs. and if no list was specified before using SSL_CTX_set_client_CA_list(), SSL_CTX_set0_CA_list(), SSL_set_client_CA_list() or SSL_set0_CA_list(), a new CA list for ctx or ssl (as appropriate) is opened.

💀 RETURN VALUES 💀

SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), SSL_CTX_set0_CA_list() and SSL_set0_CA_list() do not return a value. nothing. void. they said "no thoughts head empty" 🫥
SSL_CTX_get_client_CA_list(), SSL_get_client_CA_list(), SSL_CTX_get0_CA_list() and SSL_get0_CA_list() return a stack of CA names, or NULL if no CA names are set.
SSL_CTX_add_client_CA(), SSL_add_client_CA(), SSL_CTX_add1_to_CA_list() and SSL_add1_to_CA_list() return 1 for success and 0 for failure.
SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer, or NULL, or an empty stack, if no list was sent. three whole moods.

🌟 EXAMPLES 🌟

scan all certificates in CAfile and list them as acceptable CAs — look how tidy:

SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));

one line!! she ate and left no crumbs 🔥

the whole squad. go read them. iykyk 💅

💖 COPYRIGHT 💖

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 bestie, you're officially CA-list literate 🧚✨ this was OpenSSL 4.0.3, dated 2026-09-29, and the page is SSL_CTX_SET0_CA_LIST(3SSL). go forth and set some CA lists (on the server side, please, we talked about this) 🍓💜

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

SSL_CTX_SET0_CA_LIST(3SSL)