From a173a7ee3f51af71c27490247f9a65ff03553e2c Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Sun, 7 Feb 2016 23:14:12 -0500 Subject: [PATCH] more doc fixes MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Tim Hudson --- apps/dgst.c | 13 ++++++++----- apps/pkeyutl.c | 17 +++++++++-------- apps/progs.h | 1 - apps/progs.pl | 2 +- doc/apps/dgst.pod | 33 +++++++++++++++++++++++---------- doc/apps/openssl.pod | 2 +- doc/apps/pkeyutl.pod | 34 ++++++++++++++++++++++++---------- 7 files changed, 66 insertions(+), 36 deletions(-) diff --git a/apps/dgst.c b/apps/dgst.c index 5d25c58e32..7fa535197e 100644 --- a/apps/dgst.c +++ b/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, '-'}, - {"fips-fingerprint", OPT_FIPS_FINGERPRINT, '-'}, + {"debug", OPT_DEBUG, '-', "Print debug info"}, + {"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} }; diff --git a/apps/pkeyutl.c b/apps/pkeyutl.c index 8704fd9849..5a2827b399 100644 --- a/apps/pkeyutl.c +++ b/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"}, - {"out", OPT_OUT, '>', "Output file"}, + {"in", OPT_IN, '<', "Input file - default stdin"}, + {"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"}, - {"encrypt", OPT_ENCRYPT, '-', "Encrypt with public key"}, - {"decrypt", OPT_DECRYPT, '-', "Decrypt with private key"}, + {"rev", OPT_REV, '-', "Reverse the order of the input buffer"}, + {"encrypt", OPT_ENCRYPT, '-', "Encrypt input data with public 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} }; diff --git a/apps/progs.h b/apps/progs.h index f3eaf2ac42..86d9ab87f4 100644 --- a/apps/progs.h +++ b/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}, diff --git a/apps/progs.pl b/apps/progs.pl index 4ffa1f1e79..40053a7306 100644 --- a/apps/progs.pl +++ b/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/; diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod index 25794c13bb..1c595dcf74 100644 --- a/doc/apps/dgst.pod +++ b/doc/apps/dgst.pod @@ -6,9 +6,9 @@ dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5 - mes =head1 SYNOPSIS -B B +B B [B<-help>] -[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md4|-md5>] +[B<-I>] [B<-c>] [B<-d>] [B<-hex>] @@ -23,6 +23,8 @@ B B [B<-signature filename>] [B<-hmac key>] [B<-fips-fingerprint>] +[B<-engine id>] +[B<-engine_impl>] [B] B @@ -38,8 +40,8 @@ signatures using message digests. The generic name, B, may be used with an option specifying the algorithm to be used. The default digest is I. -The digest name may also be used as the command name. -To see the list of supported algorithms, use the +A supported I name may also be used as the command name. +To see the list of supported algorithms, use the I command. =head1 OPTIONS @@ -50,6 +52,11 @@ command. Print out a usage message. +=item B<-I> + +Specifies name of a supported digest to be used. To see the list of +supported digests, use the command I. + =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 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 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 for digest operations. + =item B file or files to digest. If no files are specified then standard input is diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod index f7a0d441df..717550d9cf 100644 --- a/doc/apps/openssl.pod +++ b/doc/apps/openssl.pod @@ -399,7 +399,7 @@ read the password from standard input. L, L, L, L, L, L, L, L, L, -L, L, L, +L, L, L, L, L, L, L, L, L, L, L, diff --git a/doc/apps/pkeyutl.pod b/doc/apps/pkeyutl.pod index bd2b6e35b0..a2da2558f6 100644 --- a/doc/apps/pkeyutl.pod +++ b/doc/apps/pkeyutl.pod @@ -29,6 +29,7 @@ B B [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 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. - -=item B<-engine id> - -specifying an engine (by its unique B string) will cause B -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. - +the peer key format PEM, DER or ENGINE. Default is PEM. =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 string) will cause B +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 for crypto operations. + + =back =head1 NOTES -- 2.25.1