Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set0_CA_list.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET0_CA_LIST 3SSL"
58 .TH SSL_CTX_SET0_CA_LIST 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_client_CA_list,
65 SSL_set_client_CA_list,
66 SSL_get_client_CA_list,
67 SSL_CTX_get_client_CA_list,
68 SSL_CTX_add_client_CA,
69 SSL_add_client_CA,
70 SSL_set0_CA_list,
71 SSL_CTX_set0_CA_list,
72 SSL_get0_CA_list,
73 SSL_CTX_get0_CA_list,
74 SSL_add1_to_CA_list,
75 SSL_CTX_add1_to_CA_list,
76 SSL_get0_peer_CA_list
77 \&\- get or set CA list
78 .SH SYNOPSIS
79 .IX Header "SYNOPSIS"
80 .Vb 1
81 \& #include <openssl/ssl.h>
82 \&
83 \& void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
84 \& void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
85 \& STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
86 \& STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
87 \& int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
88 \& int SSL_add_client_CA(SSL *ssl, X509 *cacert);
89 \&
90 \& void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
91 \& void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
92 \& const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
93 \& const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
94 \& int SSL_CTX_add1_to_CA_list(SSL_CTX *ctx, const X509 *x);
95 \& int SSL_add1_to_CA_list(SSL *ssl, const X509 *x);
96 \&
97 \& const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);
98 .Ve
99 .SH DESCRIPTION
100 .IX Header "DESCRIPTION"
101 The functions described here set and manage the list of CA names that are sent
102 between two communicating peers.
103 .PP
104 For TLS versions 1.2 and earlier the list of CA names is only sent from the
105 server to the client when requesting a client certificate. So any list of CA
106 names set is never sent from client to server and the list of CA names retrieved
107 by \fBSSL_get0_peer_CA_list()\fR is always \fBNULL\fR.
108 .PP
109 For TLS 1.3 the list of CA names is sent using the \fBcertificate_authorities\fR
110 extension and may be sent by a client (in the ClientHello message) or by
111 a server (when requesting a certificate).
112 .PP
113 In most cases it is not necessary to set CA names on the client side. The list
114 of CA names that are acceptable to the client will be sent in plaintext to the
115 server. This has privacy implications and may also have performance implications
116 if the list is large. This optional capability was introduced as part of TLSv1.3
117 and therefore setting CA names on the client side will have no impact if that
118 protocol version has been disabled. Most servers do not need this and so this
119 should be avoided unless required.
120 .PP
121 The "client CA list" functions below only have an effect when called on the
122 server side.
123 .PP
124 \&\fBSSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
125 requesting a client certificate for \fBctx\fR. Ownership of \fBlist\fR is transferred
126 to \fBctx\fR and it should not be freed by the caller.
127 .PP
128 \&\fBSSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
129 requesting a client certificate for the chosen \fBssl\fR, overriding the
130 setting valid for \fBssl\fR's SSL_CTX object. Ownership of \fBlist\fR is transferred
131 to \fBs\fR and it should not be freed by the caller.
132 .PP
133 \&\fBSSL_CTX_get_client_CA_list()\fR returns the list of client CAs explicitly set for
134 \&\fBctx\fR using \fBSSL_CTX_set_client_CA_list()\fR. The returned list should not be freed
135 by the caller.
136 .PP
137 \&\fBSSL_get_client_CA_list()\fR returns the list of client CAs explicitly
138 set for \fBssl\fR using \fBSSL_set_client_CA_list()\fR or \fBssl\fR's SSL_CTX object with
139 \&\fBSSL_CTX_set_client_CA_list()\fR, when in server mode. In client mode,
140 SSL_get_client_CA_list returns the list of client CAs sent from the server, if
141 any. The returned list should not be freed by the caller.
142 .PP
143 \&\fBSSL_CTX_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the
144 list of CAs sent to the client when requesting a client certificate for
145 \&\fBctx\fR.
146 .PP
147 \&\fBSSL_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the
148 list of CAs sent to the client when requesting a client certificate for
149 the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR's SSL_CTX object.
150 .PP
151 \&\fBSSL_get0_peer_CA_list()\fR retrieves the list of CA names (if any) the peer
152 has sent. This can be called on either the server or the client side. The
153 returned list should not be freed by the caller.
154 .PP
155 The "generic CA list" functions below are very similar to the "client CA
156 list" functions except that they have an effect on both the server and client
157 sides. The lists of CA names managed are separate \- so you cannot (for example)
158 set CA names using the "client CA list" functions and then get them using the
159 "generic CA list" functions. Where a mix of the two types of functions has been
160 used on the server side then the "client CA list" functions take precedence.
161 Typically, on the server side, the "client CA list " functions should be used in
162 preference. As noted above in most cases it is not necessary to set CA names on
163 the client side.
164 .PP
165 \&\fBSSL_CTX_set0_CA_list()\fR sets the list of CAs to be sent to the peer to
166 \&\fBname_list\fR. Ownership of \fBname_list\fR is transferred to \fBctx\fR and
167 it should not be freed by the caller.
168 .PP
169 \&\fBSSL_set0_CA_list()\fR sets the list of CAs to be sent to the peer to \fBname_list\fR
170 overriding any list set in the parent \fBSSL_CTX\fR of \fBs\fR. Ownership of
171 \&\fBname_list\fR is transferred to \fBs\fR and it should not be freed by the caller.
172 .PP
173 \&\fBSSL_CTX_get0_CA_list()\fR retrieves any previously set list of CAs set for
174 \&\fBctx\fR. The returned list should not be freed by the caller.
175 .PP
176 \&\fBSSL_get0_CA_list()\fR retrieves any previously set list of CAs set for
177 \&\fBs\fR or if none are set the list from the parent \fBSSL_CTX\fR is retrieved. The
178 returned list should not be freed by the caller.
179 .PP
180 \&\fBSSL_CTX_add1_to_CA_list()\fR appends the CA subject name extracted from \fBx\fR to the
181 list of CAs sent to peer for \fBctx\fR.
182 .PP
183 \&\fBSSL_add1_to_CA_list()\fR appends the CA subject name extracted from \fBx\fR to the
184 list of CAs sent to the peer for \fBs\fR, overriding the setting in the parent
185 \&\fBSSL_CTX\fR.
186 .SH NOTES
187 .IX Header "NOTES"
188 When a TLS/SSL server requests a client certificate (see
189 \&\fBSSL_CTX_set_verify\|(3)\fR), it sends a list of CAs, for which it will accept
190 certificates, to the client.
191 .PP
192 This list must explicitly be set using \fBSSL_CTX_set_client_CA_list()\fR or
193 \&\fBSSL_CTX_set0_CA_list()\fR for \fBctx\fR and \fBSSL_set_client_CA_list()\fR or
194 \&\fBSSL_set0_CA_list()\fR for the specific \fBssl\fR. The list specified
195 overrides the previous setting. The CAs listed do not become trusted (\fBlist\fR
196 only contains the names, not the complete certificates); use
197 \&\fBSSL_CTX_load_verify_locations\fR\|(3) to additionally load them for verification.
198 .PP
199 If the list of acceptable CAs is compiled in a file, the
200 \&\fBSSL_load_client_CA_file\fR\|(3) function can be used to help to import the
201 necessary data.
202 .PP
203 \&\fBSSL_CTX_add_client_CA()\fR, \fBSSL_CTX_add1_to_CA_list()\fR, \fBSSL_add_client_CA()\fR and
204 \&\fBSSL_add1_to_CA_list()\fR can be used to add additional items the list of CAs. If no
205 list was specified before using \fBSSL_CTX_set_client_CA_list()\fR,
206 \&\fBSSL_CTX_set0_CA_list()\fR, \fBSSL_set_client_CA_list()\fR or \fBSSL_set0_CA_list()\fR, a
207 new CA list for \fBctx\fR or \fBssl\fR (as appropriate) is opened.
208 .SH "RETURN VALUES"
209 .IX Header "RETURN VALUES"
210 \&\fBSSL_CTX_set_client_CA_list()\fR, \fBSSL_set_client_CA_list()\fR,
211 \&\fBSSL_CTX_set_client_CA_list()\fR, \fBSSL_set_client_CA_list()\fR, \fBSSL_CTX_set0_CA_list()\fR
212 and \fBSSL_set0_CA_list()\fR do not return a value.
213 .PP
214 \&\fBSSL_CTX_get_client_CA_list()\fR, \fBSSL_get_client_CA_list()\fR, \fBSSL_CTX_get0_CA_list()\fR
215 and \fBSSL_get0_CA_list()\fR return a stack of CA names or \fBNULL\fR is no CA names are
216 set.
217 .PP
218 \&\fBSSL_CTX_add_client_CA()\fR,\fBSSL_add_client_CA()\fR, \fBSSL_CTX_add1_to_CA_list()\fR and
219 \&\fBSSL_add1_to_CA_list()\fR return 1 for success and 0 for failure.
220 .PP
221 \&\fBSSL_get0_peer_CA_list()\fR returns a stack of CA names sent by the peer or
222 \&\fBNULL\fR or an empty stack if no list was sent.
223 .SH EXAMPLES
224 .IX Header "EXAMPLES"
225 Scan all certificates in \fBCAfile\fR and list them as acceptable CAs:
226 .PP
227 .Vb 1
228 \& SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
229 .Ve
230 .SH "SEE ALSO"
231 .IX Header "SEE ALSO"
232 \&\fBssl\fR\|(7),
233 \&\fBSSL_load_client_CA_file\fR\|(3),
234 \&\fBSSL_CTX_load_verify_locations\fR\|(3)
235 .SH COPYRIGHT
236 .IX Header "COPYRIGHT"
237 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
238 .PP
239 Licensed under the Apache License 2.0 (the "License"). You may not use
240 this file except in compliance with the License. You can obtain a copy
241 in the file LICENSE in the source distribution or at
242 <https://www.openssl.org/source/license.html>.