doc/man3/SSL_CTX_load_verify_locations.pod

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