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