Fix descriptions of credentials and verification options for various apps

fix doc of s_client and s_server credentials and verification options
fix doc of verification options also for s_time, x509, crl, req, ts, and verify
correcting and extending texts regarding untrusted and trusted certs,
making the order of options in the docs and help texts more consistent,
etc.

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11273)

5 files changed, 135 insertions, 88 deletions

diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index 982c54ae9e..f66e6e5d63 100644
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -30,22 +30,21 @@ B<openssl> B<s_client>
 [B<-verifyCAstore> I<uri>]
 [B<-cert> I<filename>]
 [B<-certform> B<DER>|B<PEM>]
+[B<-cert_chain> I<filename>]
+[B<-build_chain>]
 [B<-CRL> I<filename>]
 [B<-CRLform> B<DER>|B<PEM>]
 [B<-crl_download>]
 [B<-key> I<filename>]
-[B<-keyform> B<DER>|B<PEM>]
-[B<-cert_chain> I<filename>]
-[B<-build_chain>]
+[B<-keyform> B<DER>|B<PEM>|B<ENGINE>]
 [B<-pass> I<arg>]
-[B<-chainCApath> I<directory>]
 [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>]
 [B<-dane_ee_no_namechecks>]
-[B<-build_chain>]
 [B<-reconnect>]
 [B<-showcerts>]
 [B<-prexit>]
@@ -236,12 +235,25 @@ ClientHello message. Cannot be used in conjunction with the B<-servername> or
 
 =item B<-cert> I<certname>
 
-The certificate to use, if one is requested by the server. The default is
-not to use a certificate.
+The client certificate to use, if one is requested by the server.
+The default is not to use a certificate.
 
-=item B<-certform> I<format>
+The chain for the client certificate may be specified using B<-cert_chain>.
 
-The certificate format to use: DER or PEM. PEM is the default.
+=item B<-certform> B<DER>|B<PEM>
+
+The client certificate file format to use; the default is B<PEM>.
+see L<openssl(1)/Format Options>.
+
+=item B<-cert_chain>
+
+A file containing untrusted certificates to use when attempting to build the
+certificate chain related to the certificate specified via the B<-cert> option.
+
+=item B<-build_chain>
+
+Specify whether the application should build the client certificate chain to be
+provided to the server.
 
 =item B<-CRL> I<filename>
 
@@ -249,7 +261,7 @@ CRL file to use to check the server's certificate.
 
 =item B<-CRLform> B<DER>|B<PEM>
 
-The CRL format; the default is B<PEM>.
+The CRL file format; the default is B<PEM>.
 See L<openssl(1)/Format Options> for details.
 
 =item B<-crl_download>
@@ -258,25 +270,14 @@ Download CRL from distribution points in the certificate.
 
 =item B<-key> I<keyfile>
 
-The private key to use. If not specified then the certificate file will
-be used.
+The client private key file to use.
+If not specified then the certificate file will be used to read also the key.
 
-=item B<-keyform> I<format>
+=item B<-keyform> B<DER>|B<PEM>|B<ENGINE>
 
 The key format; the default is B<PEM>.
 See L<openssl(1)/Format Options> for details.
 
-=item B<-cert_chain>
-
-A file containing trusted certificates to use when attempting to build the
-client/server certificate chain related to the certificate specified via the
-B<-cert> option.
-
-=item B<-build_chain>
-
-Specify whether the application should build the certificate chain to be
-provided to the server.
-
 =item B<-pass> I<arg>
 
 the private key password source. For more information about the format of I<arg>
@@ -301,32 +302,42 @@ Limit verify output to only errors.
 
 =item B<-verifyCAfile> I<filename>
 
-CA file for verifying the server's certificate, in PEM format.
+A file in PEM format containing trusted certificates to use
+for verifying the server's certificate.
 
 =item B<-verifyCApath> I<dir>
 
