fixup! s_client.c,*.pod: fix documentation on cert_store vs. chain_st…

…ore/verify_store and PEM format

apps/lib/s_cb.c

@@ -1377,8 +1377,10 @@ 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))
             goto err;
         if (vfyCAstore != NULL && !X509_STORE_load_store(vfy, vfyCAstore))
@@ -1393,8 +1395,10 @@ 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))
             goto err;
         if (chCAstore != NULL && !X509_STORE_load_store(ch, chCAstore))

apps/rehash.c

@@ -268,7 +268,7 @@ static int do_file(const char *filename, const char *fullpath, enum Hash h)
     if (sk_X509_INFO_num(inf) != 1) {
         BIO_printf(bio_err,
                    "%s: warning: skipping %s, "
-                   "it does not contain exactly one certificate or CRL\n",
+                   "it seems not to contain exactly one certificate or CRL in PEM format\n",
                    opt_getprog(), filename);
         /* This is not an error. */
         goto end;

apps/s_client.c

@@ -1899,7 +1899,7 @@ int s_client_main(int argc, char **argv)
                          vfyCApath, vfyCAfile, vfyCAstore,
                          chCApath, chCAfile, chCAstore,
                          crls, crl_download)) {
-        BIO_printf(bio_err, "Error loading locations for server cert verificationi and client cert chain building\n");
+        BIO_printf(bio_err, "Error loading locations for server cert verification and client cert chain building\n");
         ERR_print_errors(bio_err);
         goto end;
     }

doc/man1/openssl-rehash.pod.in

@@ -33,14 +33,14 @@ B<c_rehash>
 
 =head1 DESCRIPTION
 
-This command is generally equivalent to the external
-script B<c_rehash>,
+This command is generally equivalent to the external script B<c_rehash>,
 except for minor differences noted below.
 
-B<openssl rehash> scans directories and calculates a hash value of
-each F<.pem>, F<.crt>, F<.cer>, or F<.crl>
-file in the specified directory list and creates symbolic links
-for each file, where the name of the link is the hash value.
+B<openssl rehash> scans directories and calculates a hash value for each
+F<.pem>, F<.crt>, F<.cer>, or F<.crl> file in the specified directory list
+that is in PEM format and contains exactly one certificate or CRL.
+For each of these files, it creates a symbolic link with its name being the
+hash value of the certificate subject name or CRL issuer name, respectively.
 (If the platform does not support symbolic links, a copy is made.)
 This command is useful as many programs that use OpenSSL require
 directories to be set up like this in order to find certificates.
@@ -66,12 +66,12 @@ the period, like this: I<HHHHHHHH.>B<r>I<D>.
 
 Multiple objects may have the same hash; they will be indicated by
 incrementing the I<D> value. Duplicates are found by comparing the
-full SHA-1 fingerprint. A warning will be displayed if a duplicate
-is found.
+full SHA-1 fingerprint of the certificate or CRL.
+A warning will be displayed if a duplicate is found.
 
-A warning will also be displayed if there are files that
-cannot be parsed as either a certificate or a CRL or if
-more than one such object appears in the file.
+A warning will also be displayed if there are files with a recoginzed filename
+extension that cannot be parsed as either a certificate or a CRL in PEM format
+or contain more than one such object.
 
 =head2 Script Configuration
 
@@ -85,8 +85,11 @@ a certificate or CRL:
   $OPENSSL x509 -hash -fingerprint -noout -in FILENAME
   $OPENSSL crl -hash -fingerprint -noout -in FILENAME
 
-where I<FILENAME> is the filename. It must output the hash of the
-file on the first line, and the fingerprint on the second,
+where I<FILENAME> is the filename. It must output
+for the certificate or CRL contained in the input file the
+hash value of the certificate subject name or CRL issuer name, respectively,
+on the first line,
+and the fingerprint of the full certificate or CRL structure on the second line,
 optionally prefixed with some text and an equals sign.
 
 =head1 OPTIONS

doc/man1/openssl-s_client.pod.in

@@ -321,26 +321,32 @@ Limit verify output to only errors.
 
 =item B<-CAfile> I<file>
 
-A file in PEM format containing trusted CA certificates.
+A file in PEM format containing one or more trusted CA certificates.
+They are used as trust anchors when verifying the server's certificate unless
+overridden by B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> options.
+They are 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<-CApath> I<directory>
 
-A directory with files in PEM format containing trusted CA certificates.
+A directory with files in PEM format, each containing a trusted CA certificate
+for the same purposes as specified with the B<-CAfile> option.
 This directory must be in "hash format",
-see L<openssl-verify(1)> for more information.
+see L<openssl-rehash(1)> for more information.
 
 =item B<-CAstore> I<uri>
 
