secure/lib/libcrypto/man/SSL_CTX_set0_CA_list.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_SET0_CA_LIST 3"
 132 .TH SSL_CTX_SET0_CA_LIST 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
 145 \& void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
 146 \& STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
 147 \& STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
 148 \& int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
 149 \& int SSL_add_client_CA(SSL *ssl, X509 *cacert);
 150 \&
 151 \& void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
 152 \& void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
 153 \& const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
 154 \& const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s);
 155 \& int SSL_CTX_add1_to_CA_list(SSL_CTX *ctx, const X509 *x);
 156 \& int SSL_add1_to_CA_list(SSL *ssl, const X509 *x);
 157 \&
 158 \& const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);
 159 .Ve
 160 .SH "DESCRIPTION"
 161 .IX Header "DESCRIPTION"
 162 The functions described here set and manage the list of \s-1CA\s0 names that are sent
 163 between two communicating peers.
 164 .PP
 165 For \s-1TLS\s0 versions 1.2 and earlier the list of \s-1CA\s0 names is only sent from the
 166 server to the client when requesting a client certificate. So any list of \s-1CA\s0
 167 names set is never sent from client to server and the list of \s-1CA\s0 names retrieved
 168 by \fISSL_get0_peer_CA_list()\fR is always \fB\s-1NULL\s0\fR.
 169 .PP
 170 For \s-1TLS 1.3\s0 the list of \s-1CA\s0 names is sent using the \fBcertificate_authorities\fR
 171 extension and may be sent by a client (in the ClientHello message) or by
 172 a server (when requesting a certificate).
 173 .PP
 174 In most cases it is not necessary to set \s-1CA\s0 names on the client side. The list
 175 of \s-1CA\s0 names that are acceptable to the client will be sent in plaintext to the
 176 server. This has privacy implications and may also have performance implications
 177 if the list is large. This optional capability was introduced as part of TLSv1.3
 178 and therefore setting \s-1CA\s0 names on the client side will have no impact if that
 179 protocol version has been disabled. Most servers do not need this and so this
 180 should be avoided unless required.
 181 .PP
 182 The \*(L"client \s-1CA\s0 list\*(R" functions below only have an effect when called on the
 183 server side.
 184 .PP
 185 \&\fISSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
 186 requesting a client certificate for \fBctx\fR. Ownership of \fBlist\fR is transferred
 187 to \fBctx\fR and it should not be freed by the caller.
 188 .PP
 189 \&\fISSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when
 190 requesting a client certificate for the chosen \fBssl\fR, overriding the
 191 setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object. Ownership of \fBlist\fR is transferred
 192 to \fBs\fR and it should not be freed by the caller.
 193 .PP
 194 \&\fISSL_CTX_get_client_CA_list()\fR returns the list of client CAs explicitly set for
 195 \&\fBctx\fR using \fISSL_CTX_set_client_CA_list()\fR. The returned list should not be freed
 196 by the caller.
 197 .PP
 198 \&\fISSL_get_client_CA_list()\fR returns the list of client CAs explicitly
 199 set for \fBssl\fR using \fISSL_set_client_CA_list()\fR or \fBssl\fR's \s-1SSL_CTX\s0 object with
 200 \&\fISSL_CTX_set_client_CA_list()\fR, when in server mode. In client mode,
 201 SSL_get_client_CA_list returns the list of client CAs sent from the server, if
 202 any. The returned list should not be freed by the caller.
 203 .PP
 204 \&\fISSL_CTX_add_client_CA()\fR adds the \s-1CA\s0 name extracted from \fBcacert\fR to the
 205 list of CAs sent to the client when requesting a client certificate for
 206 \&\fBctx\fR.
 207 .PP
 208 \&\fISSL_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 the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object.
 211 .PP
 212 \&\fISSL_get0_peer_CA_list()\fR retrieves the list of \s-1CA\s0 names (if any) the peer
 213 has sent. This can be called on either the server or the client side. The
 214 returned list should not be freed by the caller.
 215 .PP
 216 The \*(L"generic \s-1CA\s0 list\*(R" functions below are very similar to the \*(L"client \s-1CA\s0
 217 list\*(R" functions except that they have an effect on both the server and client
 218 sides. The lists of \s-1CA\s0 names managed are separate \- so you cannot (for example)
 219 set \s-1CA\s0 names using the \*(L"client \s-1CA\s0 list\*(R" functions and then get them using the
 220 \&\*(L"generic \s-1CA\s0 list\*(R" functions. Where a mix of the two types of functions has been
 221 used on the server side then the \*(L"client \s-1CA\s0 list\*(R" functions take precedence.
 222 Typically, on the server side, the \*(L"client \s-1CA\s0 list \*(R" functions should be used in
 223 preference. As noted above in most cases it is not necessary to set \s-1CA\s0 names on
 224 the client side.
 225 .PP
 226 \&\fISSL_CTX_set0_CA_list()\fR sets the list of CAs to be sent to the peer to
 227 \&\fBname_list\fR. Ownership of \fBname_list\fR is transferred to \fBctx\fR and
 228 it should not be freed by the caller.
 229 .PP
 230 \&\fISSL_set0_CA_list()\fR sets the list of CAs to be sent to the peer to \fBname_list\fR
 231 overriding any list set in the parent \fB\s-1SSL_CTX\s0\fR of \fBs\fR. Ownership of
 232 \&\fBname_list\fR is transferred to \fBs\fR and it should not be freed by the caller.
 233 .PP
 234 \&\fISSL_CTX_get0_CA_list()\fR retrieves any previously set list of CAs set for
 235 \&\fBctx\fR. The returned list should not be freed by the caller.
 236 .PP
 237 \&\fISSL_get0_CA_list()\fR retrieves any previously set list of CAs set for
 238 \&\fBs\fR or if none are set the list from the parent \fB\s-1SSL_CTX\s0\fR is retrieved. The
 239 returned list should not be freed by the caller.
 240 .PP
 241 \&\fISSL_CTX_add1_to_CA_list()\fR appends the \s-1CA\s0 subject name extracted from \fBx\fR to the
 242 list of CAs sent to peer for \fBctx\fR.
 243 .PP
 244 \&\fISSL_add1_to_CA_list()\fR appends the \s-1CA\s0 subject name extracted from \fBx\fR to the
 245 list of CAs sent to the peer for \fBs\fR, overriding the setting in the parent
 246 \&\fB\s-1SSL_CTX\s0\fR.
 247 .SH "NOTES"
 248 .IX Header "NOTES"
 249 When a \s-1TLS/SSL\s0 server requests a client certificate (see
 250 \&\fB\f(BISSL_CTX_set_verify\fB\|(3)\fR), it sends a list of CAs, for which it will accept
 251 certificates, to the client.
 252 .PP
 253 This list must explicitly be set using \fISSL_CTX_set_client_CA_list()\fR or
 254 \&\fISSL_CTX_set0_CA_list()\fR for \fBctx\fR and \fISSL_set_client_CA_list()\fR or
 255 \&\fISSL_set0_CA_list()\fR for the specific \fBssl\fR. The list specified
 256 overrides the previous setting. The CAs listed do not become trusted (\fBlist\fR
 257 only contains the names, not the complete certificates); use
 258 \&\fISSL_CTX_load_verify_locations\fR\|(3) to additionally load them for verification.
 259 .PP
 260 If the list of acceptable CAs is compiled in a file, the
 261 \&\fISSL_load_client_CA_file\fR\|(3) function can be used to help to import the
 262 necessary data.
 263 .PP
 264 \&\fISSL_CTX_add_client_CA()\fR, \fISSL_CTX_add1_to_CA_list()\fR, \fISSL_add_client_CA()\fR and
 265 \&\fISSL_add1_to_CA_list()\fR can be used to add additional items the list of CAs. If no
 266 list was specified before using \fISSL_CTX_set_client_CA_list()\fR,
 267 \&\fISSL_CTX_set0_CA_list()\fR, \fISSL_set_client_CA_list()\fR or \fISSL_set0_CA_list()\fR, a
 268 new \s-1CA\s0 list for \fBctx\fR or \fBssl\fR (as appropriate) is opened.
 269 .SH "RETURN VALUES"
 270 .IX Header "RETURN VALUES"
 271 \&\fISSL_CTX_set_client_CA_list()\fR, \fISSL_set_client_CA_list()\fR,
 272 \&\fISSL_CTX_set_client_CA_list()\fR, \fISSL_set_client_CA_list()\fR, \fISSL_CTX_set0_CA_list()\fR
 273 and \fISSL_set0_CA_list()\fR do not return a value.
 274 .PP
 275 \&\fISSL_CTX_get_client_CA_list()\fR, \fISSL_get_client_CA_list()\fR, \fISSL_CTX_get0_CA_list()\fR
 276 and \fISSL_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
 277 set.
 278 .PP
 279 \&\fISSL_CTX_add_client_CA()\fR,\fISSL_add_client_CA()\fR, \fISSL_CTX_add1_to_CA_list()\fR and
 280 \&\fISSL_add1_to_CA_list()\fR return 1 for success and 0 for failure.
 281 .PP
 282 \&\fISSL_get0_peer_CA_list()\fR returns a stack of \s-1CA\s0 names sent by the peer or
 283 \&\fB\s-1NULL\s0\fR or an empty stack if no list was sent.
 284 .SH "EXAMPLES"
 285 .IX Header "EXAMPLES"
 286 Scan all certificates in \fBCAfile\fR and list them as acceptable CAs:
 287 .PP
 288 .Vb 1
 289 \& SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
 290 .Ve
 291 .SH "SEE ALSO"
 292 .IX Header "SEE ALSO"
 293 \&\fIssl\fR\|(7),
 294 \&\fISSL_load_client_CA_file\fR\|(3),
 295 \&\fISSL_CTX_load_verify_locations\fR\|(3)
 296 .SH "COPYRIGHT"
 297 .IX Header "COPYRIGHT"
 298 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 299 .PP
 300 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 301 this file except in compliance with the License.  You can obtain a copy
 302 in the file \s-1LICENSE\s0 in the source distribution or at
 303 <https://www.openssl.org/source/license.html>.