apps/*.c,doc/man1/*.pod.in: fix doc and error output of cert_store vs. chain_store...

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 dbec80e6823f178c4117a14da98c7457d88c3862..46f9b3b11e328ca0ba12599280471946397301b6 100644 (file)
--- 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 f98e14616d9d97b7c934d399dcb2caae1e3d8943..ba0f323a6ba19355f0a83462f1b7b9a19240880c 100644 (file)
--- 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 c10eec811e57a17fdee0e6bf1d60f1433f85dc46..b0b3da914995aa388c8eecefe56f792cdc447e9a 100644 (file)
--- 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 11d54ed10b2c48dbd0a4d0b09426a71c5c16ce95..2293185dafa2a70264efd674977ddcd3a2cc023d 100644 (file)
--- 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 09ed684472ce951e582461052c53a6dba40d309b..f8179995629d8e54d8ed629521b52460960d7987 100644 (file)
--- 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 d2d8175901a420a4ce326a795c352143216e7cef..08ad758ebfec884b84ad722ddac4c48b88f1cf47 100644 (file)
--- 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 ebb8514fef3a4f71e78f0e137cefa5e334c70c7e..7ed53093d68c3c4c0a7fe53347ddaa1fbfb46570 100644 (file)
--- 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 9bfe6f6f132ab603771de4e9e3674996e86299e4..78df23673530514aefb67926b18fadf039ccb943 100644 (file)
--- 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 5f656c91b5d73304f0f3df85c9c6b445f75dfb4d..7f639ebd5b8b9f0e56df6cb92f5ecdf84f6e1c90 100644 (file)
--- 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 f231f16ef9bd1653a5eb50c1ddadfa500cd57694..aaec526154c2c7133b0372202a76888786167576 100644 (file)
--- 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 05fbdfc9030106fc2a9f3d38c135469192192c15..d16ccbaac05b1932430d30837c495b0abd367aa8 100644 (file)
--- 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 eec81948ff905a940f2848e50201e2d36a084a7f..3257e9f68018fc937f52349c7b23fb5d5989927e 100644 (file)
--- 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 b063a39573ef1af59fe7fe3f88b262883b6e094e..2a295cac2226451d5aac5662074c522bff315671 100644 (file)
--- 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 ffaae0b91d70f76e62020b36181beb2805514501..e330f8f015074b5e2a16ee02de8b7e6207f552fc 100644 (file)
--- 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 221060021721bed2161a638889ca6ac522dcd6df..6c9f46075418b588b65ea814afd1f7f22b332b89 100644 (file)
--- 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