SSL_LOAD_CLIENT_CA_FILE(3) FreeBSD Library Functions Manual
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
#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
<
[email protected]> 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.
FreeBSD 14.1-RELEASE-p8 June 12, 2019 FreeBSD 14.1-RELEASE-p8