[thirdparty/openssl.git] / doc / ssl / SSL_CTX_set_client_CA_list.pod

=pod

=head1 NAME

SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
SSL_add_client_CA - set list of CAs sent to the client when requesting a
client certificate

=head1 SYNOPSIS

 #include <openssl/ssl.h>
 
 void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
 void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
 int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
 int SSL_add_client_CA(SSL *ssl, X509 *cacert);

=head1 DESCRIPTION

SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
requesting a client certificate for B<ctx>.

SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
requesting a client certificate for the chosen B<ssl>, overriding the
setting valid for B<ssl>'s SSL_CTX object.

SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
list of CAs sent to the client when requesting a client certificate for
B<ctx>.

SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
list of CAs sent to the client when requesting a client certificate for
the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.

=head1 NOTES

When a TLS/SSL server requests a client certificate (see
B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
it will accept certificates, to the client.

This list must explicitly be set using SSL_CTX_set_client_CA_list() for
B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
specified overrides the previous setting. The CAs listed do not become
trusted (B<list> only contains the names, not the complete certificates); use
L<SSL_CTX_load_verify_locations(3)> 
to additionally load them for verification.

If the list of acceptable CAs is compiled in a file, the
L<SSL_load_client_CA_file(3)>
function can be used to help importing the necessary data.

SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
items the list of client CAs. If no list was specified before using
SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
CA list for B<ctx> or B<ssl> (as appropriate) is opened.

These functions are only useful for TLS/SSL servers.

=head1 RETURN VALUES

SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
diagnostic information.

SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
values:

=over 4

=item Z<>0

A failure while manipulating the STACK_OF(X509_NAME) object occurred or
the X509_NAME could not be extracted from B<cacert>. Check the error stack
to find out the reason.

=item Z<>1

The operation succeeded.

=back

=head1 EXAMPLES

Scan all certificates in B<CAfile> and list them as acceptable CAs:

  SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));

=head1 SEE ALSO

L<ssl(3)>,
L<SSL_get_client_CA_list(3)>,
L<SSL_load_client_CA_file(3)>,
L<SSL_CTX_load_verify_locations(3)>

=cut

=head1 COPYRIGHT

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

Licensed under the OpenSSL license (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
	5	SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
	6	SSL_add_client_CA - set list of CAs sent to the client when requesting a
	7	client certificate
	8
	9	=head1 SYNOPSIS
	10
	11	#include <openssl/ssl.h>
	12
	13	void SSL_CTX_set_client_CA_list(SSL_CTX ctx, STACK_OF(X509_NAME) list);
	14	void SSL_set_client_CA_list(SSL s, STACK_OF(X509_NAME) list);
	15	int SSL_CTX_add_client_CA(SSL_CTX ctx, X509 cacert);
	16	int SSL_add_client_CA(SSL ssl, X509 cacert);
	17
	18	=head1 DESCRIPTION
	19
	20	SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
	21	requesting a client certificate for B<ctx>.
	22
	23	SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
	24	requesting a client certificate for the chosen B<ssl>, overriding the
	25	setting valid for B<ssl>'s SSL_CTX object.
	26
	27	SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
	28	list of CAs sent to the client when requesting a client certificate for
	29	B<ctx>.
	30
	31	SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
	32	list of CAs sent to the client when requesting a client certificate for
	33	the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
	34
	35	=head1 NOTES
	36
	37	When a TLS/SSL server requests a client certificate (see
fc1d88f0	38	B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
638b0d42	39	it will accept certificates, to the client.
356c06c7	40
638b0d42	41	This list must explicitly be set using SSL_CTX_set_client_CA_list() for
356c06c7 RL	42	B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
	43	specified overrides the previous setting. The CAs listed do not become
	44	trusted (B<list> only contains the names, not the complete certificates); use
9b86974e	45	L<SSL_CTX_load_verify_locations(3)>
356c06c7 RL	46	to additionally load them for verification.
356c06c7 RL	47
638b0d42	48	If the list of acceptable CAs is compiled in a file, the
9b86974e	49	L<SSL_load_client_CA_file(3)>
638b0d42 LJ	50	function can be used to help importing the necessary data.
638b0d42 LJ	51
356c06c7 RL	52	SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
	53	items the list of client CAs. If no list was specified before using
	54	SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
638b0d42	55	CA list for B<ctx> or B<ssl> (as appropriate) is opened.
356c06c7 RL	56
	57	These functions are only useful for TLS/SSL servers.
	58
	59	=head1 RETURN VALUES
	60
	61	SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
	62	diagnostic information.
	63
	64	SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
	65	values:
	66
	67	=over 4
	68
c8919dde	69	=item Z<>0
356c06c7	70
52d160d8	71	A failure while manipulating the STACK_OF(X509_NAME) object occurred or
356c06c7 RL	72	the X509_NAME could not be extracted from B<cacert>. Check the error stack
	73	to find out the reason.
	74
c8919dde	75	=item Z<>1
5cc27077 NA	76
	77	The operation succeeded.
	78
356c06c7 RL	79	=back
356c06c7 RL	80
638b0d42 LJ	81	=head1 EXAMPLES
	82
	83	Scan all certificates in B<CAfile> and list them as acceptable CAs:
	84
	85	SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));
	86
356c06c7 RL	87	=head1 SEE ALSO
356c06c7 RL	88
9b86974e RS	89	L<ssl(3)>,
	90	L<SSL_get_client_CA_list(3)>,
	91	L<SSL_load_client_CA_file(3)>,
	92	L<SSL_CTX_load_verify_locations(3)>
356c06c7 RL	93
356c06c7 RL	94	=cut
e2f92610 RS	95
	96	=head1 COPYRIGHT
	97
	98	Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
	99
	100	Licensed under the OpenSSL license (the "License"). You may not use
	101	this file except in compliance with the License. You can obtain a copy
	102	in the file LICENSE in the source distribution or at
	103	L<https://www.openssl.org/source/license.html>.
	104
	105	=cut