SSL_LOAD_CLIENT_CA_FILE(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

🌸 NAME 🌸

okay so bestie, this is the SSL_LOAD_CLIENT_CA_FILE(3) page from the Library Functions Manual, and it's all about loading certificate names from files. the main characters are SSL_load_client_CA_file, SSL_add_file_cert_subjects_to_stack, and SSL_add_dir_cert_subjects_to_stack — and yes, they ate. 💅

✨ SYNOPSIS ✨

the whole libssl / libcrypto include situation is literally this, no cap:

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

STACK_OF(X509_NAME) *
SSL_load_client_CA_file(const char *file);

int
SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
    const char *file);

int
SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
    const char *dir);

🦋 DESCRIPTION 🦋

SSL_load_client_CA_file() is the main character here: it reads PEM formatted certificates from file and returns a new STACK_OF(X509_NAME) with the subject names found. and yeah, the name is giving “support function for SSL_CTX_set_client_CA_list(3)” energy, but it is not limited to CA certificates. periodt.

SSL_add_file_cert_subjects_to_stack() is similar, except the names are added to the existing stack.

SSL_add_dir_cert_subjects_to_stack() has directory-gremlin energy: it calls SSL_add_file_cert_subjects_to_stack() on every file in the directory dir.

if a name is already on the stack, all these functions skip it and do not add it again — no duplicates, no stress. 🎀

💖 RETURN VALUES 💖

  • SSL_load_client_CA_file() returns a pointer to the new STACK_OF(X509_NAME) or NULL on failure.
  • SSL_add_file_cert_subjects_to_stack() and SSL_add_dir_cert_subjects_to_stack() return 1 for success or 0 for failure.
  • all these functions treat empty files and directories as failures. yes bestie, empty = fail.
  • in some cases of failure, the reason can be determined with ERR_get_error(3).

🌈 EXAMPLES 🌈

load names of CAs from a file and use it as a client CA list — the manual literally shows this:

SSL_CTX *ctx;
STACK_OF(X509_NAME) *cert_names;
...
cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
if (cert_names != NULL)
        SSL_CTX_set_client_CA_list(ctx, cert_names);
else
        error_handling();
...

🔥 SEE ALSO 🔥

go read these too, iykyk:

🧚 HISTORY 🧚

history lesson, but make it cute:

  • SSL_load_client_CA_file() first appeared in SSLeay 0.8.0 and has been available since OpenBSD 2.4.
  • SSL_add_file_cert_subjects_to_stack() and SSL_add_dir_cert_subjects_to_stack() first appeared in OpenSSL 0.9.2b and have been available since OpenBSD 2.6.

👑 AUTHORS 👑

SSL_add_file_cert_subjects_to_stack() and SSL_add_dir_cert_subjects_to_stack() were written by Ben Laurie (<ben@openssl.org>) in 1999. iconic behavior, honestly. 💜

💀 BUGS 💀

okay bestie, read this part before you ship, fr fr:

  • in some cases of failure, for example for empty files and directories, these functions fail to report an error, in the sense that ERR_get_error(3) does not work.
  • even in case of failure, for example when parsing one of the files or certificates fails, SSL_add_file_cert_subjects_to_stack() and SSL_add_dir_cert_subjects_to_stack() may still have added some certificates to the stack.
  • the behaviour of SSL_add_dir_cert_subjects_to_stack() is non-deterministic. if parsing one file fails, parsing of the whole directory is aborted. files in the directory are not parsed in any specific order. for example, adding an empty file to dir may or may not cause some of the other files to be ignored.

this page came from Debian and is dated June 8, 2025; the manual is SSL_LOAD_CLIENT_CA_FILE(3). bye bestie, go be iconic with those cert names 💅✨

📦 where this page comes from