update libressl to v2.7.4
[unleashed.git] / lib / libssl / man / SSL_CTX_load_verify_locations.3
blobab0374ecfcf831c9f73256c3675d57907d5b4d0e
1 .\"     $OpenBSD: SSL_CTX_load_verify_locations.3,v 1.3 2018/03/21 05:07:04 schwarze Exp $
2 .\"     OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400
3 .\"
4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
5 .\" Copyright (c) 2000, 2001, 2015, 2016 The OpenSSL Project.
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\"    notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\"    notice, this list of conditions and the following disclaimer in
17 .\"    the documentation and/or other materials provided with the
18 .\"    distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\"    software must display the following acknowledgment:
22 .\"    "This product includes software developed by the OpenSSL Project
23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\"    endorse or promote products derived from this software without
27 .\"    prior written permission. For written permission, please contact
28 .\"    openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\"    nor may "OpenSSL" appear in their names without prior written
32 .\"    permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\"    acknowledgment:
36 .\"    "This product includes software developed by the OpenSSL Project
37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: March 21 2018 $
53 .Dt SSL_CTX_LOAD_VERIFY_LOCATIONS 3
54 .Os
55 .Sh NAME
56 .Nm SSL_CTX_load_verify_locations ,
57 .Nm SSL_CTX_set_default_verify_paths
58 .Nd set default locations for trusted CA certificates
59 .Sh SYNOPSIS
60 .In openssl/ssl.h
61 .Ft int
62 .Fo SSL_CTX_load_verify_locations
63 .Fa "SSL_CTX *ctx" "const char *CAfile" "const char *CApath"
64 .Fc
65 .Ft int
66 .Fo SSL_CTX_set_default_verify_paths
67 .Fa "SSL_CTX *ctx"
68 .Fc
69 .Sh DESCRIPTION
70 .Fn SSL_CTX_load_verify_locations
71 specifies the locations for
72 .Fa ctx ,
73 at which CA certificates for verification purposes are located.
74 The certificates available via
75 .Fa CAfile
76 and
77 .Fa CApath
78 are trusted.
79 .Pp
80 .Fn SSL_CTX_set_default_verify_paths
81 specifies that the default locations from which CA certificates are
82 loaded should be used.
83 There is one default directory and one default file.
84 The default CA certificates directory is called
85 .Pa certs
86 in the default OpenSSL directory.
87 The default CA certificates file is called
88 .Pa cert.pem
89 in the default OpenSSL directory.
90 .Pp
92 .Fa CAfile
93 is not
94 .Dv NULL ,
95 it points to a file of CA certificates in PEM format.
96 The file can contain several CA certificates identified by sequences of:
97 .Bd -literal
98  -----BEGIN CERTIFICATE-----
99  ... (CA certificate in base64 encoding) ...
100  -----END CERTIFICATE-----
103 Before, between, and after the certificates arbitrary text is allowed which can
104 be used, e.g., for descriptions of the certificates.
107 .Fa CAfile
108 is processed on execution of the
109 .Fn SSL_CTX_load_verify_locations
110 function.
113 .Fa CApath
114 is not NULL, it points to a directory containing CA certificates in PEM format.
115 The files each contain one CA certificate.
116 The files are looked up by the CA subject name hash value,
117 which must hence be available.
118 If more than one CA certificate with the same name hash value exist,
119 the extension must be different (e.g.,
120 .Pa 9d66eef0.0 ,
121 .Pa 9d66eef0.1 ,
122 etc.).
123 The search is performed in the ordering of the extension number,
124 regardless of other properties of the certificates.
126 The certificates in
127 .Fa CApath
128 are only looked up when required, e.g., when building the certificate chain or
129 when actually performing the verification of a peer certificate.
131 When looking up CA certificates, the OpenSSL library will first search the
132 certificates in
133 .Fa CAfile ,
134 then those in
135 .Fa CApath .
136 Certificate matching is done based on the subject name, the key identifier (if
137 present), and the serial number as taken from the certificate to be verified.
138 If these data do not match, the next certificate will be tried.
139 If a first certificate matching the parameters is found,
140 the verification process will be performed;
141 no other certificates for the same parameters will be searched in case of
142 failure.
144 In server mode, when requesting a client certificate, the server must send
145 the list of CAs of which it will accept client certificates.
146 This list is not influenced by the contents of
147 .Fa CAfile
149 .Fa CApath
150 and must explicitly be set using the
151 .Xr SSL_CTX_set_client_CA_list 3
152 family of functions.
154 When building its own certificate chain, an OpenSSL client/server will try to
155 fill in missing certificates from
156 .Fa CAfile Ns / Fa CApath ,
157 if the
158 certificate chain was not explicitly specified (see
159 .Xr SSL_CTX_add_extra_chain_cert 3
161 .Xr SSL_CTX_use_certificate 3 ) .
162 .Sh RETURN VALUES
164 .Fn SSL_CTX_load_verify_locations ,
165 the following return values can occur:
166 .Bl -tag -width Ds
167 .It 0
168 The operation failed because
169 .Fa CAfile
171 .Fa CApath
173 .Dv NULL
174 or the processing at one of the locations specified failed.
175 Check the error stack to find out the reason.
176 .It 1
177 The operation succeeded.
180 .Fn SSL_CTX_set_default_verify_paths
181 returns 1 on success or 0 on failure.
182 A missing default location is still treated as a success.
183 .Sh EXAMPLES
184 Generate a CA certificate file with descriptive text from the CA certificates
185 .Pa ca1.pem
186 .Pa ca2.pem
187 .Pa ca3.pem :
188 .Bd -literal
189 #!/bin/sh
190 rm CAfile.pem
191 for i in ca1.pem ca2.pem ca3.pem; do
192         openssl x509 -in $i -text >> CAfile.pem
193 done
196 Prepare the directory /some/where/certs containing several CA certificates
197 for use as
198 .Fa CApath :
199 .Bd -literal
200 $ cd /some/where/certs
201 $ rm -f *.[0-9]* *.r[0-9]*
202 $ for c in *.pem; do
203 >    [ "$c" = "*.pem" ] && continue
204 >    hash=$(openssl x509 -noout -hash -in "$c")
205 >    if egrep -q -- '-BEGIN( X509 | TRUSTED | )CERTIFICATE-' "$c"; then
206 >      suf=0
207 >      while [ -e $hash.$suf ]; do suf=$(( $suf + 1 )); done
208 >      ln -s "$c" $hash.$suf
209 >    fi
210 >    if egrep -q -- '-BEGIN X509 CRL-' "$c"; then
211 >      suf=0
212 >      while [ -e $hash.r$suf ]; do suf=$(( $suf + 1 )); done
213 >      ln -s "$c" $hash.r$suf
214 >    fi
215 > done
217 .Sh SEE ALSO
218 .Xr ssl 3 ,
219 .Xr SSL_CTX_add_extra_chain_cert 3 ,
220 .Xr SSL_CTX_set_cert_store 3 ,
221 .Xr SSL_CTX_set_client_CA_list 3 ,
222 .Xr SSL_CTX_use_certificate 3 ,
223 .Xr SSL_get_client_CA_list 3
224 .Sh HISTORY
225 .Fn SSL_CTX_load_verify_locations
227 .Fn SSL_CTX_set_default_verify_paths
228 appeared before SSLeay 0.8 and have been available since
229 .Ox 2.4 .
230 .Sh CAVEATS
231 If several CA certificates matching the name, key identifier, and serial
232 number condition are available, only the first one will be examined.
233 This may lead to unexpected results if the same CA certificate is available
234 with different expiration dates.
235 If a
236 .Dq certificate expired
237 verification error occurs, no other certificate will be searched.
238 Make sure to not have expired certificates mixed with valid ones.