aboutsummaryrefslogtreecommitdiffstats
path: root/secure/lib/libcrypto/man/man3/SSL_CTX_set0_CA_list.3
blob: f123d0a00359a62f729229362b2ed611f6888af2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SSL_CTX_SET0_CA_LIST 3"
.TH SSL_CTX_SET0_CA_LIST 3 "2019-09-10" "1.1.1d" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The functions described here set and manage the list of \s-1CA\s0 names that are sent
between two communicating peers.
.PP
For \s-1TLS\s0 versions 1.2 and earlier the list of \s-1CA\s0 names is only sent from the
server to the client when requesting a client certificate. So any list of \s-1CA\s0
names set is never sent from client to server and the list of \s-1CA\s0 names retrieved
by \fBSSL_get0_peer_CA_list()\fR is always \fB\s-1NULL\s0\fR.
.PP
For \s-1TLS 1.3\s0 the list of \s-1CA\s0 names is sent using the \fBcertificate_authorities\fR
extension and may be sent by a client (in the ClientHello message) or by
a server (when requesting a certificate).
.PP
In most cases it is not necessary to set \s-1CA\s0 names on the client side. The list
of \s-1CA\s0 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 \s-1CA\s0 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.
.PP
The \*(L"client \s-1CA\s0 list\*(R" functions below only have an effect when called on the
server side.
.PP
\&\fBSSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
requesting a client certificate for \fBctx\fR. Ownership of \fBlist\fR is transferred
to \fBctx\fR and it should not be freed by the caller.
.PP
\&\fBSSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
requesting a client certificate for the chosen \fBssl\fR, overriding the
setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object. Ownership of \fBlist\fR is transferred
to \fBs\fR and it should not be freed by the caller.
.PP
\&\fBSSL_CTX_get_client_CA_list()\fR returns the list of client CAs explicitly set for
\&\fBctx\fR using \fBSSL_CTX_set_client_CA_list()\fR. The returned list should not be freed
by the caller.
.PP
\&\fBSSL_get_client_CA_list()\fR returns the list of client CAs explicitly
set for \fBssl\fR using \fBSSL_set_client_CA_list()\fR or \fBssl\fR's \s-1SSL_CTX\s0 object with
\&\fBSSL_CTX_set_client_CA_list()\fR, 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.
.PP
\&\fBSSL_CTX_add_client_CA()\fR adds the \s-1CA\s0 name extracted from \fBcacert\fR to the
list of CAs sent to the client when requesting a client certificate for
\&\fBctx\fR.
.PP
\&\fBSSL_add_client_CA()\fR adds the \s-1CA\s0 name extracted from \fBcacert\fR to the
list of CAs sent to the client when requesting a client certificate for
the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object.
.PP
\&\fBSSL_get0_peer_CA_list()\fR retrieves the list of \s-1CA\s0 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.
.PP
The \*(L"generic \s-1CA\s0 list\*(R" functions below are very similar to the \*(L"client \s-1CA\s0
list\*(R" functions except that they have an effect on both the server and client
sides. The lists of \s-1CA\s0 names managed are separate \- so you cannot (for example)
set \s-1CA\s0 names using the \*(L"client \s-1CA\s0 list\*(R" functions and then get them using the
\&\*(L"generic \s-1CA\s0 list\*(R" functions. Where a mix of the two types of functions has been
used on the server side then the \*(L"client \s-1CA\s0 list\*(R" functions take precedence.
Typically, on the server side, the \*(L"client \s-1CA\s0 list \*(R" functions should be used in
preference. As noted above in most cases it is not necessary to set \s-1CA\s0 names on
the client side.
.PP
\&\fBSSL_CTX_set0_CA_list()\fR sets the list of CAs to be sent to the peer to
\&\fBname_list\fR. Ownership of \fBname_list\fR is transferred to \fBctx\fR and
it should not be freed by the caller.
.PP
\&\fBSSL_set0_CA_list()\fR sets the list of CAs to be sent to the peer to \fBname_list\fR
overriding any list set in the parent \fB\s-1SSL_CTX\s0\fR of \fBs\fR. Ownership of
\&\fBname_list\fR is transferred to \fBs\fR and it should not be freed by the caller.
.PP
\&\fBSSL_CTX_get0_CA_list()\fR retrieves any previously set list of CAs set for
\&\fBctx\fR. The returned list should not be freed by the caller.
.PP
\&\fBSSL_get0_CA_list()\fR retrieves any previously set list of CAs set for
\&\fBs\fR or if none are set the list from the parent \fB\s-1SSL_CTX\s0\fR is retrieved. The
returned list should not be freed by the caller.
.PP
\&\fBSSL_CTX_add1_to_CA_list()\fR appends the \s-1CA\s0 subject name extracted from \fBx\fR to the
list of CAs sent to peer for \fBctx\fR.
.PP
\&\fBSSL_add1_to_CA_list()\fR appends the \s-1CA\s0 subject name extracted from \fBx\fR to the
list of CAs sent to the peer for \fBs\fR, overriding the setting in the parent
\&\fB\s-1SSL_CTX\s0\fR.
.SH "NOTES"
.IX Header "NOTES"
When a \s-1TLS/SSL\s0 server requests a client certificate (see
\&\fB\fBSSL_CTX_set_verify\fB\|(3)\fR), it sends a list of CAs, for which it will accept
certificates, to the client.
.PP
This list must explicitly be set using \fBSSL_CTX_set_client_CA_list()\fR or
\&\fBSSL_CTX_set0_CA_list()\fR for \fBctx\fR and \fBSSL_set_client_CA_list()\fR or
\&\fBSSL_set0_CA_list()\fR for the specific \fBssl\fR. The list specified
overrides the previous setting. The CAs listed do not become trusted (\fBlist\fR
only contains the names, not the complete certificates); use
\&\fBSSL_CTX_load_verify_locations\fR\|(3) to additionally load them for verification.
.PP
If the list of acceptable CAs is compiled in a file, the
\&\fBSSL_load_client_CA_file\fR\|(3) function can be used to help to import the
necessary data.
.PP
\&\fBSSL_CTX_add_client_CA()\fR, \fBSSL_CTX_add1_to_CA_list()\fR, \fBSSL_add_client_CA()\fR and
\&\fBSSL_add1_to_CA_list()\fR can be used to add additional items the list of CAs. If no
list was specified before using \fBSSL_CTX_set_client_CA_list()\fR,
\&\fBSSL_CTX_set0_CA_list()\fR, \fBSSL_set_client_CA_list()\fR or \fBSSL_set0_CA_list()\fR, a
new \s-1CA\s0 list for \fBctx\fR or \fBssl\fR (as appropriate) is opened.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_CTX_set_client_CA_list()\fR, \fBSSL_set_client_CA_list()\fR,
\&\fBSSL_CTX_set_client_CA_list()\fR, \fBSSL_set_client_CA_list()\fR, \fBSSL_CTX_set0_CA_list()\fR
and \fBSSL_set0_CA_list()\fR do not return a value.
.PP
\&\fBSSL_CTX_get_client_CA_list()\fR, \fBSSL_get_client_CA_list()\fR, \fBSSL_CTX_get0_CA_list()\fR
and \fBSSL_get0_CA_list()\fR return a stack of \s-1CA\s0 names or \fB\s-1NULL\s0\fR is no \s-1CA\s0 names are
set.
.PP
\&\fBSSL_CTX_add_client_CA()\fR,\fBSSL_add_client_CA()\fR, \fBSSL_CTX_add1_to_CA_list()\fR and
\&\fBSSL_add1_to_CA_list()\fR return 1 for success and 0 for failure.
.PP
\&\fBSSL_get0_peer_CA_list()\fR returns a stack of \s-1CA\s0 names sent by the peer or
\&\fB\s-1NULL\s0\fR or an empty stack if no list was sent.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Scan all certificates in \fBCAfile\fR and list them as acceptable CAs:
.PP
.Vb 1
\& SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBssl\fR\|(7),
\&\fBSSL_load_client_CA_file\fR\|(3),
\&\fBSSL_CTX_load_verify_locations\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.