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