[thirdparty/openssl.git] / doc / man3 / SSL_load_client_CA_file.pod

=pod

=head1 NAME

SSL_load_client_CA_file,
SSL_add_file_cert_subjects_to_stack,
SSL_add_dir_cert_subjects_to_stack,
SSL_add_store_cert_subjects_to_stack
- load certificate names

=head1 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)
 int SSL_add_store_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
                                          const char *store)

=head1 DESCRIPTION

SSL_load_client_CA_file() reads certificates from I<file> and returns
a STACK_OF(X509_NAME) with the subject names found.

SSL_add_file_cert_subjects_to_stack() reads certificates from I<file>,
and adds their subject name to the already existing I<stack>.

SSL_add_dir_cert_subjects_to_stack() reads certificates from every
file in the directory I<dir>, and adds their subject name to the
already existing I<stack>.

SSL_add_store_cert_subjects_to_stack() loads certificates from the
I<store> URI, and adds their subject name to the already existing
I<stack>.

=head1 NOTES

SSL_load_client_CA_file() reads a file of PEM formatted certificates and
extracts the X509_NAMES of the certificates found. While the name suggests
the specific usage as support function for
L<SSL_CTX_set_client_CA_list(3)>,
it is not limited to CA certificates.

=head1 RETURN VALUES

The following return values can occur:

=over 4

=item NULL

The operation failed, check out the error stack for the reason.

=item Pointer to STACK_OF(X509_NAME)

Pointer to the subject names of the successfully read certificates.

=back

=head1 EXAMPLES

Load names of CAs from 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 */
 ...

=head1 SEE ALSO

L<ssl(7)>,
L<ossl_store(7)>,
L<SSL_CTX_set_client_CA_list(3)>

=head1 HISTORY

SSL_add_store_cert_subjects_to_stack() was added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.

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
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
356c06c7 RL	1	=pod
	2
	3	=head1 NAME
	4
ee669781 RL	5	SSL_load_client_CA_file,
	6	SSL_add_file_cert_subjects_to_stack,
	7	SSL_add_dir_cert_subjects_to_stack,
	8	SSL_add_store_cert_subjects_to_stack
	9	- load certificate names
356c06c7 RL	10
	11	=head1 SYNOPSIS
	12
	13	#include <openssl/ssl.h>
	14
	15	STACK_OF(X509_NAME) SSL_load_client_CA_file(const char file);
	16
ee669781 RL	17	int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
	18	const char *file)
	19	int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
	20	const char *dir)
	21	int SSL_add_store_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
	22	const char *store)
	23
356c06c7 RL	24	=head1 DESCRIPTION
356c06c7 RL	25
ee669781	26	SSL_load_client_CA_file() reads certificates from I<file> and returns
356c06c7 RL	27	a STACK_OF(X509_NAME) with the subject names found.
356c06c7 RL	28
ee669781 RL	29	SSL_add_file_cert_subjects_to_stack() reads certificates from I<file>,
	30	and adds their subject name to the already existing I<stack>.
	31
	32	SSL_add_dir_cert_subjects_to_stack() reads certificates from every
	33	file in the directory I<dir>, and adds their subject name to the
	34	already existing I<stack>.
	35
	36	SSL_add_store_cert_subjects_to_stack() loads certificates from the
	37	I<store> URI, and adds their subject name to the already existing
	38	I<stack>.
	39
356c06c7 RL	40	=head1 NOTES
	41
	42	SSL_load_client_CA_file() reads a file of PEM formatted certificates and
	43	extracts the X509_NAMES of the certificates found. While the name suggests
	44	the specific usage as support function for
9b86974e	45	L<SSL_CTX_set_client_CA_list(3)>,
356c06c7 RL	46	it is not limited to CA certificates.
356c06c7 RL	47
356c06c7 RL	48	=head1 RETURN VALUES
	49
	50	The following return values can occur:
	51
	52	=over 4
	53
	54	=item NULL
	55
	56	The operation failed, check out the error stack for the reason.
	57
	58	=item Pointer to STACK_OF(X509_NAME)
	59
	60	Pointer to the subject names of the successfully read certificates.
	61
	62	=back
	63
4564e77a PY	64	=head1 EXAMPLES
	65
	66	Load names of CAs from file and use it as a client CA list:
	67
	68	SSL_CTX *ctx;
	69	STACK_OF(X509_NAME) *cert_names;
	70
	71	...
	72	cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
	73	if (cert_names != NULL)
	74	SSL_CTX_set_client_CA_list(ctx, cert_names);
	75	else
	76	/* error */
	77	...
	78
356c06c7 RL	79	=head1 SEE ALSO
356c06c7 RL	80
b97fdb57	81	L<ssl(7)>,
ee669781	82	L<ossl_store(7)>,
9b86974e	83	L<SSL_CTX_set_client_CA_list(3)>
356c06c7	84
ee669781 RL	85	=head1 HISTORY
	86
	87	SSL_add_store_cert_subjects_to_stack() was added in OpenSSL 3.0.
	88
e2f92610 RS	89	=head1 COPYRIGHT
e2f92610 RS	90
ee669781	91	Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
e2f92610	92
4746f25a	93	Licensed under the Apache License 2.0 (the "License"). You may not use
e2f92610 RS	94	this file except in compliance with the License. You can obtain a copy
	95	in the file LICENSE in the source distribution or at
	96	L<https://www.openssl.org/source/license.html>.
	97
	98	=cut