[openssl-dev] [openssl.org #3663] [PATCH] clarify 'verify' command operation

[Adam Williamson via RT]

Explain that chains cannot be passed as the [certificates] but
the intermediates must be passed to -untrusted, explain in a
bit more detail how CApath and CAfile are used, and try a bit
harder in VERIFY OPERATION to explain what it means in terms
of the command line parameters.

This foxed me for a while until I figured it out, and there's
a question on StackOverflow illustrating the same confusion:
https://stackoverflow.com/questions/23304139
So it seems worth explaining.
---
 doc/apps/verify.pod | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod
index a5a0063..782b46d 100644
--- a/doc/apps/verify.pod
+++ b/doc/apps/verify.pod
@@ -54,7 +54,9 @@ The B<verify> command verifies certificate chains.
 =item B<-CAfile file>
 
 A file of trusted certificates. The file should contain multiple certificates
-in PEM format concatenated together.
+in PEM format concatenated together. If not passed, the default location set
+at compile time will be checked and certificates from that location will be
+included in the list of trusted certificates if found.
 
 =item B<-CApath directory>
 
@@ -62,7 +64,9 @@ A directory of trusted certificates. The certificates should have names
 of the form: hash.0 or have symbolic links to them of this
 form ("hash" is the hashed certificate subject name: see the B<-hash> option
 of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
-create symbolic links to a directory of certificates.
+create symbolic links to a directory of certificates. If not passed, the
+default location set at compile time will be checked and certificates from
+that location will be included in the list of trusted certificates if found.
 
 =item B<-attime timestamp>
 
@@ -166,8 +170,8 @@ This is mainly useful in environments with Bridge CA or Cross-Certified CAs.
 
 =item B<-untrusted file>
 
-A file of untrusted certificates. The file should contain multiple certificates
-in PEM format concatenated together.
+A file of untrusted certificates. The file should contain one or more
+certificates in PEM format concatenated together.
 
 =item B<-use_deltas>
 
@@ -215,9 +219,14 @@ with a B<->.
 
 =item B<certificates>
 
-One or more certificates to verify. If no certificates are given, B<verify>
-will attempt to read a certificate from standard input. Certificates must be
-in PEM format.
+One or more certificates to verify. Each will be verified independently of all
+the others. If no certificates are given, B<verify> will attempt to read a
+certificate from standard input. Certificates must be in PEM format. Only one
+certificate will be read from each file: passing a chain of certificates
+concatenated together will not verify the chain, it will verify the first
+certificate in the file and ignore the others. To verify a chain, pass the
+intermediate certificate(s) to B<-untrusted> and give only the final
+certificate in the chain here.
 
 =back
 
@@ -252,11 +261,12 @@ of the current certificate (if present) must match the subject key identifier
 the keyUsage extension of the candidate issuer (if present) must permit
 certificate signing.
 
-The lookup first looks in the list of untrusted certificates and if no match
-is found the remaining lookups are from the trusted certificates. The root CA
-is always looked up in the trusted certificate list: if the certificate to
-verify is a root certificate then an exact match must be found in the trusted
-list.
+The lookup first looks in the list of untrusted certificates passed to
+B<-untrusted> and if no match is found the remaining lookups are from the trusted
+certificates passed to B<-CAfile> and/or B<-CApath> and/or found in the default
+locations. The root CA is always looked up in the trusted certificate list: if
+the certificate to verify is a root certificate then an exact match must be
+found in the trusted certificate list.
 
 The second operation is to check every untrusted certificate's extensions for
 consistency with the supplied purpose. If the B<-purpose> option is not included
-- 
2.2.1