-The URI of a store containing trusted CA certificates in PEM format.
+The URI of a store containing trusted CA certificates in PEM format
+for the same purposes as specified with the B<-CAfile> option.
 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 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<-CApath> or
+B<-CAfile>, depending on if the URI indicates a directory or a single file.
+See L<openssl-rehash(1)> for more information on the C<file:> scheme.
 
 =item B<-verifyCAfile> I<filename>
 
-A file in PEM format containing CA certificates
+A file in PEM format containing one or more CA certificates
 to trust for verifying the server's certificate.
 
 =item B<-verifyCApath> I<dir>, B<-CApath> I<dir>
@@ -355,14 +361,13 @@ see L<openssl-verify(1)> for more information.
 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 acts as B<-verifyCAfile> or
-B<-verifyCApath>, depending on if the URI indicates a directory or a
-single file.
+With URIs in the C<file:> scheme, this is generally treated like B<-CApath> or
+B<-CAfile>, 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.
 
 =item B<-chainCAfile> I<file>
 
-A file in PEM format containing trusted CA certificates to use
+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.
 
 =item B<-chainCApath> I<directory>
@@ -377,9 +382,8 @@ see L<openssl-verify(1)> for more information.
 The URI of a store containing trusted certificates to use
 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.
+With URIs in the C<file:> scheme, this is generally treated like B<-CApath> or
+B<-CAfile>, 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.
 
 =item B<-requestCAfile> I<file>

doc/man1/openssl-verification-options.pod

@@ -411,7 +411,8 @@ effect.
 
 =item B<-trusted> I<file>
 
-Parse I<file> as a set of one or more certificates.
+Parse I<file> as a set of certificates.
+When the file is in PEM format, it may contain multiple certificates.
 Each of them qualifies as trusted if has a suitable positive trust attribute
 or it is 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
@@ -421,7 +422,8 @@ 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 certificates.
+When the file is in PEM format, it may contain multiple certificates.
 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.

doc/man3/SSL_CTX_load_verify_locations.pod

@@ -31,7 +31,7 @@ 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 in PEM format are located.
 For details see the L</NOTES> below.
-The SSL context B<ctx> B<MUST NOT> be NULL.
+The SSL context I<ctx> B<MUST NOT> be NULL.
 
 Details of the certificate verification and chain checking process are
 described in L<openssl-verification-options(1)/Certification Path Validation>.
@@ -49,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> B<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
@@ -74,7 +74,7 @@ building the chain of the own client/server certificate 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)>.
 
-If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
+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-----
@@ -84,41 +84,43 @@ format. The file can contain several CA certificates identified by
 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()
+The I<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
 function.
 
-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
+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
+If more than one CA certificate with the same subject name hash value exist, the
 extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
 is performed in the ordering of the extension number, regardless of other
 properties of the certificates.
-Use the B<c_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 certificate chain of the own client or server certificate
+or when actually performing the verification of 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>.
+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. Apart from the I<CAstore> not necessarily being a local file or
+directory, it's generally treated the same way as a I<CApath>
+if the store behaves like a directory, otherwise like I<CAfile>.
 
 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)>.
@@ -140,7 +142,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 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.
 
@@ -166,13 +168,13 @@ ca1.pem ca2.pem ca3.pem:
  done
 
 Prepare the directory /some/where/certs containing several CA certificates
-for use as B<CApath>:
+for use as I<CApath>:
 
- cd /some/where/certs
- c_rehash .
+ openssl rehash /some/where/certs
 
 =head1 SEE ALSO
 
+L<openssl-rehash(1)>,
 L<ssl(7)>,
 L<SSL_CTX_set0_verify_cert_store(3)>,
 L<SSL_CTX_set1_verify_cert_store(3)>,

doc/man3/SSL_CTX_set1_verify_cert_store.pod

@@ -32,13 +32,13 @@ verification or chain store
 
 SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store()
 set the certificate store used for peer certificate verification to B<st>.
-The override for this purpose any locations set by
+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>.
-The override for this purpose any locations set by
+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.
 

doc/man3/X509_LOOKUP.pod

@@ -123,10 +123,16 @@ 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. Apart from the I<uri> not necessarily being a local file or
+directory, the function behaves generally like X509_LOOKUP_add_dir() if
+the store is a directory, otherwise like X509_LOOKUP_load_file_ex().
 
 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>.

doc/man3/X509_LOOKUP_hash_dir.pod

@@ -80,7 +80,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.
 
@@ -109,12 +109,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 all files with suffix like F<.pem> in a given directory.
 
 =head2 OSSL_STORE Method
 
@@ -140,6 +136,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)>,
@@ -148,6 +145,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.