=head1 DESCRIPTION
-SSL_CTX_load_verify_locations(), SSL_CTX_load_verify_dir(),
-SSL_CTX_load_verify_file(), SSL_CTX_load_verify_store() specifies the
-locations for B<ctx>, at which CA certificates for verification purposes
-are located. The certificates available via B<CAfile>, B<CApath> and
-B<CAstore> are trusted. B<ctx> B<MUST NOT> be NULL
+SSL_CTX_load_verify_dir(), SSL_CTX_load_verify_file(),
+SSL_CTX_load_verify_store(), and SSL_CTX_load_verify_locations() specify
+the locations at which trusted CA certificates are located.
+For details, see the L</NOTES> below.
+The SSL context I<ctx> must not be NULL.
Details of the certificate verification and chain checking process are
described in L<openssl-verification-options(1)/Certification Path Validation>.
-SSL_CTX_set_default_verify_paths() specifies that the default locations from
-which CA certificates are loaded should be used. There is one default directory,
-one default file and one default store.
+SSL_CTX_set_default_verify_paths() specifies the default locations from
+which trusted CA certificates in PEM format are loaded when needed.
+For details, see the L</NOTES> below.
+
+There is one default directory, one default file, and one default store.
The default CA certificates directory is called F<certs> in the default OpenSSL
directory, and this is also the default store.
Alternatively the B<SSL_CERT_DIR> environment variable can be defined to
OpenSSL directory.
Alternatively the B<SSL_CERT_FILE> environment variable can be defined to
override this location.
-B<ctx> B<MUST NOT> be NULL.
+I<ctx> must not be NULL.
SSL_CTX_set_default_verify_dir() is similar to
SSL_CTX_set_default_verify_paths() except that just the default directory is
=head1 NOTES
-If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
+The CA certificates specified by calling the above functions are used
+as trust anchors for peer certificate verification purposes unless overridden
+by L<SSL_CTX_set0_verify_cert_store(3)>, L<SSL_CTX_set1_verify_cert_store(3)>,
+L<SSL_set0_verify_cert_store(3)>, or L<SSL_set1_verify_cert_store(3)>.
+They are also used as trust anchors for
+building the client or server's own certificate chain unless overridden
+by L<SSL_CTX_set0_chain_cert_store(3)>, L<SSL_CTX_set1_chain_cert_store(3)>,
+L<SSL_set0_chain_cert_store(3)>, or L<SSL_set1_chain_cert_store(3)>.
+
+The I<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
+and SSL_CTX_load_verify_file() functions.
+With SSL_CTX_load_verify_file() it must not be NULL.
+If I<CAfile> is not NULL, it points to a file of CA certificates in PEM
format. The file can contain several CA certificates identified by
-----BEGIN CERTIFICATE-----
... (CA certificate in base64 encoding) ...
-----END CERTIFICATE-----
-sequences. Before, between, and after the certificates text is allowed
-which can be used e.g. for descriptions of the certificates.
-
-The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
-function.
+sequences. Before, between, and after the certificates text is allowed,
+which can be used, e.g., for descriptions of the certificates.
-If B<CApath> is not NULL, it points to a directory containing CA certificates
-in PEM format. The files each contain one CA certificate. The files are
+The I<CApath> is not immediately processed on execution of the
+SSL_CTX_load_verify_locations() and SSL_CTX_load_verify_dir() functions.
+With SSL_CTX_load_verify_dir() it must not be NULL.
+If I<CApath> is not NULL, it points to a directory containing CA certificates
+in PEM format. The files each contain exactly one CA certificate. The files are
looked up by the CA subject name hash value, which must hence be available.
-If more than one CA certificate with the same name hash value exist, the
-extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
+If more than one CA certificate with the same subject name hash value exist, the
+extension must be different (e.g., C<9d66eef0.0>, C<9d66eef0.1>, etc). The search
is performed in the ordering of the extension number, regardless of other
properties of the certificates.
-Use the B<openssl rehash> utility to create the necessary links.
+Use the L<openssl-rehash(1)> utility to create the necessary links.
-The certificates in B<CApath> are only looked up when required, e.g. when
-building the certificate chain or when actually performing the verification
-of a peer certificate.
+The certificate files in I<CApath> are only looked up when required, e.g., when
+building the client or server's own certificate chain
+or when verifying a peer certificate.
When looking up CA certificates for chain building, the OpenSSL library
-will search for suitable certificates first in B<CAfile>, then in B<CApath>.
+will search for suitable certificates first in I<CAfile>, then in I<CApath>.
Details of the chain building process are described in
L<openssl-verification-options(1)/Certification Path Building>.
-If B<CAstore> is not NULL, it's a URI for to a store, which may
+I<CAstore> must not be NULL. It must be a URI to a store, which may
represent a single container or a whole catalogue of containers.
-Apart from the B<CAstore> not necessarily being a local file or
-directory, it's generally treated the same way as a B<CApath>.
+If I<CAstore> starts with the scheme C<file:>, it is treated like a local file
+or directory. See also ossl_store-file(7).
In server mode, when requesting a client certificate, the server must send
the list of CAs of which it will accept client certificates. This list
-is not influenced by the contents of B<CAfile> or B<CApath> and must
+is not influenced by the contents of I<CAfile> or I<CApath> and must
explicitly be set using the
L<SSL_CTX_set_client_CA_list(3)>
family of functions.
When building its own certificate chain, an OpenSSL client/server will
-try to fill in missing certificates from B<CAfile>/B<CApath>, if the
+try to fill in missing certificates from I<CAfile>/I<CApath>, if the
certificate chain was not explicitly specified (see
L<SSL_CTX_add_extra_chain_cert(3)>,
L<SSL_CTX_use_certificate(3)>.
=item Z<>0
-The operation failed because B<CAfile> and B<CApath> are NULL or the
+The operation failed because both I<CAfile> and I<CApath> are NULL or the
processing at one of the locations specified failed. Check the error
stack to find out the reason.
openssl x509 -in $i -text >> CAfile.pem
done
-Prepare the directory /some/where/certs containing several CA certificates
-for use as B<CApath>:
+Prepare the directory /path/to/certs containing several CA certificates
+for use as I<CApath>:
- cd /some/where/certs
- openssl rehash .
+ openssl rehash /path/to/certs
=head1 SEE ALSO
-L<ssl(7)>,
+L<openssl-rehash(1)>,
+L<SSL_CTX_set0_verify_cert_store(3)>,
+L<SSL_CTX_set1_verify_cert_store(3)>,
+L<SSL_CTX_set0_chain_cert_store(3)>,
+L<SSL_CTX_set1_chain_cert_store(3)>,
+L<SSL_set0_verify_cert_store(3)>,
+L<SSL_set1_verify_cert_store(3)>,
+L<SSL_set0_chain_cert_store(3)>,
+L<SSL_set1_chain_cert_store(3)>,
L<SSL_CTX_set_client_CA_list(3)>,
L<SSL_get_client_CA_list(3)>,
L<SSL_CTX_use_certificate(3)>,
L<SSL_CTX_add_extra_chain_cert(3)>,
L<SSL_CTX_set_cert_store(3)>,
-L<SSL_CTX_set_client_CA_list(3)>
+L<SSL_CTX_set_client_CA_list(3)>,
+L<ssl(7)>, ossl_store-file(7)
=head1 COPYRIGHT
I<store>. This also associates the B<X509_STORE> with the lookup, so
B<X509_LOOKUP> functions can look up objects in that store.
-X509_STORE_load_file_ex() loads trusted certificate(s) into an
-B<X509_STORE> from a given file. The library context I<libctx> and property
+X509_STORE_load_file_ex() loads trusted certificate(s) into an B<X509_STORE>
+from a given file in PEM format. The library context I<libctx> and property
query I<propq> are used when fetching algorithms from providers.
X509_STORE_load_file() is similar to X509_STORE_load_file_ex() but
uses NULL for the library context I<libctx> and property query I<propq>.
-X509_STORE_load_path() loads trusted certificate(s) into an
-B<X509_STORE> from a given directory path.
+X509_STORE_load_path() sets in B<X509_STORE> the given directory with
+certificate files in PEM format as source of trusted certificate(s).
+The certificate files in I<dir> are only looked up when required, e.g., when
+building the certificate chain or when verifying a peer certificate.
The certificates in the directory must be in hashed form, as
documented in L<X509_LOOKUP_hash_dir(3)>.
+Use the L<openssl-rehash(1)> utility to create the necessary links.
-X509_STORE_load_store_ex() loads trusted certificate(s) into an
-B<X509_STORE> from a store at a given URI. The library context I<libctx> and
+X509_STORE_load_store_ex() loads trusted certificate(s) into an B<X509_STORE>
+from a given URI. The library context I<libctx> and
property query I<propq> are used when fetching algorithms from providers.
+I<uri> must not be NULL. It must be a URI to a store, which may
+represent a single container or a whole catalogue of containers.
+If I<uri> starts with the scheme C<file:>, it is treated like a local file
+or directory.
X509_STORE_load_store() is similar to X509_STORE_load_store_ex() but
uses NULL for the library context I<libctx> and property query I<propq>.
X509_STORE_load_locations_ex() combines
X509_STORE_load_file_ex() and X509_STORE_load_path() for a given file
and/or directory path.
-It is permitted to specify just a file, just a directory, or both
-paths.
+It is permitted to specify just a file, just a directory, or both paths.
X509_STORE_load_locations() is similar to X509_STORE_load_locations_ex()
but uses NULL for the library context I<libctx> and property query I<propq>.
=head1 SEE ALSO
-L<X509_LOOKUP_hash_dir(3)>.
-L<X509_VERIFY_PARAM_set_depth(3)>.
+L<openssl-rehash(1)>,
+L<X509_LOOKUP_hash_dir(3)>,
+L<X509_VERIFY_PARAM_set_depth(3)>,
L<X509_STORE_new(3)>,
L<X509_STORE_get0_param(3)>
projects / thirdparty / openssl.git / commitdiff
