secure/lib/libcrypto/man/man3/SSL_CTX_set0_CA_list.3

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