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