Refactor many common flags into openssl.pod
authorRich Salz <rsalz@akamai.com>
Fri, 4 Oct 2019 02:28:40 +0000 (22:28 -0400)
committerTomas Mraz <tmraz@fedoraproject.org>
Tue, 15 Oct 2019 11:47:17 +0000 (13:47 +0200)
Options moved: -rand, -writerand, -CApath, -CAfile, -no-CApath, -no-CAfile
Added rand to dgst and srp manpages (they were missing them).
New sections in openssl.pod: Random State Options, Trusted Certificate
Options.
Cleanup and add comments to find-doc-nits
Remove ".in" file support; unless giving specific arguments, this
only runs after configuration

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

30 files changed:
doc/man1/openssl-ca.pod
doc/man1/openssl-cms.pod
doc/man1/openssl-crl.pod
doc/man1/openssl-dgst.pod
doc/man1/openssl-dhparam.pod
doc/man1/openssl-dsaparam.pod
doc/man1/openssl-ecparam.pod
doc/man1/openssl-enc.pod
doc/man1/openssl-gendsa.pod
doc/man1/openssl-genrsa.pod
doc/man1/openssl-ocsp.pod
doc/man1/openssl-passwd.pod
doc/man1/openssl-pkcs12.pod
doc/man1/openssl-pkcs8.pod
doc/man1/openssl-pkeyutl.pod
doc/man1/openssl-rand.pod
doc/man1/openssl-req.pod
doc/man1/openssl-rsautl.pod
doc/man1/openssl-s_client.pod
doc/man1/openssl-s_server.pod
doc/man1/openssl-s_time.pod
doc/man1/openssl-smime.pod
doc/man1/openssl-speed.pod
doc/man1/openssl-srp.pod
doc/man1/openssl-ts.pod
doc/man1/openssl-verify.pod
doc/man1/openssl-x509.pod
doc/man1/openssl.pod
doc/man1/tsget.pod
util/find-doc-nits

index e51e5dda6fb61e4232cf5681d996aa84d7acfde0..5ff5fd954c06b5791410dd0de2ee7ef79b5c75b5 100644 (file)
@@ -294,17 +294,9 @@ C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
 If B<-multi-rdn> is not used then the UID value is C<123456+CN=John Doe>.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-sm2-id> I<string>
 
index 507490498c043905971811db38bfe94ef6d1472d..54620fef32b09b318acf424ded15baa3606ed442 100644 (file)
@@ -285,24 +285,9 @@ structure is being checked.
 For the B<-cmsout> operation print out all fields of the CMS structure. This
 is mainly useful for testing purposes.
 
-=item B<-CAfile> I<file>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-A file containing trusted CA certificates, only used with B<-verify>.
-
-=item B<-CApath> I<dir>
-
-A directory containing trusted CA certificates, only used with
-B<-verify>. This directory must be a standard certificate directory: that
-is a hash of each subject name (using C<x509 -hash>) should be linked
-to each certificate.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-md> I<digest>
 
@@ -476,17 +461,9 @@ or to modify default parameters for ECDH.
 The private key password source. For more information about the format of B<arg>
 see L<openssl(1)/Pass Phrase Options>.
 
-=item B<-rand> I<files>
-
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item I<cert.pem> ...
 
