SSL_LOAD_CLIENT_CA_FILE(3) | Library Functions Manual | SSL_LOAD_CLIENT_CA_FILE(3)

# NAME

`SSL_load_client_CA_file`, `SSL_add_file_cert_subjects_to_stack`, `SSL_add_dir_cert_subjects_to_stack` — load certificate names from files

# SYNOPSIS

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`() reads PEM formatted certificates from file and returns a new STACK_OF(X509_NAME) with the subject names found. While the name suggests the specific usage as a support function for SSL_CTX_set_client_CA_list(3), it is not limited to CA certificates.

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

`SSL_add_dir_cert_subjects_to_stack`() 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.

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

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:

    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

PEM_read_bio_X509(3), ssl(3), SSL_CTX_set_client_CA_list(3), X509_get_subject_name(3), X509_NAME_new(3)

# HISTORY

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

# BUGS

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.

June 8, 2025 | Debian