more doc fixes

dgst: using digest instead of specific digest commands
the digest list specified in man dgst may be inaccurate, hence using
digest and referring to the list in digest-commands

'sha' as a digest name is no longer supported

dgst,pkeyutl cmds help cleanup
- In dgst, pkeyutl cmds, some options help was missing.
- fixed a minor typo in openssl.pod, that fixes make install.
- digest-commands was showing ‘sha’, which is not a supported digest
anymore.

Signed-off-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>

apps/dgst.c

@@ -91,9 +91,10 @@ OPTIONS dgst_options[] = {
     {"help", OPT_HELP, '-', "Display this summary"},
     {"c", OPT_C, '-', "Print the digest with separating colons"},
     {"r", OPT_R, '-', "Print the digest in coreutils format"},
-    {"rand", OPT_RAND, 's'},
+    {"rand", OPT_RAND, 's',
+     "Use file(s) containing random data to seed RNG or an EGD sock"},
     {"out", OPT_OUT, '>', "Output to filename rather than stdout"},
-    {"passin", OPT_PASSIN, 's'},
+    {"passin", OPT_PASSIN, 's', "Input file pass phrase source"},
     {"sign", OPT_SIGN, '<', "Sign digest using private key in file"},
     {"verify", OPT_VERIFY, '<',
      "Verify a signature using public key in file"},
@@ -104,8 +105,9 @@ OPTIONS dgst_options[] = {
     {"hex", OPT_HEX, '-', "Print as hex dump"},
     {"binary", OPT_BINARY, '-', "Print in binary form"},
     {"d", OPT_DEBUG, '-', "Print debug info"},
-    {"debug", OPT_DEBUG, '-'},
+    {"debug", OPT_DEBUG, '-', "Print debug info"},
-    {"fips-fingerprint", OPT_FIPS_FINGERPRINT, '-'},
+    {"fips-fingerprint", OPT_FIPS_FINGERPRINT, '-',
+     "Compute HMAC with the key used in OpenSSL-FIPS fingerprint"},
     {"hmac", OPT_HMAC, 's', "Create hashed MAC with key"},
     {"mac", OPT_MAC, 's', "Create MAC (not necessarily HMAC)"},
     {"sigopt", OPT_SIGOPT, 's', "Signature parameter in n:v form"},
@@ -113,7 +115,8 @@ OPTIONS dgst_options[] = {
     {"", OPT_DIGEST, '-', "Any supported digest"},
 #ifndef OPENSSL_NO_ENGINE
     {"engine", OPT_ENGINE, 's', "Use engine e, possibly a hardware device"},
-    {"engine_impl", OPT_ENGINE_IMPL, '-'},
+    {"engine_impl", OPT_ENGINE_IMPL, '-',
+     "Also use engine given by -engine for digest operations"},
 #endif
     {NULL}
 };

apps/pkeyutl.c

@@ -89,22 +89,22 @@ typedef enum OPTION_choice {
 
 OPTIONS pkeyutl_options[] = {
     {"help", OPT_HELP, '-', "Display this summary"},
-    {"in", OPT_IN, '<', "Input file"},
+    {"in", OPT_IN, '<', "Input file - default stdin"},
-    {"out", OPT_OUT, '>', "Output file"},
+    {"out", OPT_OUT, '>', "Output file - default stdout"},
     {"pubin", OPT_PUBIN, '-', "Input is a public key"},
     {"certin", OPT_CERTIN, '-', "Input is a cert with a public key"},
     {"asn1parse", OPT_ASN1PARSE, '-', "asn1parse the output data"},
     {"hexdump", OPT_HEXDUMP, '-', "Hex dump output"},
-    {"sign", OPT_SIGN, '-', "Sign with private key"},
+    {"sign", OPT_SIGN, '-', "Sign input data with private key"},
     {"verify", OPT_VERIFY, '-', "Verify with public key"},
     {"verifyrecover", OPT_VERIFYRECOVER, '-',
      "Verify with public key, recover original data"},
-    {"rev", OPT_REV, '-', "Reverse the input buffer"},
+    {"rev", OPT_REV, '-', "Reverse the order of the input buffer"},
-    {"encrypt", OPT_ENCRYPT, '-', "Encrypt with public key"},
+    {"encrypt", OPT_ENCRYPT, '-', "Encrypt input data with public key"},
-    {"decrypt", OPT_DECRYPT, '-', "Decrypt with private key"},
+    {"decrypt", OPT_DECRYPT, '-', "Decrypt input data with private key"},
     {"derive", OPT_DERIVE, '-', "Derive shared secret"},
     {"sigfile", OPT_SIGFILE, '<', "Signature file (verify operation only)"},
-    {"inkey", OPT_INKEY, 's', "Input key"},
+    {"inkey", OPT_INKEY, 's', "Input private key file"},
     {"peerkey", OPT_PEERKEY, 's', "Peer key file used in key derivation"},
     {"passin", OPT_PASSIN, 's', "Pass phrase source"},
     {"peerform", OPT_PEERFORM, 'E', "Peer key format - default PEM"},
@@ -112,7 +112,8 @@ OPTIONS pkeyutl_options[] = {
     {"pkeyopt", OPT_PKEYOPT, 's', "Public key options as opt:value"},
 #ifndef OPENSSL_NO_ENGINE
     {"engine", OPT_ENGINE, 's', "Use engine, possibly a hardware device"},
-    {"engine_impl", OPT_ENGINE_IMPL, '-', "Also use engine given by -engine for crypto operations"},
+    {"engine_impl", OPT_ENGINE_IMPL, '-',
+     "Also use engine given by -engine for crypto operations"},
 #endif
     {NULL}
 };

apps/progs.h

@@ -214,7 +214,6 @@ static FUNCTION functions[] = {
 #ifndef OPENSSL_NO_MD_GHOST94
     { FT_md, "md_ghost94", dgst_main},
 #endif
-    { FT_md, "sha", dgst_main},
     { FT_md, "sha1", dgst_main},
     { FT_md, "sha224", dgst_main},
     { FT_md, "sha256", dgst_main},

apps/progs.pl

@@ -72,7 +72,7 @@ foreach (@ARGV) {
 foreach (
 	"md2", "md4", "md5",
 	"md_ghost94",
-	"sha", "sha1", "sha224", "sha256", "sha384", "sha512",
+	"sha1", "sha224", "sha256", "sha384", "sha512",
 	"mdc2", "rmd160"
 ) {
         printf "#ifndef OPENSSL_NO_".uc($_)."\n" if ! /sha/;

doc/apps/dgst.pod

@@ -8,7 +8,7 @@ dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5 - mes
 
 B<openssl> B<dgst>
 [B<-help>]
-[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md4|-md5>]
+[B<-I<digest>>]
 [B<-c>]
 [B<-d>]
 [B<-hex>]
@@ -23,6 +23,8 @@ B<openssl> B<dgst>
 [B<-signature filename>]
 [B<-hmac key>]
 [B<-fips-fingerprint>]
+[B<-engine id>]
+[B<-engine_impl>]
 [B<file...>]
 
 B<openssl>
@@ -38,8 +40,8 @@ signatures using message digests.
 The generic name, B<dgst>, may be used with an option specifying the
 algorithm to be used.
 The default digest is I<sha256>.
-The digest name may also be used as the command name.
+A supported I<digest> name may also be used as the command name.
-To see the list of supported algorithms, use the <Ilist --digest-commands>
+To see the list of supported algorithms, use the I<list --digest-commands>
 command.
 
 =head1 OPTIONS
@@ -50,6 +52,11 @@ command.
 
 Print out a usage message.
 
+=item B<-I<digest>>
+
+Specifies name of a supported digest to be used. To see the list of
+supported digests, use the command I<list --digest-commands>.
+
 =item B<-c>
 
 print out the digest in two digit groups separated by colons, only relevant if
@@ -86,12 +93,6 @@ digitally sign the digest using the private key in "filename".
 Specifies the key format to sign digest with. The DER, PEM, P12,
 and ENGINE formats are supported.
 
-=item B<-engine id>
-
-Use engine B<id> for operations (including private key storage).
-This engine is not used as source for digest algorithms, unless it is
-also specified in the configuration file.
-
 =item B<-sigopt nm:v>
 
 Pass options to the signature algorithm during sign or verify operations.
@@ -162,6 +163,18 @@ all others.
 compute HMAC using a specific key
 for certain OpenSSL-FIPS operations.
 
+=item B<-engine id>
+
+Use engine B<id> for operations (including private key storage).
+This engine is not used as source for digest algorithms, unless it is
+also specified in the configuration file or B<-engine_impl> is also
+specified.
+
+=item B<-engine_impl>
+
+When used with the B<-engine> option, it specifies to also use
+engine B<id> for digest operations.
+
 =item B<file...>
 
 file or files to digest. If no files are specified then standard input is

doc/apps/openssl.pod

@@ -399,7 +399,7 @@ read the password from standard input.
 L<asn1parse(1)>, L<ca(1)>, L<config(5)>,
 L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
 L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
-L<enc(1)>, L<engine(1), L<gendsa(1)>, L<genpkey(1)>,
+L<enc(1)>, L<engine(1)>, L<gendsa(1)>, L<genpkey(1)>,
 L<genrsa(1)>, L<nseq(1)>, L<openssl(1)>,
 L<passwd(1)>,
 L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,

doc/apps/pkeyutl.pod

@@ -29,6 +29,7 @@ B<openssl> B<pkeyutl>
 [B<-hexdump>]
 [B<-asn1parse>]
 [B<-engine id>]
+[B<-engine_impl>]
 
 =head1 DESCRIPTION
 
@@ -53,13 +54,17 @@ if this option is not specified.
 specifies the output filename to write to or standard output by
 default.
 
+=item B<-sigfile file>
+
+Signature file, required for B<verify> operations only
+
 =item B<-inkey file>
 
 the input key file, by default it should be a private key.
 
 =item B<-keyform PEM|DER|ENGINE>
 
-the key format PEM, DER or ENGINE.
+the key format PEM, DER or ENGINE. Default is PEM.
 
 =item B<-passin arg>
 
@@ -73,15 +78,7 @@ the peer key file, used by key derivation (agreement) operations.
 
 =item B<-peerform PEM|DER|ENGINE>
 
-the peer key format PEM, DER or ENGINE.
+the peer key format PEM, DER or ENGINE. Default is PEM.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
-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<-pubin>
 
@@ -122,6 +119,10 @@ decrypt the input data using a private key.
 
 derive a shared secret using the peer key.
 
+=item B<-pkeyopt opt:value>
+
+Public key options specified as opt:value. See NOTES below for more details.
+
 =item B<-hexdump>
 
 hex dump the output data.
@@ -131,6 +132,19 @@ hex dump the output data.
 asn1parse the output data, this is useful when combined with the
 B<-verifyrecover> option when an ASN1 structure is signed.
 
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
+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<-engine_impl>
+
+When used with the B<-engine> option, it specifies to also use
+engine B<id> for crypto operations.
+
+
 =back
 
 =head1 NOTES