index fa29d4b0c4fe503b933c38832e4d0f2456e34478..9e5f6ca7c0b1aaa3702c1e54d4f08724cc7dcaf8 100644 (file)
@@ -21,6 +21,8 @@ B<openssl> B<crl>
 [B<-nextupdate>]
 [B<-CAfile> I<file>]
 [B<-CApath> I<dir>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
 
 =for openssl ifdef hash_old
 
@@ -92,17 +94,9 @@ Output the lastUpdate field.
 
 Output the nextUpdate field.
 
-=item B<-CAfile> I<file>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-Verify the signature on a CRL by looking up the issuing certificate in
-I<file>.
-
-=item B<-CApath> I<dir>
-
-Verify the signature on a CRL by looking up the issuing certificate in
-I<dir>. This directory must be a standard certificate directory: that
-is a hash of each subject name (using the L<openssl-x509(1)> B<-hash> option)
-should be linked to each certificate.
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =back
 
index b2da9229cfe465f528dd70cc8ed55d534b6570e6..7859d75da75af230b7922f44c9e5cd81e49c7338 100644 (file)
@@ -25,6 +25,7 @@ B<openssl> B<dgst>|I<digest>
 [B<-hmac> I<key>]
 [B<-fips-fingerprint>]
 [B<-rand> I<files>]
+[B<-writerand> I<file>]
 [B<-engine> I<id>]
 [B<-engine_impl>]
 [I<file> ...]
@@ -158,17 +159,9 @@ for example exactly 32 chars for gost-mac.
 The L<openssl-mac(1)> command should be preferred to using this command line
 option.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-fips-fingerprint>
 
index c7929e8126425dae12f1f2b5e4719093d60c86aa..a28d1b81f8ddf9ce52771badb2ee525075f0a7be 100644 (file)
@@ -86,17 +86,9 @@ input file is ignored and parameters are generated instead. If not
 present but I<numbits> is present, parameters are generated with the
 default generator 2.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item I<numbits>
 
index cc5570f3338052c7973273da3eaa8e0a87cfc9b8..5c145ef1fb8e38f68f6cdf59dc234ee96f21cb5b 100644 (file)
@@ -76,17 +76,9 @@ be loaded by calling the get_dsaXXX() function.
 This option will generate a DSA either using the specified or generated
 parameters.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-engine> I<id>
 
index e52d1833e1acc418c9be02fc1d3b4c4869298804..09c69273201667157fbfbc586985d5b03ecdcb72 100644 (file)
@@ -124,17 +124,9 @@ is included in the ECParameters structure (see RFC 3279).
 
 This option will generate an EC private key using the specified parameters.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-engine> I<id>
 
index 99486ee1521cfe3df11d95518c86ed77b1280a6d..592e4f5764040dbfcfae1b8ed173702218233348 100644 (file)
@@ -185,17 +185,9 @@ or zlib-dynamic option.
 
 Use NULL cipher (no encryption or decryption of input).
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =back
 
index 62fc25089e8227c3c093ddc451e41e116793ee99..451a3c48358ca2c8f3abadf3112dc6970426c408 100644 (file)
@@ -53,17 +53,9 @@ These options encrypt the private key with specified
 cipher before outputting it. A pass phrase is prompted for.
 If none of these options is specified no encryption is used.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-engine> I<id>
 
index 2b3c5c303f6bb1af1d8da9c2f8dde727b562a82a..d04c8eeb19ac7022204391ff4e013becc571b3f5 100644 (file)
@@ -65,17 +65,9 @@ for if it is not supplied via the B<-passout> argument.
 
 The public exponent to use, either 65537 or 3. The default is 65537.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-engine> I<id>
 
index 5e75e6af538179c54bfb2886c21bb9073bebd219..6fc077506f9deadf74c7b7115c3edd649a401d7f 100644 (file)
@@ -207,18 +207,9 @@ each child is willing to wait for the client's OCSP response.
 This option is available on POSIX systems (that support the fork() and other
 required unix system-calls).
 
-=item B<-CAfile> I<file>, B<-CApath> I<pathname>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-File or pathname containing trusted CA certificates. These are used to verify
-the signature on the OCSP response.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
 B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
index c1daac17abfbe2f0f90a7d5b6fe35b6ec367aef2..e7502ae33251a36bc159a2b268afc1548e90c98a 100644 (file)
@@ -93,17 +93,9 @@ Don't output warnings when passwords given at the command line are truncated.
 In the output list, prepend the cleartext password and a TAB character
 to each password hash.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =back
 
index 412438285fe9e8d222ce79c3f4e09309be981379..574254989153088c54b3023b0e4619bafd13d9ce 100644 (file)
@@ -263,35 +263,13 @@ to be needed to use MAC iterations counts but they are now used by default.
 
 Don't attempt to provide the MAC integrity.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
+See L<openssl(1)/Random State Options> for more information.
 
-=item B<-writerand> I<file>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
-
-=item B<-CAfile> I<file>
-
-CA storage as a file.
-
-=item B<-CApath> I<dir>
-
-CA storage as a directory. This directory must be a standard certificate
-directory: that is a hash of each subject name (using C<openssl x509 -hash>)
-should be linked to each certificate.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location.
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location.
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-CSP> I<name>
 
index 01c13487b6b71cd4a5e44ac8f9fe9bb463d79f7f..e3d779a165ba8c78463dc3b3bb47da7139513ef6 100644 (file)
@@ -101,17 +101,9 @@ This option does not encrypt private keys at all and should only be used
 when absolutely necessary. Certain software such as some versions of Java
 code signing software used unencrypted private keys.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-v2> I<alg>
 
index 6ad23064215adcb2fc3ea247c35a4b12bcd2d408..58c90436b83a10ed86d8485eedc9eb15e1755383 100644 (file)
@@ -177,17 +177,9 @@ hex dump the output data.
 Parse the ASN.1 output data, this is useful when combined with the
 B<-verifyrecover> option when an ASN1 structure is signed.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-engine> I<id>
 
index f63859e304611b054e29625856a1ea8caa7a92e5..c32b10242e86dd0f1c1da7b52a4f0790467cca32 100644 (file)
@@ -20,11 +20,7 @@ I<num>
 =head1 DESCRIPTION
 
 This command outputs I<num> pseudo-random bytes after seeding
-the random number generator once.  As in other B<openssl> command
-line tools, PRNG seeding uses the file F<$HOME/.rnd> or F<.rnd>
-in addition to the files given in the B<-rand> option.  A new
-F<$HOME/.rnd> or F<.rnd> file will be written back if enough
-seeding was obtained from these sources.
+the random number generator once.
 
 =head1 OPTIONS
 
@@ -38,17 +34,9 @@ Print out a usage message.
 
 Write to I<file> instead of standard output.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-base64>
 
index 13f62574928bddc854cd5bf3432523e014ae89a7..b84a4c92ab06860ca5cb67cdf789f410f39249b5 100644 (file)
@@ -137,17 +137,9 @@ in the configuration file and any requested extensions.
 If the B<-key> option is not used it will generate a new RSA private
 key using information specified in the configuration file.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-newkey> I<arg>
 
index 508237364c0a497a819f82beae1d771a9c5cc584..0b5fc73830ae42d9212fd6204651e326faa6176e 100644 (file)
@@ -84,17 +84,9 @@ Encrypt the input data using an RSA public key.
 
 Decrypt the input data using an RSA private key.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-pkcs>, B<-oaep>, B<-ssl>, B<-raw>
 
index b7021cdf9ab0d1e963373dd71be61944e1e9236c..0bb8781947a87dc41f41e975514a1aa9e3d77dfb 100644 (file)
@@ -306,16 +306,9 @@ I<option> argument can be a single option or multiple options separated by
 commas.  Alternatively the B<-nameopt> switch may be used more than once to
 set multiple options. See the L<openssl-x509(1)> manual page for details.
 
-=item B<-CApath> I<directory>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-The directory to use for server certificate verification. This directory
-must be in "hash format", see L<openssl-verify(1)> for more information.
-These are also used when building the client certificate chain.
-
-=item B<-CAfile> I<file>
-
-A file containing trusted certificates to use during server authentication
-and to use when attempting to build the client certificate chain.
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-chainCApath> I<directory>
 
@@ -328,14 +321,6 @@ information.
 A file containing trusted certificates to use when attempting to build the
 client certificate chain.
 
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
 =item B<-requestCAfile> I<file>
 
 A file containing a list of certificates whose subject names will be sent
@@ -674,17 +659,9 @@ to attempt to obtain a functional reference to the specified engine,
 thus initialising it if needed. The engine will then be set as the default
 for all available algorithms.
 
-=item B<-rand> I<files>
-
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-serverinfo> I<types>
 
index d035f5e4fd97abb55cd7b68900ad1df225720715..5cbfeb0f5e3b854d55a3a074ccfbcd3e547be601 100644 (file)
@@ -370,18 +370,9 @@ File to send output of B<-msg> or B<-trace> to, default standard output.
 
 Prints the SSL session states.
 
-=item B<-CAfile> I<infile>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-A file containing trusted certificates to use during client authentication
-and to use when attempting to build the server certificate chain. The list
-is also used in the list of acceptable client CAs passed to the client when
-a certificate is requested.
-
-=item B<-CApath> I<dir>
-
-The directory to use for client certificate verification. This directory
-must be in "hash format", see L<openssl-verify(1)> for more information.
-These are also used when building the server certificate chain.
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-chainCApath> I<dir>
 
@@ -394,14 +385,6 @@ information.
 A file containing trusted certificates to use when attempting to build the
 server certificate chain.
 
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location.
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location.
-
 =item B<-nocert>
 
 If this option is set then no certificate is used. This restricts the
@@ -446,17 +429,9 @@ for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
 servers, when each of which might be generating a unique range of session
 IDs (eg. with a certain prefix).
 
-=item B<-rand> I<files>
-
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-verify_return_error>
 
index 4af9e84a608c2d389b6777b7c80646e41c73c50c..f5126dae54be2ffb2c1af8df35967eb4842376b9 100644 (file)
@@ -91,18 +91,9 @@ The directory to use for server certificate verification. This directory
 must be in "hash format", see L<openssl-verify(1)> for more information.
 These are also used when building the client certificate chain.
 
-=item B<-CAfile> I<file>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-A file containing trusted certificates to use during server authentication
-and to use when attempting to build the client certificate chain.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-new>
 
index b8cb7cd63559084a78c9beac4dd6d85fa8a58bfb..ac377160a30c593ef4ecde300e4fe759ea71e2d0 100644 (file)
@@ -179,24 +179,9 @@ message if encrypting or signing. If decrypting or verifying it strips
 off text headers: if the decrypted or verified message is not of MIME
 type text/plain then an error occurs.
 
-=item B<-CAfile> I<file>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-A file containing trusted CA certificates, only used with B<-verify>.
-
-=item B<-CApath> I<dir>
-
-A directory containing trusted CA certificates, only used with
-B<-verify>. This directory must be a standard certificate directory: that
-is a hash of each subject name (using C<openssl x509 -hash>) should be linked
-to each certificate.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location.
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location.
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-md> I<digest>
 
@@ -298,17 +283,9 @@ specified, the argument is given to the engine as a key identifier.
 The private key password source. For more information about the format of I<arg>
 see L<openssl(1)/Pass Phrase Options>.
 
-=item B<-rand> I<files>
-
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-to>, B<-from>, B<-subject>
 
index d227b0235c7a1e72314673ca262d8792da678d83..e818bf6666378c234c3c21361901e4f9e1d778fb 100644 (file)
@@ -71,17 +71,9 @@ C<openssl speed -cmac aes128>.
 
 Time the decryption instead of encryption. Affects only the EVP testing.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-primes> I<num>
 
index 9096499750a3c579dff11f3bbb62907c6fbf3364..65443c25cf822ea588ddc3a0276f27f2e19533e5 100644 (file)
@@ -20,6 +20,8 @@ B<openssl srp>
 [B<-userinfo> I<text>]
 [B<-passin> I<arg>]
 [B<-passout> I<arg>]
+[B<-rand> I<files>]
+[B<-writerand> I<file>]
 [I<user> ...]
 
 =for openssl ifdef engine
@@ -69,6 +71,10 @@ The password source for the input and output file.
 For more information about the format of B<arg>
 see L<openssl(1)/Pass Phrase Options>.
 
+=item B<-rand> I<files>, B<-writerand> I<file>
+
+See L<openssl(1)/Random State Options> for more information.
+
 =back
 
 =head1 COPYRIGHT
index 1f7a0b7341cc87f6f5d9879a6723a9765b445d14..fc464217453fe74e706095c63869b67c460feb36 100644 (file)
@@ -134,17 +134,9 @@ request with the following options:
 
 =over 4
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-config> I<configfile>
 
@@ -358,20 +350,9 @@ This flag can be used together with the B<-in> option and indicates
 that the input is a DER encoded timestamp token (ContentInfo) instead
 of a timestamp response (TimeStampResp). (Optional)
 
-=item B<-CApath> I<trusted_cert_path>
-
-The name of the directory containing the trusted CA certificates of the
-client. See the similar option of L<openssl-verify(1)> for additional
-details. Either this option or B<-CAfile> must be specified. (Optional)
+=item B<-CAfile> I<file>, B<-CApath> I<dir>
 
-
-=item B<-CAfile> I<trusted_certs.pem>
-
-The name of the file containing a set of trusted self-signed CA
-certificates in PEM format. See the similar option of
-L<openssl-verify(1)> for additional details. Either this option
-or B<-CApath> must be specified.
-(Optional)
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-untrusted> I<cert_file.pem>
 
index 63277949e16573713b2f3a6fadc6cf1d61b7a1a2..abaa0755f2fc6e7d816bf74cc6a313b2221fce4e 100644 (file)
@@ -68,26 +68,9 @@ This command verifies certificate chains.
 
 Print out a usage message.
 
-=item B<-CAfile> I<file>
+=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>
 
-A I<file> of trusted certificates.
-The file should contain one or more certificates in PEM format.
-
-=item B<-CApath> I<directory>
-
-A directory of trusted certificates. The certificates should have names
-of the form: F<I<hash>.0> or have symbolic links to them of this form
-(I<hash> is the hashed certificate subject name: see the L<openssl-x509(1)>
-B<-hash> option). Under Unix, L<openssl-rehash(1)> will automatically create
-symbolic links to a directory of certificates.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location.
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location.
+See L<openssl(1)/Trusted Certificate Options> for more information.
 
 =item B<-allow_proxy_certs>
 
index 731cb61344ff2e4522c407e81a44c56940183c5f..4e13d2d88180728c9ce3cf8c2369a5752ef0e093 100644 (file)
@@ -122,17 +122,9 @@ Any digest supported by the L<openssl-dgst(1)> command can be used.
 If not specified then SHA1 is used with B<-fingerprint> or
 the default digest for the signing algorithm is used, typically SHA256.
 
-=item B<-rand> I<files>
+=item B<-rand> I<files>, B<-writerand> I<file>
 
-The files containing random data used to seed the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-writerand> I<file>
-
-Writes random data to the specified I<file> upon exit.
-This can be used with a subsequent B<-rand> flag.
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-engine> I<id>
 
index 00800d8c0b4e6d1e8ce8f215977a3eca41d3f264..fe037c5243c8a097fd67474fa498cc915951b3d7 100644 (file)
@@ -505,6 +505,14 @@ This section describes some common options with common behavior.
 =item B<-help>
 
 Provides a terse summary of all options.
+If an option takes an argument, the "type" of argument is also given.
+
+=item B<-->
+
+This terminates the list of options. It is mostly useful if any filename
+parameters start with a minus sign:
+
+ openssl verify [flags...] -- -cert1.pem...
 
 =back
 
@@ -554,6 +562,73 @@ Read the password from standard input.
 
 =back
 
+=head2 Trusted Certificate Options
+
+Part of validating a certificate includes verifying that the chain of CA's
+can be traced up to an existing trusted root.  The following options specify
+how to list the trusted roots, also known as trust anchors.  A collection
+of trusted roots is called a I<trust store>.
+
+Note that OpenSSL does not provide a default set of trust anchors.  Many
+Linux distributions include a system default and configure OpenSSL to point
+to that.  Mozilla maintains an influential trust store that can be found at
+L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>.
+
+=over 4
+
+=item B<-CAfile> I<file>
+
+Load the specified file which contains one or more PEM-format certificates
+of CA's that are trusted.
+
+=item B<-no-CAfile>
+
+Do not load the default file of trusted certificates.
+
+=item B<-CApath> I<dir>
+
+Use the specified directory as a list of trust certificates. That is,
+files should be named with the hash of the X.509 SubjectName of each
+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.
+
+=item B<-no-CApath>
+
+Do not use the default directory of trusted certificates.
+
+=back
+
+=head2 Random State Options
+
+Prior to OpenSSL 3.0, it was common for applications to store information
+about the state of the random-number generator in a file that was loaded
+at startup and rewritten upon exit. On modern operating systems, this is
+generally no longer necessary as OpenSSL will seed itself from the
+appropriate CPU flags, device files, and so on. These flags are still
+supported for special platforms or circumstances that might require them.
+
+It is generally an error to use the same seed file more than once and
+every use of B<-rand> should be paired with B<-writerand>.
+
+=over 4
+
+=item B<-rand> I<files>
+
+A file or files containing random data used to seed the random number
+generator.
+Multiple files can be specified separated by an OS-dependent character.
+The separator is C<;> for MS-Windows, C<,> for OpenVMS, and C<:> for
+all others. Another way to specify multiple files is to repeat this flag
+with different filenames.
+
+=item B<-writerand> I<file>
+
+Writes the seed data to the specified I<file> upon exit.
+This file can be used in a subsequent command invocation.
+
+=back
+
 =head1 ENVIRONMENT
 
 =over 4
index d006198c67a1fde21fb901aaf484502f4d1d7a4c..6e013b9e68753d45aceab661a6095c49a40143de 100644 (file)
@@ -113,9 +113,7 @@ option B<-C> or option B<-P> must be given in case of HTTPS. (Optional)
 
 =item B<-r> I<files>
 
-The files containing random data for seeding the random number
-generator. Multiple files can be specified, the separator is B<;> for
-MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
+See L<openssl(1)/Random State Options> for more information.
 
 =item B<-g> I<EGD_socket>
 
index 576eac2cb7a32fcdd5eaef246b7b99c67a1d2057..f1841d8a8a3b24cba99a15ea948b26ae6bc64fed 100755 (executable)
@@ -10,6 +10,7 @@
 require 5.10.0;
 use warnings;
 use strict;
+
 use Pod::Checker;
 use File::Find;
 use File::Basename;
@@ -18,7 +19,8 @@ use Getopt::Std;
 use lib catdir(dirname($0), "perl");
 use OpenSSL::Util::Pod;
 
-my $debug = 0;                  # Set to 1 for debug output
+# Set to 1 for debug output
+my $debug = 0;
 
 # Options.
 our($opt_d);
@@ -71,12 +73,14 @@ my $OUT;
 my %public;
 my $status = 0;
 
-my %mandatory_sections =
-    ( '*'    => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
-      1      => [ 'SYNOPSIS', 'OPTIONS' ],
-      3      => [ 'SYNOPSIS', 'RETURN VALUES' ],
-      5      => [ ],
-      7      => [ ] );
+my %mandatory_sections = (
+    '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
+    1   => [ 'SYNOPSIS', 'OPTIONS' ],
+    3   => [ 'SYNOPSIS', 'RETURN VALUES' ],
+    5   => [ ],
+    7   => [ ]
+);
+
 
 # Print error message, set $status.
 sub err {
@@ -116,10 +120,9 @@ sub name_synopsis {
         $names{$n} = 1;
         $foundfilename++ if $n eq $simplename;
         $foundfilenames{$n} = 1
-            if ((-f "$dirname/$n.pod.in" || -f "$dirname/$n.pod")
-                && $n ne $simplename);
+            if -f "$dirname/$n.pod" && $n ne $simplename;
     }
-    err($id, "the following exist as other .pod or .pod.in files:",
+    err($id, "the following exist as other .pod files:",
          sort keys %foundfilenames)
         if %foundfilenames;
     err($id, "$simplename (filename) missing from NAME section")
@@ -256,10 +259,9 @@ my $option_re =
 
 # Helper function to check if a given $thing is properly marked up
 # option.  It returns one of these values:
-#
-# undef         if it's not an option
-# ""            if it's a malformed option
-# $unwrapped    the option with the outermost B<> wrapping removed.
+#     undef         if it's not an option
+#     ""            if it's a malformed option
+#     $unwrapped    the option with the outermost B<> wrapping removed.
 sub normalise_option {
     my $id = shift;
     my $filename = shift;
@@ -342,7 +344,6 @@ my $symbol_re = qr/[[:alpha:]_][_[:alnum:]]*?/;
 # Checks of function name (man3) formatting.  The man3 checks are
 # easier than the man1 checks, we only check the names followed by (),
 # and only the names that have POD markup.
-
 sub functionname_check {
     my $id = shift;
     my $filename = shift;
@@ -407,6 +408,7 @@ my %preferred_words = (
     'zeroes'        => 'zeros'
 );
 
+# Search manpage for words that have a different preferred use.
 sub wording {
     my $id = shift;
     my $contents = shift;
@@ -422,6 +424,7 @@ sub wording {
         if $contents =~ /\bepoch\b/;
 }
 
+# Perform all sorts of nit/error checks on a manpage
 sub check {
     my $filename = shift;
     my $dirname = basename(dirname($filename));
@@ -515,15 +518,13 @@ sub check {
     my $section = 3;
     $section = $1 if $dirname =~ /man([1-9])/;
 
-    foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
-        # Skip "return values" if not -s
+    foreach ( (@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}}) ) {
         err($id, "missing $_ head1 section")
             if $contents !~ /^=head1\s+${_}\s*$/m;
     }
 }
 
-my %dups;
-
+# Parse libcrypto.num, etc., and return sorted list of what's there.
 sub parsenum {
     my $file = shift;
     my @apis;
@@ -545,12 +546,15 @@ sub parsenum {
     return sort @apis;
 }
 
+# Parse all the manpages, getting return map of what they document
+# (by looking at their NAME sections).
 sub getdocced
 {
     my $dir = shift;
     my %return;
+    my %dups;
 
-    foreach my $pod ( glob("$dir/*.pod"), glob("$dir/*.pod.in") ) {
+    foreach my $pod ( glob("$dir/*.pod") ) {
         my %podinfo = extract_pod_info($pod);
         foreach my $n ( @{$podinfo{names}} ) {
             $return{$n} = $pod;
@@ -563,8 +567,14 @@ sub getdocced
     return %return;
 }
 
+# Map of documented functions; function => manpage
 my %docced;
+# Map of links in each POD file; filename => [ "foo(1)", "bar(3)", ... ]
+my %link_map = ();
+# Map of names in each POD file; "name(s)" => filename
+my %name_map = ();
 
+# Load file of symbol names that we know aren't documented.
 sub loadmissing($)
 {
     my $missingfile = shift;
@@ -582,14 +592,16 @@ sub loadmissing($)
     return @missing;
 }
 
+# Check for undocumented macros; ignore those in the "missing" file
+# and do simple check for #define in our header files.
 sub checkmacros {
     my $count = 0;
     my %seen;
     my @missing;
 
-    if ($opt_o) {
+    if ( $opt_o ) {
         @missing = loadmissing('util/missingmacro111.txt');
-    } elsif ($opt_v) {
+    } elsif ( $opt_v ) {
         @missing = loadmissing('util/missingmacro.txt');
     }
 
@@ -623,6 +635,8 @@ sub checkmacros {
         if $count > 0;
 }
 
+# Find out what is undocumented (filtering out the known missing ones)
+# and display them.
 sub printem {
     my $libname = shift;
     my $numfile = shift;
@@ -630,7 +644,7 @@ sub printem {
     my $count = 0;
     my %seen;
 
-    my @missing = loadmissing($missingfile) if ($opt_v);
+    my @missing = loadmissing($missingfile) if ( $opt_v );
 
     foreach my $func ( parsenum($numfile) ) {
         next if $docced{$func} || defined $seen{$func};
@@ -650,19 +664,12 @@ sub printem {
         if $count > 0;
 }
 
-
-# Collection of links in each POD file.
-# filename => [ "foo(1)", "bar(3)", ... ]
-my %link_collection = ();
-# Collection of names in each POD file.
-# "name(s)" => filename
-my %name_collection = ();
-
+# Collect all the names in a manpage.
 sub collectnames {
     my $filename = shift;
     $filename =~ m|man(\d)/|;
     my $section = $1;
-    my $simplename = basename(basename($filename, ".in"), ".pod");
+    my $simplename = basename($filename, ".pod");
     my $id = "${filename}:1:";
 
     my $contents = '';
@@ -675,7 +682,7 @@ sub collectnames {
 
     $contents =~ /=head1 NAME([^=]*)=head1 /ms;
     my $tmp = $1;
-    unless (defined $tmp) {
+    unless ( defined $tmp ) {
         err($id, "weird name section");
         return;
     }
@@ -686,32 +693,32 @@ sub collectnames {
         map { s|/|-|g; $_ }              # Treat slash as dash
         map { s/^\s+//g; s/\s+$//g; $_ } # Trim prefix and suffix blanks
         split(/,/, $tmp);
-    unless (grep { $simplename eq $_ } @names) {
+    unless ( grep { $simplename eq $_ } @names ) {
         err($id, "missing $simplename");
         push @names, $simplename;
     }
     foreach my $name (@names) {
         next if $name eq "";
-        if ($name =~ /\s/) {
+        if ( $name =~ /\s/ ) {
             err($id, "'$name' contains white space")
         }
         my $name_sec = "$name($section)";
-        if (! exists $name_collection{$name_sec}) {
-            $name_collection{$name_sec} = $filename;
-        } elsif ($filename eq $name_collection{$name_sec}) {
+        if ( !exists $name_map{$name_sec} ) {
+            $name_map{$name_sec} = $filename;
+        } elsif ( $filename eq $name_map{$name_sec} ) {
             err($id, "$name_sec repeated in NAME section of",
-                 $name_collection{$name_sec});
+                 $name_map{$name_sec});
         } else {
             err($id, "$name_sec also in NAME section of",
-                 $name_collection{$name_sec});
+                 $name_map{$name_sec});
         }
     }
 
     my @foreign_names =
         map { map { s/\s+//g; $_ } split(/,/, $_) }
         $contents =~ /=for\s+comment\s+foreign\s+manuals:\s*(.*)\n\n/;
-    foreach (@foreign_names) {
-        $name_collection{$_} = undef; # It still exists!
+    foreach ( @foreign_names ) {
+        $name_map{$_} = undef; # It still exists!
     }
 
     my @links = $contents =~ /L<
@@ -723,14 +730,15 @@ sub collectnames {
                               # a one digit section number
                               ([^\/>\(]+\(\d\))
                              /gx;
-    $link_collection{$filename} = [ @links ];
+    $link_map{$filename} = [ @links ];
 }
 
+# Look for L<> ("link") references that point to files that do not exist.
 sub checklinks {
-    foreach my $filename (sort keys %link_collection) {
-        foreach my $link (@{$link_collection{$filename}}) {
+    foreach my $filename (sort keys %link_map) {
+        foreach my $link (@{$link_map{$filename}}) {
             err("${filename}:1:", "reference to non-existing $link")
-                unless exists $name_collection{$link};
+                unless exists $name_map{$link};
         }
     }
 }
@@ -748,7 +756,8 @@ sub publicize {
     }
 }
 
-# Cipher/digests to skip if not documented
+# Cipher/digests to skip if they show up as "not implemented"
+# because they are, via the "-*" construct.
 my %skips = (
     'aes128' => 1,
     'aes192' => 1,
@@ -766,6 +775,7 @@ my %skips = (
     'digest' => 1,
 );
 
+# Check the flags of a command and see if everything is in the manpage
 sub checkflags {
     my $cmd = shift;
     my $doc = shift;
@@ -803,30 +813,27 @@ sub checkflags {
     close CFH;
 
     # See what's in the command not the manpage.
-    my @undocced = ();
-    foreach my $k ( keys %cmdopts ) {
-        push @undocced, $k unless $docopts{$k};
-    }
-    if ( scalar @undocced > 0 ) {
-        foreach ( @undocced ) {
-            next if /-/; # Skip the -- end-of-flags marker
-            err("$doc: undocumented option -$_");
-        }
+    my @undocced = sort grep { !defined $docopts{$_} } keys %cmdopts;
+    foreach ( @undocced ) {
+        next if /-/; # Skip the -- end-of-flags marker
+        err("$doc: undocumented option -$_");
     }
 
     # See what's in the command not the manpage.
-    my @unimpl = ();
-    foreach my $k ( keys %docopts ) {
-        push @unimpl, $k unless $cmdopts{$k};
-    }
-    if ( scalar @unimpl > 0 ) {
-        foreach ( @unimpl ) {
-            next if defined $skips{$_} || defined $localskips{$_};
-            err("$cmd documented but not implemented -$_");
-        }
+    my @unimpl = sort grep { !defined $cmdopts{$_} } keys %docopts;
+    foreach ( @unimpl ) {
+        next if defined $skips{$_} || defined $localskips{$_};
+        err("$cmd documented but not implemented -$_");
     }
 }
 
+##
+##  MAIN()
+##  Do the work requested by the various getopt flags.
+##  The flags are parsed in alphabetical order, just because we have
+##  to have *some way* of listing them.
+##
+
 if ( $opt_c ) {
     my @commands = ();
 
@@ -865,8 +872,7 @@ if ( $opt_c ) {
 }
 
 if ( $opt_l ) {
-    foreach (@ARGV ? @ARGV : (glob('doc/*/*.pod'), glob('doc/*/*.pod.in'),
-                              glob('doc/internal/*/*.pod'))) {
+    foreach ( @ARGV ? @ARGV : glob('doc/*/*.pod doc/internal/*/*.pod') ) {
         collectnames($_);
     }
     checklinks();
@@ -874,10 +880,7 @@ if ( $opt_l ) {
 
 if ( $opt_n ) {
     publicize();
-    foreach (@ARGV ? @ARGV : (glob('doc/*/*.pod'), glob('doc/*/*.pod.in'))) {
-        check($_);
-    }
-    foreach (@ARGV ? @ARGV : glob('doc/internal/*/*.pod')) {
+    foreach ( @ARGV ? @ARGV : glob('doc/*/*.pod doc/internal/*/*.pod') ) {
         check($_);
     }
 
@@ -895,7 +898,7 @@ if ( $opt_u || $opt_v) {
     foreach ( keys %temp ) {
         $docced{$_} = $temp{$_};
     }
-    if ($opt_o) {
+    if ( $opt_o ) {
         printem('crypto', 'util/libcrypto.num', 'util/missingcrypto111.txt');
         printem('ssl', 'util/libssl.num', 'util/missingssl111.txt');
     } else {