-Use the specified directory as a certificate store path to verify
-the server's CA certificate.
+A directory containing trusted certificates to use
+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>
 
-Use the specified URI as a store URI to verify the server's certificate.
-
+The URI of a store containing trusted certificates to use
+for verifying the server's certificate.
 
-=item B<-chainCApath> I<directory>
+=item B<-chainCAfile> I<file>
 
-The directory to use for building the chain provided to the server. This
-directory must be in "hash format", see L<openssl-verify(1)> for more
-information.
+A file in PEM format containing trusted certificates to use
+when attempting to build the client certificate chain.
 
-=item B<-chainCAfile> I<file>
+=item B<-chainCApath> I<directory>
 
-A file containing trusted certificates to use when attempting to build the
-client certificate chain.
+A directory containing trusted certificates to use
+for building 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 to use when attempting to build the client certificate chain.
+The URI of a store containing trusted certificates to use
+when attempting to build the client certificate chain.
+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.
 
 =item B<-requestCAfile> I<file>
 
diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in
index 0fd22d4689..c7c78562c1 100644
--- a/doc/man1/openssl-s_server.pod.in
+++ b/doc/man1/openssl-s_server.pod.in
@@ -19,16 +19,20 @@ B<openssl> B<s_server>
 [B<-verify> I<int>]
 [B<-Verify> I<int>]
 [B<-cert> I<infile>]
-[B<-naccept> I<+int>]
-[B<-serverinfo> I<val>]
+[B<-cert2> I<infile>]
 [B<-certform> B<DER>|B<PEM>]
+[B<-cert_chain> I<infile>]
+[B<-build_chain>]
+[B<-serverinfo> I<val>]
 [B<-key> I<infile>]
-[B<-keyform> B<DER>|B<PEM>]
+[B<-key2> I<infile>]
+[B<-keyform> B<DER>|B<PEM>|B<ENGINE>]
 [B<-pass> I<val>]
 [B<-dcert> I<infile>]
 [B<-dcertform> B<DER>|B<PEM>]
+[B<-dcert_chain> I<infile>]
 [B<-dkey> I<infile>]
-[B<-dkeyform> B<DER>|B<PEM>]
+[B<-dkeyform> B<DER>|B<PEM>|B<ENGINE>]
 [B<-dpass> I<val>]
 [B<-nbio_test>]
 [B<-crlf>]
@@ -44,29 +48,24 @@ B<openssl> B<s_server>
 [B<-http_server_binmode>]
 [B<-servername>]
 [B<-servername_fatal>]
-[B<-cert2> I<infile>]
-[B<-key2> I<infile>]
 [B<-tlsextdebug>]
 [B<-HTTP>]
 [B<-id_prefix> I<val>]
 [B<-keymatexport> I<val>]
 [B<-keymatexportlen> I<+int>]
-[B<-CRLform> B<DER>|B<PEM>]
 [B<-CRL> I<infile>]
+[B<-CRLform> B<DER>|B<PEM>]
 [B<-crl_download>]
-[B<-cert_chain> I<infile>]
-[B<-dcert_chain> I<infile>]
+[B<-chainCAfile> I<infile>]
 [B<-chainCApath> I<dir>]
-[B<-verifyCApath> I<dir>]
 [B<-chainCAstore> I<uri>]
+[B<-verifyCAfile> I<infile>]
+[B<-verifyCApath> I<dir>]
 [B<-verifyCAstore> I<uri>]
 [B<-no_cache>]
 [B<-ext_cache>]
 [B<-verify_return_error>]
 [B<-verify_quiet>]
-[B<-build_chain>]
-[B<-chainCAfile> I<infile>]
-[B<-verifyCAfile> I<infile>]
 [B<-ign_eof>]
 [B<-no_ign_eof>]
 [B<-status>]
@@ -84,6 +83,7 @@ B<openssl> B<s_server>
 [B<-max_send_frag> I<+int>]
 [B<-split_send_frag> I<+int>]
 [B<-max_pipelines> I<+int>]
