lib/libssl/man/SSL_CTX_set_client_CA_list.3

   1 .\"     $OpenBSD: SSL_CTX_set_client_CA_list.3,v 1.5 2018/03/27 17:35:50 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2000, 2001, 2013 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: March 27 2018 $
  52 .Dt SSL_CTX_SET_CLIENT_CA_LIST 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_CTX_set_client_CA_list ,
  56 .Nm SSL_set_client_CA_list ,
  57 .Nm SSL_CTX_add_client_CA ,
  58 .Nm  SSL_add_client_CA
  59 .Nd set list of CAs sent to the client when requesting a client certificate
  60 .Sh SYNOPSIS
  61 .In openssl/ssl.h
  62 .Ft void
  63 .Fn SSL_CTX_set_client_CA_list "SSL_CTX *ctx" "STACK_OF(X509_NAME) *list"
  64 .Ft void
  65 .Fn SSL_set_client_CA_list "SSL *s" "STACK_OF(X509_NAME) *list"
  66 .Ft int
  67 .Fn SSL_CTX_add_client_CA "SSL_CTX *ctx" "X509 *cacert"
  68 .Ft int
  69 .Fn SSL_add_client_CA "SSL *ssl" "X509 *cacert"
  70 .Sh DESCRIPTION
  71 .Fn SSL_CTX_set_client_CA_list
  72 sets the
  73 .Fa list
  74 of CAs sent to the client when requesting a client certificate for
  75 .Fa ctx .
  76 .Pp
  77 .Fn SSL_set_client_CA_list
  78 sets the
  79 .Fa list
  80 of CAs sent to the client when requesting a client certificate for the chosen
  81 .Fa ssl ,
  82 overriding the setting valid for
  83 .Fa ssl Ns 's
  84 .Vt SSL_CTX
  85 object.
  86 .Pp
  87 .Fn SSL_CTX_add_client_CA
  88 adds the CA name extracted from
  89 .Fa cacert
  90 to the list of CAs sent to the client when requesting a client certificate for
  91 .Fa ctx .
  92 .Pp
  93 .Fn SSL_add_client_CA
  94 adds the CA name extracted from
  95 .Fa cacert
  96 to the list of CAs sent to the client when requesting a client certificate for
  97 the chosen
  98 .Fa ssl ,
  99 overriding the setting valid for
 100 .Fa ssl Ns 's
 101 .Va SSL_CTX
 102 object.
 103 .Pp
 104 When a TLS/SSL server requests a client certificate (see
 105 .Fn SSL_CTX_set_verify ) ,
 106 it sends a list of CAs for which it will accept certificates to the client.
 107 .Pp
 108 This list must explicitly be set using
 109 .Fn SSL_CTX_set_client_CA_list
 110 for
 111 .Fa ctx
 112 and
 113 .Fn SSL_set_client_CA_list
 114 for the specific
 115 .Fa ssl .
 116 The list specified overrides the previous setting.
 117 The CAs listed do not become trusted
 118 .Po
 119 .Fa list
 120 only contains the names, not the complete certificates
 121 .Pc ;
 122 use
 123 .Xr SSL_CTX_load_verify_locations 3
 124 to additionally load them for verification.
 125 .Pp
 126 If the list of acceptable CAs is compiled in a file, the
 127 .Xr SSL_load_client_CA_file 3
 128 function can be used to help importing the necessary data.
 129 .Pp
 130 .Fn SSL_CTX_add_client_CA
 131 and
 132 .Fn SSL_add_client_CA
 133 can be used to add additional items the list of client CAs.
 134 If no list was specified before using
 135 .Fn SSL_CTX_set_client_CA_list
 136 or
 137 .Fn SSL_set_client_CA_list ,
 138 a new client CA list for
 139 .Fa ctx
 140 or
 141 .Fa ssl
 142 (as appropriate) is opened.
 143 .Pp
 144 These functions are only useful for TLS/SSL servers.
 145 .Sh RETURN VALUES
 146 .Fn SSL_CTX_set_client_CA_list
 147 and
 148 .Fn SSL_set_client_CA_list
 149 do not return diagnostic information.
 150 .Pp
 151 .Fn SSL_CTX_add_client_CA
 152 and
 153 .Fn SSL_add_client_CA
 154 have the following return values:
 155 .Bl -tag -width Ds
 156 .It 0
 157 A failure while manipulating the
 158 .Dv STACK_OF Ns
 159 .Pq Vt X509_NAME
 160 object occurred or the
 161 .Vt X509_NAME
 162 could not be extracted from
 163 .Fa cacert .
 164 Check the error stack to find out the reason.
 165 .It 1
 166 The operation succeeded.
 167 .El
 168 .Sh EXAMPLES
 169 Scan all certificates in
 170 .Fa CAfile
 171 and list them as acceptable CAs:
 172 .Bd -literal
 173 SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
 174 .Ed
 175 .Sh SEE ALSO
 176 .Xr ssl 3 ,
 177 .Xr SSL_CTX_load_verify_locations 3 ,
 178 .Xr SSL_get_client_CA_list 3 ,
 179 .Xr SSL_load_client_CA_file 3 ,
 180 .Xr X509_NAME_new 3
 181 .Sh HISTORY
 182 .Fn SSL_CTX_set_client_CA_list ,
 183 .Fn SSL_set_client_CA_list ,
 184 .Fn SSL_CTX_add_client_CA ,
 185 and
 186 .Fn SSL_add_client_CA
 187 first appeared in SSLeay 0.8.0 and have been available since
 188 .Ox 2.4 .