Commit d260311c53 for openssl.org
commit d260311c53a0d656b880266f4c9c14c5f5da5bd8
Author: Dr. David von Oheimb <dev@ddvo.net>
Date: Sun Oct 13 21:20:28 2024 +0200
apps/*.c,doc/man1/*.pod.in: fix doc and error output of 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:15 2026
(Merged from https://github.com/openssl/openssl/pull/25683)
diff --git a/apps/cms.c b/apps/cms.c
index dbec80e682..46f9b3b11e 100644
--- a/apps/cms.c
+++ b/apps/cms.c
@@ -284,9 +284,9 @@ const OPTIONS cms_options[] = {
{ "cades", OPT_DUP, '-', "Check signingCertificate (CAdES-BES)" },
{ "verify_retcode", OPT_VERIFY_RETCODE, '-',
"Exit non-zero on verification failure" },
- { "CAfile", OPT_CAFILE, '<', "Trusted certificates file" },
- { "CApath", OPT_CAPATH, '/', "Trusted certificates directory" },
- { "CAstore", OPT_CASTORE, ':', "Trusted certificates store URI" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
diff --git a/apps/crl.c b/apps/crl.c
index f98e14616d..ba0f323a6b 100644
--- a/apps/crl.c
+++ b/apps/crl.c
@@ -84,9 +84,9 @@ const OPTIONS crl_options[] = {
{ "gendelta", OPT_GENDELTA, '<', "Other CRL to compare/diff to the Input one" },
OPT_SECTION("Certificate"),
- { "CApath", OPT_CAPATH, '/', "Verify CRL using certificates in dir" },
- { "CAfile", OPT_CAFILE, '<', "Verify CRL using certificates in file name" },
- { "CAstore", OPT_CASTORE, ':', "Verify CRL using certificates in store URI" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
diff --git a/apps/lib/s_cb.c b/apps/lib/s_cb.c
index c10eec811e..b0b3da9149 100644
--- a/apps/lib/s_cb.c
+++ b/apps/lib/s_cb.c
@@ -1405,12 +1405,18 @@ int ssl_load_stores(SSL_CTX *ctx,
vfy = X509_STORE_new();
if (vfy == NULL)
goto err;
- if (vfyCAfile != NULL && !X509_STORE_load_file(vfy, vfyCAfile))
+ if (vfyCAfile != NULL && !X509_STORE_load_file(vfy, vfyCAfile)) {
+ BIO_printf(bio_err, "Error loading trusted peer verification cert file %s\n", vfyCAfile);
goto err;
- if (vfyCApath != NULL && !X509_STORE_load_path(vfy, vfyCApath))
+ }
+ if (vfyCApath != NULL && !X509_STORE_load_path(vfy, vfyCApath)) {
+ BIO_printf(bio_err, "Error adding trusted peer verification certs directory %s\n", vfyCApath);
goto err;
- if (vfyCAstore != NULL && !X509_STORE_load_store(vfy, vfyCAstore))
+ }
+ if (vfyCAstore != NULL && !X509_STORE_load_store(vfy, vfyCAstore)) {
+ BIO_printf(bio_err, "Error adding trusted peer verification cert store file %s\n", vfyCAstore);
goto err;
+ }
add_crls_store(vfy, crls);
if (SSL_CTX_set1_verify_cert_store(ctx, vfy) == 0)
goto err;
@@ -1421,12 +1427,18 @@ int ssl_load_stores(SSL_CTX *ctx,
ch = X509_STORE_new();
if (ch == NULL)
goto err;
- if (chCAfile != NULL && !X509_STORE_load_file(ch, chCAfile))
+ if (chCAfile != NULL && !X509_STORE_load_file(ch, chCAfile)) {
+ BIO_printf(bio_err, "Error loading trusted chain building cert file %s\n", chCAfile);
goto err;
- if (chCApath != NULL && !X509_STORE_load_path(ch, chCApath))
+ }
+ if (chCApath != NULL && !X509_STORE_load_path(ch, chCApath)) {
+ BIO_printf(bio_err, "Error adddng trusted chain building cert directory %s\n", chCApath);
goto err;
- if (chCAstore != NULL && !X509_STORE_load_store(ch, chCAstore))
+ }
+ if (chCAstore != NULL && !X509_STORE_load_store(ch, chCAstore)) {
+ BIO_printf(bio_err, "Error adddng trusted chain building cert store file %s\n", chCAstore);
goto err;
+ }
if (SSL_CTX_set1_chain_cert_store(ctx, ch) == 0)
goto err;
}
diff --git a/apps/ocsp.c b/apps/ocsp.c
index 11d54ed10b..2293185daf 100644
--- a/apps/ocsp.c
+++ b/apps/ocsp.c
@@ -152,9 +152,9 @@ const OPTIONS ocsp_options[] = {
{ "help", OPT_HELP, '-', "Display this summary" },
{ "ignore_err", OPT_IGNORE_ERR, '-',
"Ignore error on OCSP request or response and continue running" },
- { "CAfile", OPT_CAFILE, '<', "Trusted certificates file" },
- { "CApath", OPT_CAPATH, '<', "Trusted certificates directory" },
- { "CAstore", OPT_CASTORE, ':', "Trusted certificates store URI" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
diff --git a/apps/pkcs12.c b/apps/pkcs12.c
index 09ed684472..f817999562 100644
--- a/apps/pkcs12.c
+++ b/apps/pkcs12.c
@@ -157,9 +157,9 @@ const OPTIONS pkcs12_options[] = {
{ OPT_MORE_STR, 0, 0,
"which is the 1st cert from -in matching the private key (if given)" },
{ "untrusted", OPT_UNTRUSTED, '<', "Untrusted certificates for chain building" },
- { "CAfile", OPT_CAFILE, '<', "PEM-format file of CA's" },
- { "CApath", OPT_CAPATH, '/', "PEM-format directory of CA's" },
- { "CAstore", OPT_CASTORE, ':', "URI to store of CA's" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
diff --git a/apps/s_client.c b/apps/s_client.c
index d2d8175901..08ad758ebf 100644
--- a/apps/s_client.c
+++ b/apps/s_client.c
@@ -686,9 +686,9 @@ const OPTIONS s_client_options[] = {
{ "pass", OPT_PASS, 's', "Private key and cert file pass phrase source" },
{ "verify", OPT_VERIFY, 'p', "Turn on peer certificate verification, set depth" },
{ "nameopt", OPT_NAMEOPT, 's', "Certificate subject/issuer name printing options" },
- { "CApath", OPT_CAPATH, '/', "PEM format directory of CA's" },
- { "CAfile", OPT_CAFILE, '<', "PEM format file of CA's" },
- { "CAstore", OPT_CASTORE, ':', "URI to store of CA's" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
@@ -874,17 +874,21 @@ const OPTIONS s_client_options[] = {
"Close connection on verification error" },
{ "verify_quiet", OPT_VERIFY_QUIET, '-', "Restrict verify output to errors" },
{ "chainCAfile", OPT_CHAINCAFILE, '<',
- "CA file for certificate chain (PEM format)" },
+ "File in PEM format with trusted CA certs to build own cert chain" },
{ "chainCApath", OPT_CHAINCAPATH, '/',
- "Use dir as certificate store path to build CA certificate chain" },
+ "Dir with trusted CA cert files in PEM format to build own cert chain" },
{ "chainCAstore", OPT_CHAINCASTORE, ':',
- "CA store URI for certificate chain" },
+ "URI of trusted CA cert store to build own cert chain" },
+ { OPT_MORE_STR, 0, 0,
+ "NOTE: these override -CApath, -CAfile, and -CAstore for client chain building" },
{ "verifyCAfile", OPT_VERIFYCAFILE, '<',
- "CA file for certificate verification (PEM format)" },
+ "File in PEM format with trusted CA certs for server cert verification" },
{ "verifyCApath", OPT_VERIFYCAPATH, '/',
- "Use dir as certificate store path to verify CA certificate" },
+ "Dir with trusted CA cert files in PEM format for server cert verification" },
{ "verifyCAstore", OPT_VERIFYCASTORE, ':',
- "CA store URI for certificate verification" },
+ "URI of trusted CA cert store for server cert verification" },
+ { OPT_MORE_STR, 0, 0,
+ "NOTE: these override -CApath, -CAfile, and -CAstore for server cert verification" },
OPT_X_OPTIONS,
OPT_PROV_OPTIONS,
@@ -2084,7 +2088,7 @@ int s_client_main(int argc, char **argv)
vfyCApath, vfyCAfile, vfyCAstore,
chCApath, chCAfile, chCAstore,
crls, crl_download)) {
- BIO_puts(bio_err, "Error loading store locations\n");
+ BIO_puts(bio_err, "Error loading store locations for server cert verification and client cert chain building\n");
goto end;
}
if (ReqCAfile != NULL) {
@@ -2192,8 +2196,10 @@ int s_client_main(int argc, char **argv)
SSL_CTX_set_verify(ctx, verify, verify_callback);
if (!ctx_set_verify_locations(ctx, CAfile, noCAfile, CApath, noCApath,
- CAstore, noCAstore))
+ CAstore, noCAstore)) {
+ BIO_puts(bio_err, "Error setting default locations for trusted certificates\n");
goto end;
+ }
ssl_ctx_add_crls(ctx, crls, crl_download);
diff --git a/apps/s_server.c b/apps/s_server.c
index ebb8514fef..7ed53093d6 100644
--- a/apps/s_server.c
+++ b/apps/s_server.c
@@ -1340,9 +1340,9 @@ const OPTIONS s_server_options[] = {
OPT_SECTION("Identity"),
{ "context", OPT_CONTEXT, 's', "Set session ID context" },
- { "CAfile", OPT_CAFILE, '<', "PEM format file of CA's" },
- { "CApath", OPT_CAPATH, '/', "PEM format directory of CA's" },
- { "CAstore", OPT_CASTORE, ':', "URI to store of CA's" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
@@ -1409,17 +1409,21 @@ const OPTIONS s_server_options[] = {
{ "crl_download", OPT_CRL_DOWNLOAD, '-',
"Download CRLs from distribution points in certificate CDP entries" },
{ "chainCAfile", OPT_CHAINCAFILE, '<',
- "CA file for certificate chain (PEM format)" },
+ "File in PEM format with trusted CA certs to build own cert chain" },
{ "chainCApath", OPT_CHAINCAPATH, '/',
- "use dir as certificate store path to build CA certificate chain" },
+ "Dir with trusted CA cert files in PEM format to build own cert chain" },
{ "chainCAstore", OPT_CHAINCASTORE, ':',
- "use URI as certificate store to build CA certificate chain" },
+ "URI of trusted CA cert store to build own cert chain" },
+ { OPT_MORE_STR, 0, 0,
+ "NOTE: these override -CApath, -CAfile, and -CAstore for server chain building" },
{ "verifyCAfile", OPT_VERIFYCAFILE, '<',
- "CA file for certificate verification (PEM format)" },
+ "File in PEM format with trusted CA certs for client cert verification" },
{ "verifyCApath", OPT_VERIFYCAPATH, '/',
- "use dir as certificate store path to verify CA certificate" },
+ "Dir with trusted CA cert files in PEM format for client cert verification" },
{ "verifyCAstore", OPT_VERIFYCASTORE, ':',
- "use URI as certificate store to verify CA certificate" },
+ "URI of trusted CA cert store for client cert verification" },
+ { OPT_MORE_STR, 0, 0,
+ "NOTE: these override -CApath, -CAfile, and -CAstore for client cert verification" },
{ "expected-rpks", OPT_EXPECTED_RPK, '<',
"PEM file with expected client public key(s)" },
{ "no_cache", OPT_NO_CACHE, '-', "Disable session cache" },
diff --git a/apps/s_time.c b/apps/s_time.c
index 9bfe6f6f13..78df236735 100644
--- a/apps/s_time.c
+++ b/apps/s_time.c
@@ -103,9 +103,10 @@ const OPTIONS s_time_options[] = {
{ "nameopt", OPT_NAMEOPT, 's', "Certificate subject/issuer name printing options" },
{ "cert", OPT_CERT, '<', "Cert file to use, PEM format assumed" },
{ "key", OPT_KEY, '<', "File with key, PEM; default is -cert file" },
- { "cafile", OPT_CAFILE, '<', "PEM format file of CA's" },
- { "CAfile", OPT_CAFILE, '<', "PEM format file of CA's" },
- { "CApath", OPT_CAPATH, '/', "PEM format directory of CA's" },
+ { "cafile", OPT_CAFILE, '<', "Deprecated alias of -CAfile" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "CAstore", OPT_CASTORE, ':', "URI to store of CA's" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
diff --git a/apps/smime.c b/apps/smime.c
index 5f656c91b5..7f639ebd5b 100644
--- a/apps/smime.c
+++ b/apps/smime.c
@@ -141,9 +141,9 @@ const OPTIONS smime_options[] = {
{ "nosmimecap", OPT_NOSMIMECAP, '-', "Omit the SMIMECapabilities attribute" },
OPT_SECTION("Certificate chain"),
- { "CApath", OPT_CAPATH, '/', "Trusted certificates directory" },
- { "CAfile", OPT_CAFILE, '<', "Trusted certificates file" },
- { "CAstore", OPT_CASTORE, ':', "Trusted certificates store URI" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
diff --git a/apps/ts.c b/apps/ts.c
index f231f16ef9..aaec526154 100644
--- a/apps/ts.c
+++ b/apps/ts.c
@@ -114,9 +114,9 @@ const OPTIONS ts_options[] = {
{ "inkey", OPT_INKEY, 's', "File with private key for reply" },
{ "signer", OPT_SIGNER, 's', "Signer certificate file" },
{ "chain", OPT_CHAIN, '<', "File with signer CA chain" },
- { "CAfile", OPT_CAFILE, '<', "File with trusted CA certs" },
- { "CApath", OPT_CAPATH, '/', "Path to trusted CA files" },
- { "CAstore", OPT_CASTORE, ':', "URI to trusted CA store" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "untrusted", OPT_UNTRUSTED, '<', "Extra untrusted certs" },
{ "token_in", OPT_TOKEN_IN, '-', "Input is a PKCS#7 file" },
{ "token_out", OPT_TOKEN_OUT, '-', "Output is a PKCS#7 file" },
diff --git a/apps/verify.c b/apps/verify.c
index 05fbdfc903..d16ccbaac0 100644
--- a/apps/verify.c
+++ b/apps/verify.c
@@ -56,9 +56,9 @@ const OPTIONS verify_options[] = {
OPT_SECTION("Certificate chain"),
{ "trusted", OPT_TRUSTED, '<', "A file of trusted certificates" },
- { "CAfile", OPT_CAFILE, '<', "A file of trusted certificates" },
- { "CApath", OPT_CAPATH, '/', "A directory of files with trusted certificates" },
- { "CAstore", OPT_CASTORE, ':', "URI to a store of trusted certificates" },
+ { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
+ { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
+ { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
{ "no-CAfile", OPT_NOCAFILE, '-',
"Do not load the default trusted certificates file" },
{ "no-CApath", OPT_NOCAPATH, '-',
diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index eec81948ff..3257e9f680 100644
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -26,9 +26,13 @@ B<openssl> B<s_client>
[B<-verify> I<depth>]
[B<-verify_return_error>]
[B<-verify_quiet>]
+{- $OpenSSL::safe::opt_trust_synopsis -}
[B<-verifyCAfile> I<filename>]
[B<-verifyCApath> I<dir>]
[B<-verifyCAstore> I<uri>]
+[B<-chainCAfile> I<filename>]
+[B<-chainCApath> I<directory>]
+[B<-chainCAstore> I<uri>]
[B<-cert> I<filename>]
[B<-certform> B<DER>|B<PEM>|B<P12>]
[B<-cert_chain> I<filename>]
@@ -39,9 +43,6 @@ B<openssl> B<s_client>
[B<-key> I<filename>|I<uri>]
[B<-keyform> B<DER>|B<PEM>|B<P12>]
[B<-pass> I<arg>]
-[B<-chainCAfile> I<filename>]
-[B<-chainCApath> I<directory>]
-[B<-chainCAstore> I<uri>]
[B<-requestCAfile> I<filename>]
[B<-dane_tlsa_domain> I<domain>]
[B<-dane_tlsa_rrdata> I<rrdata>]
@@ -116,7 +117,6 @@ B<openssl> B<s_client>
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_version_synopsis -}
{- $OpenSSL::safe::opt_x_synopsis -}
-{- $OpenSSL::safe::opt_trust_synopsis -}
{- $OpenSSL::safe::opt_s_synopsis -}
{- $OpenSSL::safe::opt_r_synopsis -}
{- $OpenSSL::safe::opt_provider_synopsis -}
@@ -325,22 +325,38 @@ This will typically abort the handshake with a fatal error.
Limit verify output to only errors.
+{- $OpenSSL::safe::opt_trust_item -}
+
+The certificates loaded via the B<-CAfile>, B<-CApath>, and B<-CAstore> options
+are used as trust anchors when verifying the server's certificate unless
+overridden by B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> options.
+They are also used as trust anchors when attempting
+to build the client certificate chain provided to the server unless
+overridden by B<-chainCAfile>, B<-chainCApath>, or B<-chainCAstore> options.
+
=item B<-verifyCAfile> I<filename>
-A file in PEM format containing trusted certificates to use
-for verifying the server's certificate.
+A file in PEM format containing one or more CA certificates
+to trust for verifying the server's certificate.
+
+This and the following two options, B<-verifyCApath> and B<-verifyCAstore>,
+take precedence over the B<-CAfile>, B<-CApath>, and B<-CAstore> options.
=item B<-verifyCApath> I<dir>
-A directory containing trusted certificates to use
-for verifying the server's certificate.
+A directory with files in PEM format containing CA certificates
+to trust for verifying the server's certificate.
This directory must be in "hash format",
see L<openssl-verify(1)> for more information.
=item B<-verifyCAstore> I<uri>
-The URI of a store containing trusted certificates to use
-for verifying the server's certificate.
+URI of a store containing CA certificates
+to trust for verifying the server's certificate.
+The URI may indicate a single certificate, as well as a collection of them.
+With URIs in the C<file:> scheme, this is generally treated like B<-verifyCApath> or
+B<-verifyCAfile>, depending on if the URI indicates a directory or a single file.
+See L<ossl_store(7)> for more information on stores and supported schemes.
When any of B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> is
specified, they are loaded into a separate verification store (via
@@ -350,25 +366,27 @@ B<-CAstore>.
=item B<-chainCAfile> I<file>
-A file in PEM format containing trusted certificates to use
-when attempting to build the client certificate chain.
+A file in PEM format containing one or more trusted CA certificates to use
+when attempting to build the client certificate chain provided to the server.
+
+This and the following two options, B<-chainCApath> and B<-chainCAstore>,
+take precedence over the B<-CAfile>, B<-CApath>, and B<-CAstore> options.
=item B<-chainCApath> I<directory>
-A directory containing trusted certificates to use
-for building the client certificate chain provided to the server.
+A directory with files in PEM format containing trusted CA certificates to use
+when attempting to build the client certificate chain provided to the server.
This directory must be in "hash format",
see L<openssl-verify(1)> for more information.
=item B<-chainCAstore> I<uri>
The URI of a store containing trusted certificates to use
-when attempting to build the client certificate chain.
+when attempting to build the client certificate chain provided to the server.
The URI may indicate a single certificate, as well as a collection of them.
-With URIs in the C<file:> scheme, this acts as B<-chainCAfile> or
-B<-chainCApath>, depending on if the URI indicates a directory or a
-single file.
-See L<ossl_store-file(7)> for more information on the C<file:> scheme.
+With URIs in the C<file:> scheme, this is generally treated like B<-chainCApath> or
+B<-chainCAfile>, depending on whether the URI points to a directory or a single file.
+See L<ossl_store(7)> for more information on stores and supported schemes.
=item B<-requestCAfile> I<file>
@@ -800,8 +818,6 @@ Enable creation of connections via TCP fast open (RFC7413).
{- $OpenSSL::safe::opt_x_item -}
-{- $OpenSSL::safe::opt_trust_item -}
-
{- $OpenSSL::safe::opt_s_item -}
{- $OpenSSL::safe::opt_r_item -}
@@ -1118,7 +1134,7 @@ L<SSL_CONF_cmd(3)>,
L<SSL_CTX_set_max_send_fragment(3)>,
L<SSL_CTX_set_split_send_fragment(3)>,
L<SSL_CTX_set_max_pipelines(3)>,
-L<ossl_store-file(7)>
+L<ossl_store(7)>
=head1 HISTORY
diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in
index b063a39573..2a295cac22 100644
--- a/doc/man1/openssl-s_server.pod.in
+++ b/doc/man1/openssl-s_server.pod.in
@@ -344,6 +344,9 @@ Download CRLs from distribution points given in CDP extensions of certificates
A file in PEM format containing trusted CA certificates (root and/or
intermediate) used to verify the client certificate chain.
+This and the following two options, B<-verifyCApath> and B<-verifyCAstore>,
+take precedence over the B<-CAfile>, B<-CApath>, and B<-CAstore> options.
+
=item B<-verifyCApath> I<dir>
A directory containing trusted certificates to use
@@ -353,14 +356,14 @@ see L<openssl-verify(1)> for more information.
=item B<-verifyCAstore> I<uri>
-The URI of a store containing trusted certificates to use
+URI of a store containing trusted certificates to use
for verifying client certificates.
+The URI may indicate a single certificate, as well as a collection of them.
+With URIs in the C<file:> scheme, this is generally treated like B<-verifyCApath> or
+B<-verifyCAfile>, depending on whether the URI points to a directory or a single file.
+See L<ossl_store(7)> for more information on stores and supported schemes.
-When any of B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> is
-specified, they are loaded into a separate verification store (via
-L<SSL_CTX_set1_verify_cert_store(3)>) and used for client certificate
-verification instead of the store built from B<-CAfile>, B<-CApath>, and
-B<-CAstore>. Note that B<-CAfile> is the sole source of acceptable issuing
+Note that B<-CAfile> is the sole source of acceptable issuing
CA names sent to the client in the Certificate Request message during the
handshake; B<-CApath>, B<-CAstore>, and the B<-verifyCA*> options do not
contribute to this list.
@@ -370,6 +373,9 @@ contribute to this list.
A file in PEM format containing trusted certificates to use
when attempting to build the server certificate chain.
+This and the following two options, B<-chainCApath> and B<-chainCAstore>,
+take precedence over the B<-CAfile>, B<-CApath>, and B<-CAstore> options.
+
=item B<-chainCApath> I<dir>
A directory containing trusted certificates to use
@@ -382,10 +388,9 @@ see L<openssl-verify(1)> for more information.
The URI of a store containing trusted certificates to use
for building the server certificate chain provided to the client.
The URI may indicate a single certificate, as well as a collection of them.
-With URIs in the C<file:> scheme, this acts as B<-chainCAfile> or
-B<-chainCApath>, depending on if the URI indicates a directory or a
-single file.
-See L<ossl_store-file(7)> for more information on the C<file:> scheme.
+With URIs in the C<file:> scheme, this is generally treated like B<-chainCApath> or
+B<-chainCAfile>, depending on whether the URI points to a directory or a single file.
+See L<ossl_store(7)> for more information on stores and supported schemes.
=item B<-nocert>
@@ -806,6 +811,17 @@ Pre-compresses certificates (RFC8879) that will be sent during the handshake.
{- $OpenSSL::safe::opt_trust_item -}
+The certificates loaded via the B<-CAfile>, B<-CApath>, and B<-CAstore> options
+are used as trust anchors when verifying client certificates unless
+overridden by B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> options.
+They are also used as trust anchors when attempting
+to build the server certificate chain provided to clients unless
+overridden by B<-chainCAfile>, B<-chainCApath>, or B<-chainCAstore> options.
+
+B<-CAfile> also determines the list of acceptable issuing CA names
+sent to the client in the Certificate Request message during the handshake;
+B<-CApath>, B<-CAstore>, and the B<-verifyCA*> options do not contribute here.
+
{- $OpenSSL::safe::opt_r_item -}
{- $OpenSSL::safe::opt_provider_item -}
@@ -971,7 +987,7 @@ L<SSL_CONF_cmd(3)>,
L<SSL_CTX_set_max_send_fragment(3)>,
L<SSL_CTX_set_split_send_fragment(3)>,
L<SSL_CTX_set_max_pipelines(3)>,
-L<ossl_store-file(7)>
+L<ossl_store(7)>
=head1 HISTORY
diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod
index ffaae0b91d..e330f8f015 100644
--- a/doc/man1/openssl-verification-options.pod
+++ b/doc/man1/openssl-verification-options.pod
@@ -292,7 +292,8 @@ Do not load the default file of trusted certificates.
Use the specified directory as a collection of trusted certificates,
i.e., a trust store.
-Files should be named with the hash value of the X.509 SubjectName of each
+Each file should contain exactly one certificate in PEM format.
+It should be named with the hash value of the X.509 SubjectName of the
certificate. This is so that the library can extract the IssuerName,
hash it, and directly lookup the file to get the issuer certificate.
See L<openssl-rehash(1)> for information on creating this type of directory.
@@ -303,12 +304,12 @@ Do not use the default directory of trusted certificates.
=item B<-CAstore> I<uri>
-Use I<uri> as a store of CA certificates.
-The URI may indicate a single certificate, as well as a collection of them.
-With URIs in the C<file:> scheme, this acts as B<-CAfile> or
-B<-CApath>, depending on if the URI indicates a single file or
-directory.
-See L<ossl_store-file(7)> for more information on the C<file:> scheme.
+Use I<uri> as a store of trusted certificates.
+The URI may indicate a single certificate or a collection of them.
+When the URI references a file, only the PEM format is supported.
+With URIs in the C<file:> scheme, this is generally treated like B<-CApath> or
+B<-CAfile>, depending on whether the URI indicates a directory or a single file.
+See L<ossl_store(7)> for more information on stores and supported schemes.
These certificates are also used when building the server certificate
chain (for example with L<openssl-s_server(1)>) or client certificate
@@ -316,7 +317,7 @@ chain (for example with L<openssl-s_time(1)>).
=item B<-no-CAstore>
-Do not use the default store of trusted CA certificates.
+Do not use the default store of trusted certificates.
=back
@@ -479,7 +480,7 @@ Since B<-trusted_first> is always on, this option has no effect.
=item B<-trusted> I<file>
-Parse I<file> as a set of one or more certificates.
+Parse I<file> as a set of one or more certificates in PEM format.
Each of them qualifies as trusted if has a suitable positive trust attribute
or it is apparently self-signed or the B<-partial_chain> option is specified.
This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options
@@ -489,7 +490,7 @@ This option may be used multiple times.
=item B<-untrusted> I<file>
-Parse I<file> as a set of one or more certificates.
+Parse I<file> as a set of one or more certificates in PEM format.
All certificates (typically of intermediate CAs) are considered untrusted
and may be used to
construct a certificate chain from the target certificate to a trust anchor.
diff --git a/doc/man7/provider-storemgmt.pod b/doc/man7/provider-storemgmt.pod
index 2210600217..6c9f460754 100644
--- a/doc/man7/provider-storemgmt.pod
+++ b/doc/man7/provider-storemgmt.pod
@@ -192,7 +192,9 @@ decoder implementations.
=item "input-type" (B<OSSL_STORE_PARAM_INPUT_TYPE>) <utf8 string>
Type of the input format as a hint to use when decoding the objects in the
-store.
+store, such as C<DER> and C<PEM>.
+See L<openssl-format-options(1)> for details on their use for OpenSSL commands.
+
=back