doc/man3/SSL_CTX_set0_CA_list.pod - third_party/openssl - Git at Google

 =pod

 =head1 NAME

 SSL_CTX_set_client_CA_list,
 SSL_set_client_CA_list,
 SSL_get_client_CA_list,
 SSL_CTX_get_client_CA_list,
 SSL_CTX_add_client_CA,
 SSL_add_client_CA,
 SSL_set0_CA_list,
 SSL_CTX_set0_CA_list,
 SSL_get0_CA_list,
 SSL_CTX_get0_CA_list,
 SSL_add1_to_CA_list,
 SSL_CTX_add1_to_CA_list,
 SSL_get0_peer_CA_list
 - get or set CA list

 =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);
  STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
  STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
  int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
  int SSL_add_client_CA(SSL *ssl, X509 *cacert);

  void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
  void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
  const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
  const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
  int SSL_CTX_add1_to_CA_list(SSL_CTX *ctx, const X509 *x);
  int SSL_add1_to_CA_list(SSL *ssl, const X509 *x);

  const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);

 =head1 DESCRIPTION

 The functions described here set and manage the list of CA names that are sent
 between two communicating peers.

 For TLS versions 1.2 and earlier the list of CA names is only sent from the
 server to the client when requesting a client certificate. So any list of CA
 names set is never sent from client to server and the list of CA names retrieved
 by SSL_get0_peer_CA_list() is always B<NULL>.

 For TLS 1.3 the list of CA names is sent using the B<certificate_authorities>
 extension and may be sent by a client (in the ClientHello message) or by
 a server (when requesting a certificate).

 In most cases it is not necessary to set CA names on the client side. The list
 of CA names that are acceptable to the client will be sent in plaintext to the
 server. This has privacy implications and may also have performance implications
 if the list is large. This optional capability was introduced as part of TLSv1.3
 and therefore setting CA names on the client side will have no impact if that
 protocol version has been disabled. Most servers do not need this and so this
 should be avoided unless required.

 The "client CA list" functions below only have an effect when called on the
 server side.

 SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
 requesting a client certificate for B<ctx>. Ownership of B<list> is transferred
 to B<ctx> and it should not be freed by the caller.

 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. Ownership of B<list> is transferred
 to B<s> and it should not be freed by the caller.

 SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
 B<ctx> using SSL_CTX_set_client_CA_list(). The returned list should not be freed
 by the caller.

 SSL_get_client_CA_list() returns the list of client CAs explicitly
 set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
 SSL_CTX_set_client_CA_list(), when in server mode. In client mode,
 SSL_get_client_CA_list returns the list of client CAs sent from the server, if
 any. The returned list should not be freed by the caller.

 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.

 SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
 has sent. This can be called on either the server or the client side. The
 returned list should not be freed by the caller.

 The "generic CA list" functions below are very similar to the "client CA
 list" functions except that they have an effect on both the server and client
 sides. The lists of CA names managed are separate - so you cannot (for example)
 set CA names using the "client CA list" functions and then get them using the
 "generic CA list" functions. Where a mix of the two types of functions has been
 used on the server side then the "client CA list" functions take precedence.
 Typically, on the server side, the "client CA list " functions should be used in
 preference. As noted above in most cases it is not necessary to set CA names on
 the client side.

 SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to
 B<name_list>. Ownership of B<name_list> is transferred to B<ctx> and
 it should not be freed by the caller.

 SSL_set0_CA_list() sets the list of CAs to be sent to the peer to B<name_list>
 overriding any list set in the parent B<SSL_CTX> of B<s>. Ownership of
 B<name_list> is transferred to B<s> and it should not be freed by the caller.

 SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
 B<ctx>. The returned list should not be freed by the caller.

 SSL_get0_CA_list() retrieves any previously set list of CAs set for
 B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved. The
 returned list should not be freed by the caller.

 SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
 list of CAs sent to peer for B<ctx>.

 SSL_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
 list of CAs sent to the peer for B<s>, overriding the setting in the parent
 B<SSL_CTX>.

 =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() or
 SSL_CTX_set0_CA_list() for B<ctx> and SSL_set_client_CA_list() or
 SSL_set0_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 to import the
 necessary data.

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

 =head1 RETURN VALUES

 SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(),
 SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), SSL_CTX_set0_CA_list()
 and SSL_set0_CA_list() do not return a value.

 SSL_CTX_get_client_CA_list(), SSL_get_client_CA_list(), SSL_CTX_get0_CA_list()
 and SSL_get0_CA_list() return a stack of CA names or B<NULL> is no CA names are
 set.

 SSL_CTX_add_client_CA(),SSL_add_client_CA(), SSL_CTX_add1_to_CA_list() and
 SSL_add1_to_CA_list() return 1 for success and 0 for failure.

 SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
 B<NULL> or an empty stack if no list was sent.

 =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(7)>,
 L<SSL_load_client_CA_file(3)>,
 L<SSL_CTX_load_verify_locations(3)>

 =head1 COPYRIGHT

 Copyright 2000-2018 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
	=pod

	=head1 NAME

	SSL_CTX_set_client_CA_list,
	SSL_set_client_CA_list,
	SSL_get_client_CA_list,
	SSL_CTX_get_client_CA_list,
	SSL_CTX_add_client_CA,
	SSL_add_client_CA,
	SSL_set0_CA_list,
	SSL_CTX_set0_CA_list,
	SSL_get0_CA_list,
	SSL_CTX_get0_CA_list,
	SSL_add1_to_CA_list,
	SSL_CTX_add1_to_CA_list,
	SSL_get0_peer_CA_list
	- get or set CA list

	=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);
	STACK_OF(X509_NAME) SSL_get_client_CA_list(const SSL s);
	STACK_OF(X509_NAME) SSL_CTX_get_client_CA_list(const SSL_CTX ctx);
	int SSL_CTX_add_client_CA(SSL_CTX ctx, X509 cacert);
	int SSL_add_client_CA(SSL ssl, X509 cacert);

	void SSL_CTX_set0_CA_list(SSL_CTX ctx, STACK_OF(X509_NAME) name_list);
	void SSL_set0_CA_list(SSL s, STACK_OF(X509_NAME) name_list);
	const STACK_OF(X509_NAME) SSL_CTX_get0_CA_list(const SSL_CTX ctx);
	const STACK_OF(X509_NAME) SSL_get0_CA_list(const SSL s);
	int SSL_CTX_add1_to_CA_list(SSL_CTX ctx, const X509 x);
	int SSL_add1_to_CA_list(SSL ssl, const X509 x);

	const STACK_OF(X509_NAME) SSL_get0_peer_CA_list(const SSL s);

	=head1 DESCRIPTION

	The functions described here set and manage the list of CA names that are sent
	between two communicating peers.

	For TLS versions 1.2 and earlier the list of CA names is only sent from the
	server to the client when requesting a client certificate. So any list of CA
	names set is never sent from client to server and the list of CA names retrieved
	by SSL_get0_peer_CA_list() is always B<NULL>.

	For TLS 1.3 the list of CA names is sent using the B<certificate_authorities>
	extension and may be sent by a client (in the ClientHello message) or by
	a server (when requesting a certificate).

	In most cases it is not necessary to set CA names on the client side. The list
	of CA names that are acceptable to the client will be sent in plaintext to the
	server. This has privacy implications and may also have performance implications
	if the list is large. This optional capability was introduced as part of TLSv1.3
	and therefore setting CA names on the client side will have no impact if that
	protocol version has been disabled. Most servers do not need this and so this
	should be avoided unless required.

	The "client CA list" functions below only have an effect when called on the
	server side.

	SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
	requesting a client certificate for B<ctx>. Ownership of B<list> is transferred
	to B<ctx> and it should not be freed by the caller.

	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. Ownership of B<list> is transferred
	to B<s> and it should not be freed by the caller.

	SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
	B<ctx> using SSL_CTX_set_client_CA_list(). The returned list should not be freed
	by the caller.

	SSL_get_client_CA_list() returns the list of client CAs explicitly
	set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
	SSL_CTX_set_client_CA_list(), when in server mode. In client mode,
	SSL_get_client_CA_list returns the list of client CAs sent from the server, if
	any. The returned list should not be freed by the caller.

	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.

	SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
	has sent. This can be called on either the server or the client side. The
	returned list should not be freed by the caller.

	The "generic CA list" functions below are very similar to the "client CA
	list" functions except that they have an effect on both the server and client
	sides. The lists of CA names managed are separate - so you cannot (for example)
	set CA names using the "client CA list" functions and then get them using the
	"generic CA list" functions. Where a mix of the two types of functions has been
	used on the server side then the "client CA list" functions take precedence.
	Typically, on the server side, the "client CA list " functions should be used in
	preference. As noted above in most cases it is not necessary to set CA names on
	the client side.

	SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to
	B<name_list>. Ownership of B<name_list> is transferred to B<ctx> and
	it should not be freed by the caller.

	SSL_set0_CA_list() sets the list of CAs to be sent to the peer to B<name_list>
	overriding any list set in the parent B<SSL_CTX> of B<s>. Ownership of
	B<name_list> is transferred to B<s> and it should not be freed by the caller.

	SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
	B<ctx>. The returned list should not be freed by the caller.

	SSL_get0_CA_list() retrieves any previously set list of CAs set for
	B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved. The
	returned list should not be freed by the caller.

	SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
	list of CAs sent to peer for B<ctx>.

	SSL_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
	list of CAs sent to the peer for B<s>, overriding the setting in the parent
	B<SSL_CTX>.

	=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() or
	SSL_CTX_set0_CA_list() for B<ctx> and SSL_set_client_CA_list() or
	SSL_set0_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 to import the
	necessary data.

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

	=head1 RETURN VALUES

	SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(),
	SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), SSL_CTX_set0_CA_list()
	and SSL_set0_CA_list() do not return a value.

	SSL_CTX_get_client_CA_list(), SSL_get_client_CA_list(), SSL_CTX_get0_CA_list()
	and SSL_get0_CA_list() return a stack of CA names or B<NULL> is no CA names are
	set.

	SSL_CTX_add_client_CA(),SSL_add_client_CA(), SSL_CTX_add1_to_CA_list() and
	SSL_add1_to_CA_list() return 1 for success and 0 for failure.

	SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
	B<NULL> or an empty stack if no list was sent.

	=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(7)>,
	L<SSL_load_client_CA_file(3)>,
	L<SSL_CTX_load_verify_locations(3)>

	=head1 COPYRIGHT

	Copyright 2000-2018 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