+[B<-naccept> I<+int>]
 [B<-read_buf> I<+int>]
 [B<-bugs>]
 [B<-no_comp>]
@@ -219,22 +219,21 @@ certificate and some require a certificate with a certain public key type:
 for example the DSS cipher suites require a certificate containing a DSS
 (DSA) key. If not specified then the filename F<server.pem> will be used.
 
+=item B<-certform> B<DER>|B<PEM>
+
+The server certificate file format; the default is B<PEM>.
+See L<openssl(1)/Format Options> for details.
+
 =item B<-cert_chain>
 
-A file containing trusted certificates to use when attempting to build the
-client/server certificate chain related to the certificate specified via the
-B<-cert> option.
+A file containing untrusted certificates to use when attempting to build the
+certificate chain related to the certificate specified via the B<-cert> option.
 
 =item B<-build_chain>
 
-Specify whether the application should build the certificate chain to be
+Specify whether the application should build the server certificate chain to be
 provided to the client.
 
-=item B<-naccept> I<+int>
-
-The server will exit after receiving the specified number of connections,
-default unlimited.
-
 =item B<-serverinfo> I<val>
 
 A file containing one or more blocks of PEM data.  Each PEM block
@@ -243,17 +242,12 @@ followed by "length" bytes of extension data).  If the client sends
 an empty TLS ClientHello extension matching the type, the corresponding
 ServerHello extension will be returned.
 
-=item B<-certform> B<DER>|B<PEM>, B<-CRLForm> B<DER>|B<PEM>
-
-The certificate and CRL format; the default is PEM.
-See L<openssl(1)/Format Options> for details.
-
 =item B<-key> I<infile>
 
 The private key to use. If not specified then the certificate file will
 be used.
 
-=item B<-keyform> B<DER>|B<PEM>
+=item B<-keyform> B<DER>|B<PEM>|B<ENGINE>
 
 The key format; the default is B<PEM>.
 See L<openssl(1)/Format Options> for details.
@@ -277,14 +271,19 @@ by using an appropriate certificate.
 
 =item B<-dcert_chain>
 
-A file containing trusted certificates to use when attempting to build the
+A file containing untrusted certificates to use when attempting to build the
 server certificate chain when a certificate specified via the B<-dcert> option
 is in use.
 
-=item B<-dcertform> B<DER>|B<PEM>, B<-dkeyform> B<DER>|B<PEM>
+=item B<-dcertform> B<DER>|B<PEM>
+
+The format of the additional certificate file; the default is B<PEM>.
+See L<openssl(1)/Format Options>.
+
+=item B<-dkeyform> B<DER>|B<PEM>|B<ENGINE>
 
-The format of the certificate and private key; the default is B<PEM>
-see L<openssl(1)/Format Options>.
+The format of the additional private key; the default is B<PEM>.
+See L<openssl(1)/Format Options>.
 
 =item B<-dpass> I<val>
 
@@ -316,22 +315,53 @@ File to send output of B<-msg> or B<-trace> to, default standard output.
 
 Prints the SSL session states.
 
-=item B<-chainCApath> I<dir>
+=item B<-CRL> I<infile>
+
+The CRL file to use.
+
+=item B<-CRLform> B<DER>|B<PEM>
+
+The CRL file format; the default is B<PEM>.
+See L<openssl(1)/Format Options> for details.
+
+=item B<-crl_download>
+
+Download CRLs from distribution points given in CDP extensions of certificates
 
-The directory to use for building the chain provided to the client. This
-directory must be in "hash format", see L<openssl-verify(1)> for more
-information.
+=item B<-verifyCAfile> I<filename>
+
+A file in PEM format CA containing trusted certificates to use
+for verifying client certificates.
+
+=item B<-verifyCApath> I<dir>
+
+A directory containing trusted certificates to use
+for verifying client certificates.
+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 client certificates.
 
 =item B<-chainCAfile> I<file>
 
