1SSL_CTX_SET0_CA_LIST(3)             OpenSSL            SSL_CTX_SET0_CA_LIST(3)
2
3
4

NAME

6       SSL_CTX_set_client_CA_list, SSL_set_client_CA_list,
7       SSL_get_client_CA_list, SSL_CTX_get_client_CA_list,
8       SSL_CTX_add_client_CA, SSL_add_client_CA, SSL_set0_CA_list,
9       SSL_CTX_set0_CA_list, SSL_get0_CA_list, SSL_CTX_get0_CA_list,
10       SSL_add1_to_CA_list, SSL_CTX_add1_to_CA_list, SSL_get0_peer_CA_list -
11       get or set CA list
12

SYNOPSIS

14        #include <openssl/ssl.h>
15
16        void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
17        void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
18        STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
19        STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
20        int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
21        int SSL_add_client_CA(SSL *ssl, X509 *cacert);
22
23        void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
24        void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
25        const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
26        const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
27        int SSL_CTX_add1_to_CA_list(SSL_CTX *ctx, const X509 *x);
28        int SSL_add1_to_CA_list(SSL *ssl, const X509 *x);
29
30        const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);
31

DESCRIPTION

33       The functions described here set and manage the list of CA names that
34       are sent between two communicating peers.
35
36       For TLS versions 1.2 and earlier the list of CA names is only sent from
37       the server to the client when requesting a client certificate. So any
38       list of CA names set is never sent from client to server and the list
39       of CA names retrieved by SSL_get0_peer_CA_list() is always NULL.
40
41       For TLS 1.3 the list of CA names is sent using the
42       certificate_authorities extension and may be sent by a client (in the
43       ClientHello message) or by a server (when requesting a certificate).
44
45       In most cases it is not necessary to set CA names on the client side.
46       The list of CA names that are acceptable to the client will be sent in
47       plaintext to the server. This has privacy implications and may also
48       have performance implications if the list is large. This optional
49       capability was introduced as part of TLSv1.3 and therefore setting CA
50       names on the client side will have no impact if that protocol version
51       has been disabled. Most servers do not need this and so this should be
52       avoided unless required.
53
54       The "client CA list" functions below only have an effect when called on
55       the server side.
56
57       SSL_CTX_set_client_CA_list() sets the list of CAs sent to the client
58       when requesting a client certificate for ctx. Ownership of list is
59       transferred to ctx and it should not be freed by the caller.
60
61       SSL_set_client_CA_list() sets the list of CAs sent to the client when
62       requesting a client certificate for the chosen ssl, overriding the
63       setting valid for ssl's SSL_CTX object. Ownership of list is
64       transferred to s and it should not be freed by the caller.
65
66       SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly
67       set for ctx using SSL_CTX_set_client_CA_list(). The returned list
68       should not be freed by the caller.
69
70       SSL_get_client_CA_list() returns the list of client CAs explicitly set
71       for ssl using SSL_set_client_CA_list() or ssl's SSL_CTX object with
72       SSL_CTX_set_client_CA_list(), when in server mode. In client mode,
73       SSL_get_client_CA_list returns the list of client CAs sent from the
74       server, if any. The returned list should not be freed by the caller.
75
76       SSL_CTX_add_client_CA() adds the CA name extracted from cacert to the
77       list of CAs sent to the client when requesting a client certificate for
78       ctx.
79
80       SSL_add_client_CA() adds the CA name extracted from cacert to the list
81       of CAs sent to the client when requesting a client certificate for the
82       chosen ssl, overriding the setting valid for ssl's SSL_CTX object.
83
84       SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the
85       peer has sent. This can be called on either the server or the client
86       side. The returned list should not be freed by the caller.
87
88       The "generic CA list" functions below are very similar to the "client
89       CA list" functions except that they have an effect on both the server
90       and client sides. The lists of CA names managed are separate - so you
91       cannot (for example) set CA names using the "client CA list" functions
92       and then get them using the "generic CA list" functions. Where a mix of
93       the two types of functions has been used on the server side then the
94       "client CA list" functions take precedence.  Typically, on the server
95       side, the "client CA list " functions should be used in preference. As
96       noted above in most cases it is not necessary to set CA names on the
97       client side.
98
99       SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to
100       name_list. Ownership of name_list is transferred to ctx and it should
101       not be freed by the caller.
102
103       SSL_set0_CA_list() sets the list of CAs to be sent to the peer to
104       name_list overriding any list set in the parent SSL_CTX of s. Ownership
105       of name_list is transferred to s and it should not be freed by the
106       caller.
107
108       SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
109       ctx. The returned list should not be freed by the caller.
110
111       SSL_get0_CA_list() retrieves any previously set list of CAs set for s
112       or if none are set the list from the parent SSL_CTX is retrieved. The
113       returned list should not be freed by the caller.
114
115       SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from x
116       to the list of CAs sent to peer for ctx.
117
118       SSL_add1_to_CA_list() appends the CA subject name extracted from x to
119       the list of CAs sent to the peer for s, overriding the setting in the
120       parent SSL_CTX.
121

NOTES

123       When a TLS/SSL server requests a client certificate (see
124       SSL_CTX_set_verify(3)), it sends a list of CAs, for which it will
125       accept certificates, to the client.
126
127       This list must explicitly be set using SSL_CTX_set_client_CA_list() or
128       SSL_CTX_set0_CA_list() for ctx and SSL_set_client_CA_list() or
129       SSL_set0_CA_list() for the specific ssl. The list specified overrides
130       the previous setting. The CAs listed do not become trusted (list only
131       contains the names, not the complete certificates); use
132       SSL_CTX_load_verify_locations(3) to additionally load them for
133       verification.
134
135       If the list of acceptable CAs is compiled in a file, the
136       SSL_load_client_CA_file(3) function can be used to help to import the
137       necessary data.
138
139       SSL_CTX_add_client_CA(), SSL_CTX_add1_to_CA_list(), SSL_add_client_CA()
140       and SSL_add1_to_CA_list() can be used to add additional items the list
141       of CAs. If no list was specified before using
142       SSL_CTX_set_client_CA_list(), SSL_CTX_set0_CA_list(),
143       SSL_set_client_CA_list() or SSL_set0_CA_list(), a new CA list for ctx
144       or ssl (as appropriate) is opened.
145

RETURN VALUES

147       SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(),
148       SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(),
149       SSL_CTX_set0_CA_list() and SSL_set0_CA_list() do not return a value.
150
151       SSL_CTX_get_client_CA_list(), SSL_get_client_CA_list(),
152       SSL_CTX_get0_CA_list() and SSL_get0_CA_list() return a stack of CA
153       names or NULL is no CA names are set.
154
155       SSL_CTX_add_client_CA(),SSL_add_client_CA(), SSL_CTX_add1_to_CA_list()
156       and SSL_add1_to_CA_list() return 1 for success and 0 for failure.
157
158       SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
159       NULL or an empty stack if no list was sent.
160

EXAMPLES

162       Scan all certificates in CAfile and list them as acceptable CAs:
163
164        SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
165

SEE ALSO

167       ssl(7), SSL_load_client_CA_file(3), SSL_CTX_load_verify_locations(3)
168
170       Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
171
172       Licensed under the OpenSSL license (the "License").  You may not use
173       this file except in compliance with the License.  You can obtain a copy
174       in the file LICENSE in the source distribution or at
175       <https://www.openssl.org/source/license.html>.
176
177
178
1791.1.1d                            2019-10-03           SSL_CTX_SET0_CA_LIST(3)
Impressum