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