1.\"	$OpenBSD: SSL_CTX_set_client_CA_list.3,v 1.6 2020/03/30 10:28:59 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 30 2020 $
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
72sets the
73.Fa list
74of CAs sent to the client when requesting a client certificate for
75.Fa ctx .
76.Pp
77.Fn SSL_set_client_CA_list
78sets the
79.Fa list
80of CAs sent to the client when requesting a client certificate for the chosen
81.Fa ssl ,
82overriding the setting valid for
83.Fa ssl Ns 's
84.Vt SSL_CTX
85object.
86.Pp
87.Fn SSL_CTX_add_client_CA
88adds the CA name extracted from
89.Fa cacert
90to 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
94adds the CA name extracted from
95.Fa cacert
96to the list of CAs sent to the client when requesting a client certificate for
97the chosen
98.Fa ssl ,
99overriding the setting valid for
100.Fa ssl Ns 's
101.Va SSL_CTX
102object.
103.Pp
104When a TLS/SSL server requests a client certificate (see
105.Fn SSL_CTX_set_verify ) ,
106it sends a list of CAs for which it will accept certificates to the client.
107.Pp
108This list must explicitly be set using
109.Fn SSL_CTX_set_client_CA_list
110for
111.Fa ctx
112and
113.Fn SSL_set_client_CA_list
114for the specific
115.Fa ssl .
116The list specified overrides the previous setting.
117The CAs listed do not become trusted
118.Po
119.Fa list
120only contains the names, not the complete certificates
121.Pc ;
122use
123.Xr SSL_CTX_load_verify_locations 3
124to additionally load them for verification.
125.Pp
126If the list of acceptable CAs is compiled in a file, the
127.Xr SSL_load_client_CA_file 3
128function can be used to help importing the necessary data.
129.Pp
130.Fn SSL_CTX_add_client_CA
131and
132.Fn SSL_add_client_CA
133can be used to add additional items the list of client CAs.
134If no list was specified before using
135.Fn SSL_CTX_set_client_CA_list
136or
137.Fn SSL_set_client_CA_list ,
138a new client CA list for
139.Fa ctx
140or
141.Fa ssl
142(as appropriate) is opened.
143.Pp
144These functions are only useful for TLS/SSL servers.
145.Sh RETURN VALUES
146.Fn SSL_CTX_add_client_CA
147and
148.Fn SSL_add_client_CA
149have the following return values:
150.Bl -tag -width Ds
151.It 0
152A failure while manipulating the
153.Dv STACK_OF Ns
154.Pq Vt X509_NAME
155object occurred or the
156.Vt X509_NAME
157could not be extracted from
158.Fa cacert .
159Check the error stack to find out the reason.
160.It 1
161The operation succeeded.
162.El
163.Sh EXAMPLES
164Scan all certificates in
165.Fa CAfile
166and list them as acceptable CAs:
167.Bd -literal
168SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
169.Ed
170.Sh SEE ALSO
171.Xr ssl 3 ,
172.Xr SSL_CTX_load_verify_locations 3 ,
173.Xr SSL_get_client_CA_list 3 ,
174.Xr SSL_load_client_CA_file 3 ,
175.Xr X509_NAME_new 3
176.Sh HISTORY
177.Fn SSL_CTX_set_client_CA_list ,
178.Fn SSL_set_client_CA_list ,
179.Fn SSL_CTX_add_client_CA ,
180and
181.Fn SSL_add_client_CA
182first appeared in SSLeay 0.8.0 and have been available since
183.Ox 2.4 .
184