1=pod
2
3=head1 NAME
4
5SSL_CTX_load_verify_dir, SSL_CTX_load_verify_file,
6SSL_CTX_load_verify_store, SSL_CTX_set_default_verify_paths,
7SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file,
8SSL_CTX_set_default_verify_store, SSL_CTX_load_verify_locations
9- set default locations for trusted CA certificates
10
11=head1 SYNOPSIS
12
13 #include <openssl/ssl.h>
14
15 int SSL_CTX_load_verify_dir(SSL_CTX *ctx, const char *CApath);
16 int SSL_CTX_load_verify_file(SSL_CTX *ctx, const char *CAfile);
17 int SSL_CTX_load_verify_store(SSL_CTX *ctx, const char *CAstore);
18
19 int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
20
21 int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx);
22 int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
23 int SSL_CTX_set_default_verify_store(SSL_CTX *ctx);
24
25 int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
26                                   const char *CApath);
27
28=head1 DESCRIPTION
29
30SSL_CTX_load_verify_locations(), SSL_CTX_load_verify_dir(),
31SSL_CTX_load_verify_file(), SSL_CTX_load_verify_store() specifies the
32locations for B<ctx>, at which CA certificates for verification purposes
33are located. The certificates available via B<CAfile>, B<CApath> and
34B<CAstore> are trusted.
35
36Details of the certificate verification and chain checking process are
37described in L<openssl-verification-options(1)/Certification Path Validation>.
38
39SSL_CTX_set_default_verify_paths() specifies that the default locations from
40which CA certificates are loaded should be used. There is one default directory,
41one default file and one default store.
42The default CA certificates directory is called F<certs> in the default OpenSSL
43directory, and this is also the default store.
44Alternatively the B<SSL_CERT_DIR> environment variable can be defined to
45override this location.
46The default CA certificates file is called F<cert.pem> in the default
47OpenSSL directory.
48Alternatively the B<SSL_CERT_FILE> environment variable can be defined to
49override this location.
50
51SSL_CTX_set_default_verify_dir() is similar to
52SSL_CTX_set_default_verify_paths() except that just the default directory is
53used.
54
55SSL_CTX_set_default_verify_file() is similar to
56SSL_CTX_set_default_verify_paths() except that just the default file is
57used.
58
59SSL_CTX_set_default_verify_store() is similar to
60SSL_CTX_set_default_verify_paths() except that just the default store is
61used.
62
63=head1 NOTES
64
65If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
66format. The file can contain several CA certificates identified by
67
68 -----BEGIN CERTIFICATE-----
69 ... (CA certificate in base64 encoding) ...
70 -----END CERTIFICATE-----
71
72sequences. Before, between, and after the certificates text is allowed
73which can be used e.g. for descriptions of the certificates.
74
75The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
76function.
77
78If B<CApath> is not NULL, it points to a directory containing CA certificates
79in PEM format. The files each contain one CA certificate. The files are
80looked up by the CA subject name hash value, which must hence be available.
81If more than one CA certificate with the same name hash value exist, the
82extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
83is performed in the ordering of the extension number, regardless of other
84properties of the certificates.
85Use the B<c_rehash> utility to create the necessary links.
86
87The certificates in B<CApath> are only looked up when required, e.g. when
88building the certificate chain or when actually performing the verification
89of a peer certificate.
90
91When looking up CA certificates for chain building, the OpenSSL library
92will search for suitable certificates first in B<CAfile>, then in B<CApath>.
93Details of the chain building process are described in
94L<openssl-verification-options(1)/Certification Path Building>.
95
96If B<CAstore> is not NULL, it's a URI for to a store, which may
97represent a single container or a whole catalogue of containers.
98Apart from the B<CAstore> not necessarily being a local file or
99directory, it's generally treated the same way as a B<CApath>.
100
101In server mode, when requesting a client certificate, the server must send
102the list of CAs of which it will accept client certificates. This list
103is not influenced by the contents of B<CAfile> or B<CApath> and must
104explicitly be set using the
105L<SSL_CTX_set_client_CA_list(3)>
106family of functions.
107
108When building its own certificate chain, an OpenSSL client/server will
109try to fill in missing certificates from B<CAfile>/B<CApath>, if the
110certificate chain was not explicitly specified (see
111L<SSL_CTX_add_extra_chain_cert(3)>,
112L<SSL_CTX_use_certificate(3)>.
113
114=head1 WARNINGS
115
116If several CA certificates matching the name, key identifier, and serial
117number condition are available, only the first one will be examined. This
118may lead to unexpected results if the same CA certificate is available
119with different expiration dates. If a "certificate expired" verification
120error occurs, no other certificate will be searched. Make sure to not
121have expired certificates mixed with valid ones.
122
123=head1 RETURN VALUES
124
125For SSL_CTX_load_verify_locations the following return values can occur:
126
127=over 4
128
129=item Z<>0
130
131The operation failed because B<CAfile> and B<CApath> are NULL or the
132processing at one of the locations specified failed. Check the error
133stack to find out the reason.
134
135=item Z<>1
136
137The operation succeeded.
138
139=back
140
141SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
142SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
143missing default location is still treated as a success.
144
145=head1 EXAMPLES
146
147Generate a CA certificate file with descriptive text from the CA certificates
148ca1.pem ca2.pem ca3.pem:
149
150 #!/bin/sh
151 rm CAfile.pem
152 for i in ca1.pem ca2.pem ca3.pem ; do
153     openssl x509 -in $i -text >> CAfile.pem
154 done
155
156Prepare the directory /some/where/certs containing several CA certificates
157for use as B<CApath>:
158
159 cd /some/where/certs
160 c_rehash .
161
162=head1 SEE ALSO
163
164L<ssl(7)>,
165L<SSL_CTX_set_client_CA_list(3)>,
166L<SSL_get_client_CA_list(3)>,
167L<SSL_CTX_use_certificate(3)>,
168L<SSL_CTX_add_extra_chain_cert(3)>,
169L<SSL_CTX_set_cert_store(3)>,
170L<SSL_CTX_set_client_CA_list(3)>
171
172=head1 COPYRIGHT
173
174Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
175
176Licensed under the Apache License 2.0 (the "License").  You may not use
177this file except in compliance with the License.  You can obtain a copy
178in the file LICENSE in the source distribution or at
179L<https://www.openssl.org/source/license.html>.
180
181=cut
182