-A file containing trusted certificates to use when attempting to build the
-server certificate chain.
+A file in PEM format containing trusted certificates to use
+when attempting to build the server certificate chain.
+
+=item B<-chainCApath> I<dir>
+
+A directory containing trusted certificates to use
+for building the server certificate chain provided to the client.
+This directory must be in "hash format",
+see L<openssl-verify(1)> for more information.
 
 =item B<-chainCAstore> I<uri>
 
-The URI to a store to use for building the chain provided to the client.
-The URI may indicate a single certificate, as well as a collection of
-them.
+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.
@@ -462,6 +492,11 @@ an effect if an engine has been loaded that supports pipelining (e.g. the dasync
 engine) and a suitable cipher suite has been negotiated. The default value is 1.
 See L<SSL_CTX_set_max_pipelines(3)> for further information.
 
+=item B<-naccept> I<+int>
+
+The server will exit after receiving the specified number of connections,
+default unlimited.
+
 =item B<-read_buf> I<+int>
 
 The default read buffer size to be used for connections. This will only have an
diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in
index 38fcf530fe..8437862c2c 100644
--- a/doc/man1/openssl-ts.pod.in
+++ b/doc/man1/openssl-ts.pod.in
@@ -37,7 +37,6 @@ B<-reply>
 [B<-chain> I<certs_file.pem>]
 [B<-tspolicy> I<object_id>]
 [B<-in> I<response.tsr>]
-[B<-untrusted> I<file>]
 [B<-token_in>]
 [B<-out> I<response.tsr>]
 [B<-token_out>]
@@ -52,6 +51,7 @@ B<-verify>
 [B<-queryfile> I<request.tsq>]
 [B<-in> I<response.tsr>]
 [B<-token_in>]
+[B<-untrusted> I<file>]
 [B<-CAfile> I<file>]
 [B<-CApath> I<dir>]
 [B<-CAstore> I<uri>]
diff --git a/doc/man1/openssl-verify.pod.in b/doc/man1/openssl-verify.pod.in
index 821f88dae9..2b824c0370 100644
--- a/doc/man1/openssl-verify.pod.in
+++ b/doc/man1/openssl-verify.pod.in
@@ -38,10 +38,6 @@ This command verifies certificate chains.
 
 Print out a usage message.
 
-=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
-
-See L<openssl(1)/Trusted Certificate Options> for more information.
-
 =item B<-CRLfile> I<file>
 
 The I<file> should contain one or more CRLs in PEM format.
@@ -50,7 +46,7 @@ I<file>s.
 
 =item B<-crl_download>
 
-Attempt to download CRL information for this certificate.
+Attempt to download CRL information for certificates via their CDP entries.
 
 =item B<-show_chain>
 
@@ -64,11 +60,16 @@ Print extra information about the operations being performed.
 
 =item B<-trusted> I<file>
 
-A file of trusted certificates.
+A file of trusted certificates in PEM format.
+This option can be specified more than once to load certificates from multiple
+I<file>s.
 
 =item B<-untrusted> I<file>
 
-A file of untrusted certificates.
+A file of untrusted certificates in PEM format to use for chain building.
+This option can be specified more than once to load certificates from multiple
+I<file>s.
+
 
 =item B<-vfyopt> I<nm>:I<v>
 
diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index c05fc29f67..c8de9016fb 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -977,8 +977,8 @@ effect.
 Parse I<file> as a set of one or more certificates in PEM format.
 All certificates must be self-signed, unless the
 B<-partial_chain> option is specified.
-This option implies the B<-no-CAfile> and B<-no-CApath> options and it
-cannot be used with either the B<-CAfile> or B<-CApath> options, so
+This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options
+and it cannot be used with the B<-CAfile>, B<-CApath> or B<-CAstore> options, so
 only certificates in the file are trust anchors.
 This option may be used multiple times.