Commit 2b5a525b6d for openssl.org
commit 2b5a525b6ddf5931fa8936c0a09c0a09345bfe27
Author: Dr. David von Oheimb <dev@ddvo.net>
Date: Thu Apr 23 21:54:10 2026 +0200
doc/man3/*.pod: fix doc cert_store vs. chain_store/verify_store and PEM format
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
MergeDate: Mon Jun 1 04:57:17 2026
(Merged from https://github.com/openssl/openssl/pull/25683)
diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod
index c129f17f7b..b127ac3868 100644
--- a/doc/man3/SSL_CTX_load_verify_locations.pod
+++ b/doc/man3/SSL_CTX_load_verify_locations.pod
@@ -27,18 +27,20 @@ SSL_CTX_set_default_verify_store, SSL_CTX_load_verify_locations
=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
@@ -47,7 +49,7 @@ The default CA certificates file is called F<cert.pem> in the default
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
@@ -63,51 +65,63 @@ used.
=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)>.
@@ -129,7 +143,7 @@ For SSL_CTX_load_verify_locations the following return values can occur:
=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.
@@ -154,21 +168,29 @@ ca1.pem ca2.pem ca3.pem:
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
diff --git a/doc/man3/SSL_CTX_set1_verify_cert_store.pod b/doc/man3/SSL_CTX_set1_verify_cert_store.pod
index ba8a380bb8..fbfbaf6a48 100644
--- a/doc/man3/SSL_CTX_set1_verify_cert_store.pod
+++ b/doc/man3/SSL_CTX_set1_verify_cert_store.pod
@@ -31,10 +31,16 @@ verification or chain store
=head1 DESCRIPTION
SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store()
-set the certificate store used for certificate verification to B<st>.
-
-SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store()
-set the certificate store used for certificate chain building to B<st>.
+set the certificate store used for peer certificate verification to B<st>.
+They override for this purpose any locations set by
+L<SSL_CTX_load_verify_locations(3)>, L<SSL_CTX_set_default_verify_paths(3)>,
+L<SSL_CTX_load_verify_file(3)>, L<SSL_CTX_set_default_verify_file(3)>, etc.
+
+SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store() set the
+cert store for building the chain of the own client/server certificate to B<st>.
+They override for this purpose any locations set by
+L<SSL_CTX_load_verify_locations(3)>, L<SSL_CTX_set_default_verify_paths(3)>,
+L<SSL_CTX_load_verify_file(3)>, L<SSL_CTX_set_default_verify_file(3)>, etc.
SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(),
SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar
diff --git a/doc/man3/X509_LOOKUP.pod b/doc/man3/X509_LOOKUP.pod
index 2c1d88c0fd..b17a47e9bb 100644
--- a/doc/man3/X509_LOOKUP.pod
+++ b/doc/man3/X509_LOOKUP.pod
@@ -123,10 +123,14 @@ I<type> indicates what type of object is expected.
This can only be used with a lookup using the implementation
L<X509_LOOKUP_hash_dir(3)>.
-X509_LOOKUP_add_store_ex() passes a URI for a directory-like structure
-from which containers with certificates and CRLs are loaded on demand
+X509_LOOKUP_add_store_ex() passes a URI for a directory-like or file-like
+structure from which containers with certificates and CRLs are loaded on demand
into the associated B<X509_STORE>. The library context I<libctx> and property
query I<propq> are used when fetching algorithms from providers.
+If I<uri> is not 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. See also ossl_store-file(7).
X509_LOOKUP_add_store() is similar to X509_LOOKUP_add_store_ex() but
uses NULL for the library context I<libctx> and property query I<propq>.
diff --git a/doc/man3/X509_LOOKUP_hash_dir.pod b/doc/man3/X509_LOOKUP_hash_dir.pod
index 35160e87c5..b512f2a3cf 100644
--- a/doc/man3/X509_LOOKUP_hash_dir.pod
+++ b/doc/man3/X509_LOOKUP_hash_dir.pod
@@ -81,7 +81,7 @@ set of CAs.
B<X509_LOOKUP_hash_dir> is a more advanced method, which loads
certificates and CRLs on demand, and caches them in memory once
-they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs
+they are loaded. It also checks for newer CRLs
upon each lookup, so that newer CRLs are as soon as they appear in
the directory.
@@ -110,12 +110,8 @@ When checking for new CRLs once one CRL for given hash value is
loaded, hash_dir lookup method checks only for certificates with
sequence number greater than that of the already cached CRL.
-Note that the hash algorithm used for subject name hashing changed in OpenSSL
-1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
-0.9.8 to 1.0.0.
-
OpenSSL includes a L<openssl-rehash(1)> utility which creates symlinks with
-hashed names for all files with F<.pem> suffix in a given directory.
+hashed names for files in PEM format in a given directory.
=head2 OSSL_STORE Method
@@ -144,6 +140,7 @@ the number of loaded objects or 0 on error.
=head1 SEE ALSO
+L<openssl-rehash(1)>,
L<PEM_read_PrivateKey(3)>,
L<X509_STORE_load_locations(3)>,
L<SSL_CTX_load_verify_locations(3)>,
@@ -152,6 +149,9 @@ L<ossl_store(7)>
=head1 HISTORY
+The hash algorithm used for subject name hashing changed in OpenSSL 1.0.0.
+All certificate stores had to be rehashed when moving from OpenSSL 0.9.8 to 1.0.0.
+
The functions X509_load_cert_file_ex(),
X509_load_cert_crl_file_ex() and X509_LOOKUP_store() were added in
OpenSSL 3.0.
diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod
index 65d9068812..cb083dc1d0 100644
--- a/doc/man3/X509_STORE_add_cert.pod
+++ b/doc/man3/X509_STORE_add_cert.pod
@@ -95,21 +95,28 @@ L<X509_LOOKUP_METHOD(3)> I<meth> and adds it to the B<X509_STORE>
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>.
@@ -117,8 +124,7 @@ 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>.
@@ -149,8 +155,9 @@ L<X509_LOOKUP(3)>, or NULL on error.
=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)>