dgst.pod revision 273149
159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 5273149Sjkimdgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests 659191Skris 759191Skris=head1 SYNOPSIS 859191Skris 959191SkrisB<openssl> B<dgst> 10273149Sjkim[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>] 1159191Skris[B<-c>] 1259191Skris[B<-d>] 1368651Skris[B<-hex>] 1468651Skris[B<-binary>] 15273149Sjkim[B<-r>] 1668651Skris[B<-out filename>] 1768651Skris[B<-sign filename>] 18238405Sjkim[B<-keyform arg>] 19160814Ssimon[B<-passin arg>] 2068651Skris[B<-verify filename>] 2168651Skris[B<-prverify filename>] 2268651Skris[B<-signature filename>] 23194206Ssimon[B<-hmac key>] 24273149Sjkim[B<-non-fips-allow>] 25273149Sjkim[B<-fips-fingerprint>] 2659191Skris[B<file...>] 2759191Skris 28273149SjkimB<openssl> 29273149Sjkim[I<digest>] 30273149Sjkim[B<...>] 3159191Skris 3259191Skris=head1 DESCRIPTION 3359191Skris 3468651SkrisThe digest functions output the message digest of a supplied file or files 35273149Sjkimin hexadecimal. The digest functions also generate and verify digital 36273149Sjkimsignatures using message digests. 3759191Skris 3859191Skris=head1 OPTIONS 3959191Skris 4059191Skris=over 4 4159191Skris 4259191Skris=item B<-c> 4359191Skris 4468651Skrisprint out the digest in two digit groups separated by colons, only relevant if 4568651SkrisB<hex> format output is used. 4659191Skris 4759191Skris=item B<-d> 4859191Skris 4959191Skrisprint out BIO debugging information. 5059191Skris 5168651Skris=item B<-hex> 5268651Skris 5368651Skrisdigest is to be output as a hex dump. This is the default case for a "normal" 54273149Sjkimdigest as opposed to a digital signature. See NOTES below for digital 55273149Sjkimsignatures using B<-hex>. 5668651Skris 5768651Skris=item B<-binary> 5868651Skris 5968651Skrisoutput the digest or signature in binary form. 6068651Skris 61273149Sjkim=item B<-r> 62273149Sjkim 63273149Sjkimoutput the digest in the "coreutils" format used by programs like B<sha1sum>. 64273149Sjkim 6568651Skris=item B<-out filename> 6668651Skris 6768651Skrisfilename to output to, or standard output by default. 6868651Skris 6968651Skris=item B<-sign filename> 7068651Skris 7168651Skrisdigitally sign the digest using the private key in "filename". 7268651Skris 73238405Sjkim=item B<-keyform arg> 74238405Sjkim 75273149SjkimSpecifies the key format to sign digest with. The DER, PEM, P12, 76273149Sjkimand ENGINE formats are supported. 77238405Sjkim 78238405Sjkim=item B<-engine id> 79238405Sjkim 80238405SjkimUse engine B<id> for operations (including private key storage). 81238405SjkimThis engine is not used as source for digest algorithms, unless it is 82238405Sjkimalso specified in the configuration file. 83238405Sjkim 84238405Sjkim=item B<-sigopt nm:v> 85238405Sjkim 86238405SjkimPass options to the signature algorithm during sign or verify operations. 87238405SjkimNames and values of these options are algorithm-specific. 88238405Sjkim 89238405Sjkim 90160814Ssimon=item B<-passin arg> 91160814Ssimon 92160814Ssimonthe private key password source. For more information about the format of B<arg> 93160814Ssimonsee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 94160814Ssimon 9568651Skris=item B<-verify filename> 9668651Skris 97237658Sjkimverify the signature using the public key in "filename". 9868651SkrisThe output is either "Verification OK" or "Verification Failure". 9968651Skris 10068651Skris=item B<-prverify filename> 10168651Skris 102246771Sjkimverify the signature using the private key in "filename". 10368651Skris 10468651Skris=item B<-signature filename> 10568651Skris 10668651Skristhe actual signature to verify. 10768651Skris 108194206Ssimon=item B<-hmac key> 109194206Ssimon 110194206Ssimoncreate a hashed MAC using "key". 111194206Ssimon 112238405Sjkim=item B<-mac alg> 113238405Sjkim 114238405Sjkimcreate MAC (keyed Message Authentication Code). The most popular MAC 115238405Sjkimalgorithm is HMAC (hash-based MAC), but there are other MAC algorithms 116238405Sjkimwhich are not based on hash, for instance B<gost-mac> algorithm, 117238405Sjkimsupported by B<ccgost> engine. MAC keys and other options should be set 118238405Sjkimvia B<-macopt> parameter. 119238405Sjkim 120238405Sjkim=item B<-macopt nm:v> 121238405Sjkim 122238405SjkimPasses options to MAC algorithm, specified by B<-mac> key. 123238405SjkimFollowing options are supported by both by B<HMAC> and B<gost-mac>: 124238405Sjkim 125238405Sjkim=over 8 126238405Sjkim 127238405Sjkim=item B<key:string> 128273149Sjkim 129238405SjkimSpecifies MAC key as alphnumeric string (use if key contain printable 130238405Sjkimcharacters only). String length must conform to any restrictions of 131238405Sjkimthe MAC algorithm for example exactly 32 chars for gost-mac. 132238405Sjkim 133238405Sjkim=item B<hexkey:string> 134238405Sjkim 135238405SjkimSpecifies MAC key in hexadecimal form (two hex digits per byte). 136238405SjkimKey length must conform to any restrictions of the MAC algorithm 137238405Sjkimfor example exactly 32 chars for gost-mac. 138238405Sjkim 139238405Sjkim=back 140238405Sjkim 14168651Skris=item B<-rand file(s)> 14268651Skris 14368651Skrisa file or files containing random data used to seed the random number 14468651Skrisgenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 14568651SkrisMultiple files can be specified separated by a OS-dependent character. 14668651SkrisThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 14768651Skrisall others. 14868651Skris 149273149Sjkim=item B<-non-fips-allow> 150273149Sjkim 151273149Sjkimenable use of non-FIPS algorithms such as MD5 even in FIPS mode. 152273149Sjkim 153273149Sjkim=item B<-fips-fingerprint> 154273149Sjkim 155273149Sjkimcompute HMAC using a specific key 156273149Sjkimfor certain OpenSSL-FIPS operations. 157273149Sjkim 15859191Skris=item B<file...> 15959191Skris 16059191Skrisfile or files to digest. If no files are specified then standard input is 16159191Skrisused. 16259191Skris 16359191Skris=back 16459191Skris 165273149Sjkim 166273149Sjkim=head1 EXAMPLES 167273149Sjkim 168273149SjkimTo create a hex-encoded message digest of a file: 169273149Sjkim openssl dgst -md5 -hex file.txt 170273149Sjkim 171273149SjkimTo sign a file using SHA-256 with binary file output: 172273149Sjkim openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt 173273149Sjkim 174273149SjkimTo verify a signature: 175273149Sjkim openssl dgst -sha256 -verify publickey.pem \ 176273149Sjkim -signature signature.sign \ 177273149Sjkim file.txt 178273149Sjkim 179273149Sjkim 18059191Skris=head1 NOTES 18159191Skris 18259191SkrisThe digest of choice for all new applications is SHA1. Other digests are 18359191Skrishowever still widely used. 18459191Skris 185273149SjkimWhen signing a file, B<dgst> will automatically determine the algorithm 186273149Sjkim(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. 187273149SjkimWhen verifying signatures, it only handles the RSA, DSA, or ECDSA signature 188273149Sjkimitself, not the related data to identify the signer and algorithm used in 189273149Sjkimformats such as x.509, CMS, and S/MIME. 19068651Skris 19168651SkrisA source of random numbers is required for certain signing algorithms, in 192273149Sjkimparticular ECDSA and DSA. 19368651Skris 19468651SkrisThe signing and verify options should only be used if a single file is 19568651Skrisbeing signed or verified. 19668651Skris 197273149SjkimHex signatures cannot be verified using B<openssl>. Instead, use "xxd -r" 198273149Sjkimor similar program to transform the hex signature into a binary signature 199273149Sjkimprior to verification. 200273149Sjkim 201273149Sjkim 20259191Skris=cut 203