X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Fdgst.pod;h=b27bb946b1b2e346e914e44346d4f51f4056c1e6;hp=908cd2a6d657db9906ef6af19817eb6dc91ff3d7;hb=3d411057a5e28530fffc40b257698f453c89aa87;hpb=3d11b8f89617edc81d01329dbb5bf134fcda3303 diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod index 908cd2a6d6..b27bb946b1 100644 --- a/doc/apps/dgst.pod +++ b/doc/apps/dgst.pod @@ -2,34 +2,39 @@ =head1 NAME -dgst, md5, md4, md2, sha1, sha, mdc2, ripemd160 - message digests +dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests =head1 SYNOPSIS B B -[B<-md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1>] +[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>] [B<-c>] [B<-d>] [B<-hex>] [B<-binary>] +[B<-r>] +[B<-non-fips-allow>] [B<-out filename>] [B<-sign filename>] +[B<-keyform arg>] [B<-passin arg>] [B<-verify filename>] [B<-prverify filename>] [B<-signature filename>] [B<-hmac key>] +[B<-non-fips-allow>] +[B<-fips-fingerprint>] [B] -[B] -[B<-c>] -[B<-d>] -[B] +B +[I] +[B<...>] =head1 DESCRIPTION The digest functions output the message digest of a supplied file or files -in hexadecimal form. They can also be used for digital signing and verification. +in hexadecimal. The digest functions also generate and verify digital +signatures using message digests. =head1 OPTIONS @@ -47,12 +52,22 @@ print out BIO debugging information. =item B<-hex> digest is to be output as a hex dump. This is the default case for a "normal" -digest as opposed to a digital signature. +digest as opposed to a digital signature. See NOTES below for digital +signatures using B<-hex>. =item B<-binary> output the digest or signature in binary form. +=item B<-r> + +output the digest in the "coreutils" format used by programs like B. + +=item B<-non-fips-allow> + +Allow use of non FIPS digest when in FIPS mode. This has no effect when not in +FIPS mode. + =item B<-out filename> filename to output to, or standard output by default. @@ -61,6 +76,23 @@ filename to output to, or standard output by default. digitally sign the digest using the private key in "filename". +=item B<-keyform arg> + +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. +Names and values of these options are algorithm-specific. + + =item B<-passin arg> the private key password source. For more information about the format of B @@ -83,6 +115,35 @@ the actual signature to verify. create a hashed MAC using "key". +=item B<-mac alg> + +create MAC (keyed Message Authentication Code). The most popular MAC +algorithm is HMAC (hash-based MAC), but there are other MAC algorithms +which are not based on hash, for instance B algorithm, +supported by B engine. MAC keys and other options should be set +via B<-macopt> parameter. + +=item B<-macopt nm:v> + +Passes options to MAC algorithm, specified by B<-mac> key. +Following options are supported by both by B and B: + +=over 8 + +=item B + +Specifies MAC key as alphnumeric string (use if key contain printable +characters only). String length must conform to any restrictions of +the MAC algorithm for example exactly 32 chars for gost-mac. + +=item B + +Specifies MAC key in hexadecimal form (two hex digits per byte). +Key length must conform to any restrictions of the MAC algorithm +for example exactly 32 chars for gost-mac. + +=back + =item B<-rand file(s)> a file or files containing random data used to seed the random number @@ -91,6 +152,15 @@ Multiple files can be specified separated by a OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. +=item B<-non-fips-allow> + +enable use of non-FIPS algorithms such as MD5 even in FIPS mode. + +=item B<-fips-fingerprint> + +compute HMAC using a specific key +for certain OpenSSL-FIPS operations. + =item B file or files to digest. If no files are specified then standard input is @@ -98,18 +168,41 @@ used. =back + +=head1 EXAMPLES + +To create a hex-encoded message digest of a file: + openssl dgst -md5 -hex file.txt + +To sign a file using SHA-256 with binary file output: + openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt + +To verify a signature: + openssl dgst -sha256 -verify publickey.pem \ + -signature signature.sign \ + file.txt + + =head1 NOTES The digest of choice for all new applications is SHA1. Other digests are however still widely used. -If you wish to sign or verify data using the DSA algorithm then the dss1 -digest must be used. +When signing a file, B will automatically determine the algorithm +(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. +When verifying signatures, it only handles the RSA, DSA, or ECDSA signature +itself, not the related data to identify the signer and algorithm used in +formats such as x.509, CMS, and S/MIME. A source of random numbers is required for certain signing algorithms, in -particular DSA. +particular ECDSA and DSA. The signing and verify options should only be used if a single file is being signed or verified. +Hex signatures cannot be verified using B. Instead, use "xxd -r" +or similar program to transform the hex signature into a binary signature +prior to verification. + + =cut