doc/man3/SSL_CTX_set0_CA_list.pod

   1 =pod
   2
   3 =head1 NAME
   4
   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
  19
  20 =head1 SYNOPSIS
  21
  22  #include <openssl/ssl.h>
  23
  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
  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);
  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);
  37
  38  const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s);
  39
  40 =head1 DESCRIPTION
  41
  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
 104 the client side.
 105
 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
 115 B<ctx>. The returned list should not be freed by the caller.
 116
 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.
 120
 121 SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
 122 list of CAs sent to peer for B<ctx>.
 123
 124 SSL_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
 125 list of CAs sent to the peer for B<s>, overriding the setting in the parent
 126 B<SSL_CTX>.
 127
 128 =head1 NOTES
 129
 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.
 133
 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.
 140
 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.
 150
 151 =head1 RETURN VALUES
 152
 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.
 156
 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.
 160
 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.
 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
 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
 173 =head1 SEE ALSO
 174
 175 L<ssl(7)>,
 176 L<SSL_load_client_CA_file(3)>,
 177 L<SSL_CTX_load_verify_locations(3)>
 178
 179 =head1 COPYRIGHT
 180
 181 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
 182
 183 Licensed under the Apache License 2.0 (the "License").  You may not use
 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