1=pod
2
3=head1 NAME
4
5SSL_CTX_set_client_CA_list,
6SSL_set_client_CA_list,
7SSL_get_client_CA_list,
8SSL_CTX_get_client_CA_list,
9SSL_CTX_add_client_CA,
10SSL_add_client_CA,
11SSL_set0_CA_list,
12SSL_CTX_set0_CA_list,
13SSL_get0_CA_list,
14SSL_CTX_get0_CA_list,
15SSL_add1_to_CA_list,
16SSL_CTX_add1_to_CA_list,
17SSL_get0_peer_CA_list
18- get or set CA list
19
20=head1 SYNOPSIS
21
22 #include <openssl/ssl.h>
23
24 void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
25 void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
26 STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
27 STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
28 int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
29 int SSL_add_client_CA(SSL *ssl, X509 *cacert);
30
31 void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
32 void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
33 const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
34 const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
35 int SSL_CTX_add1_to_CA_list(SSL_CTX *ctx, const X509 *x);
36 int SSL_add1_to_CA_list(SSL *ssl, const X509 *x);
37
38 const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);
39
40=head1 DESCRIPTION
41
42The functions described here set and manage the list of CA names that are sent
43between two communicating peers.
44
45For TLS versions 1.2 and earlier the list of CA names is only sent from the
46server to the client when requesting a client certificate. So any list of CA
47names set is never sent from client to server and the list of CA names retrieved
48by SSL_get0_peer_CA_list() is always B<NULL>.
49
50For TLS 1.3 the list of CA names is sent using the B<certificate_authorities>
51extension and may be sent by a client (in the ClientHello message) or by
52a server (when requesting a certificate).
53
54In most cases it is not necessary to set CA names on the client side. The list
55of CA names that are acceptable to the client will be sent in plaintext to the
56server. This has privacy implications and may also have performance implications
57if the list is large. This optional capability was introduced as part of TLSv1.3
58and therefore setting CA names on the client side will have no impact if that
59protocol version has been disabled. Most servers do not need this and so this
60should be avoided unless required.
61
62The "client CA list" functions below only have an effect when called on the
63server side.
64
65SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
66requesting a client certificate for B<ctx>. Ownership of B<list> is transferred
67to B<ctx> and it should not be freed by the caller.
68
69SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
70requesting a client certificate for the chosen B<ssl>, overriding the
71setting valid for B<ssl>'s SSL_CTX object. Ownership of B<list> is transferred
72to B<s> and it should not be freed by the caller.
73
74SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
75B<ctx> using SSL_CTX_set_client_CA_list(). The returned list should not be freed
76by the caller.
77
78SSL_get_client_CA_list() returns the list of client CAs explicitly
79set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
80SSL_CTX_set_client_CA_list(), when in server mode. In client mode,
81SSL_get_client_CA_list returns the list of client CAs sent from the server, if
82any. The returned list should not be freed by the caller.
83
84SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
85list of CAs sent to the client when requesting a client certificate for
86B<ctx>.
87
88SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
89list of CAs sent to the client when requesting a client certificate for
90the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
91
92SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
93has sent. This can be called on either the server or the client side. The
94returned list should not be freed by the caller.
95
96The "generic CA list" functions below are very similar to the "client CA
97list" functions except that they have an effect on both the server and client
98sides. The lists of CA names managed are separate - so you cannot (for example)
99set CA names using the "client CA list" functions and then get them using the
100"generic CA list" functions. Where a mix of the two types of functions has been
101used on the server side then the "client CA list" functions take precedence.
102Typically, on the server side, the "client CA list " functions should be used in
103preference. As noted above in most cases it is not necessary to set CA names on
104the client side.
105
106SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to
107B<name_list>. Ownership of B<name_list> is transferred to B<ctx> and
108it should not be freed by the caller.
109
110SSL_set0_CA_list() sets the list of CAs to be sent to the peer to B<name_list>
111overriding any list set in the parent B<SSL_CTX> of B<s>. Ownership of
112B<name_list> is transferred to B<s> and it should not be freed by the caller.
113
114SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
115B<ctx>. The returned list should not be freed by the caller.
116
117SSL_get0_CA_list() retrieves any previously set list of CAs set for
118B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved. The
119returned list should not be freed by the caller.
120
121SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
122list of CAs sent to peer for B<ctx>.
123
124SSL_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
125list of CAs sent to the peer for B<s>, overriding the setting in the parent
126B<SSL_CTX>.
127
128=head1 NOTES
129
130When a TLS/SSL server requests a client certificate (see
131B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which it will accept
132certificates, to the client.
133
134This list must explicitly be set using SSL_CTX_set_client_CA_list() or
135SSL_CTX_set0_CA_list() for B<ctx> and SSL_set_client_CA_list() or
136SSL_set0_CA_list() for the specific B<ssl>. The list specified
137overrides the previous setting. The CAs listed do not become trusted (B<list>
138only contains the names, not the complete certificates); use
139L<SSL_CTX_load_verify_locations(3)> to additionally load them for verification.
140
141If the list of acceptable CAs is compiled in a file, the
142L<SSL_load_client_CA_file(3)> function can be used to help to import the
143necessary data.
144
145SSL_CTX_add_client_CA(), SSL_CTX_add1_to_CA_list(), SSL_add_client_CA() and
146SSL_add1_to_CA_list() can be used to add additional items the list of CAs. If no
147list was specified before using SSL_CTX_set_client_CA_list(),
148SSL_CTX_set0_CA_list(), SSL_set_client_CA_list() or SSL_set0_CA_list(), a
149new CA list for B<ctx> or B<ssl> (as appropriate) is opened.
150
151=head1 RETURN VALUES
152
153SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(),
154SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), SSL_CTX_set0_CA_list()
155and SSL_set0_CA_list() do not return a value.
156
157SSL_CTX_get_client_CA_list(), SSL_get_client_CA_list(), SSL_CTX_get0_CA_list()
158and SSL_get0_CA_list() return a stack of CA names or B<NULL> is no CA names are
159set.
160
161SSL_CTX_add_client_CA(),SSL_add_client_CA(), SSL_CTX_add1_to_CA_list() and
162SSL_add1_to_CA_list() return 1 for success and 0 for failure.
163
164SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
165B<NULL> or an empty stack if no list was sent.
166
167=head1 EXAMPLES
168
169Scan all certificates in B<CAfile> and list them as acceptable CAs:
170
171 SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
172
173=head1 SEE ALSO
174
175L<ssl(7)>,
176L<SSL_load_client_CA_file(3)>,
177L<SSL_CTX_load_verify_locations(3)>
178
179=head1 COPYRIGHT
180
181Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
182
183Licensed under the OpenSSL license (the "License").  You may not use
184this file except in compliance with the License.  You can obtain a copy
185in the file LICENSE in the source distribution or at
186L<https://www.openssl.org/source/license.html>.
187
188=cut
189