1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery{- OpenSSL::safe::output_do_not_edit_headers(); -} 3*b077aed3SPierre Pronchery 4*b077aed3SPierre Pronchery=head1 NAME 5*b077aed3SPierre Pronchery 6*b077aed3SPierre Proncheryopenssl-dgst - perform digest operations 7*b077aed3SPierre Pronchery 8*b077aed3SPierre Pronchery=head1 SYNOPSIS 9*b077aed3SPierre Pronchery 10*b077aed3SPierre ProncheryB<openssl> B<dgst>|I<digest> 11*b077aed3SPierre Pronchery[B<-I<digest>>] 12*b077aed3SPierre Pronchery[B<-list>] 13*b077aed3SPierre Pronchery[B<-help>] 14*b077aed3SPierre Pronchery[B<-c>] 15*b077aed3SPierre Pronchery[B<-d>] 16*b077aed3SPierre Pronchery[B<-debug>] 17*b077aed3SPierre Pronchery[B<-hex>] 18*b077aed3SPierre Pronchery[B<-binary>] 19*b077aed3SPierre Pronchery[B<-xoflen> I<length>] 20*b077aed3SPierre Pronchery[B<-r>] 21*b077aed3SPierre Pronchery[B<-out> I<filename>] 22*b077aed3SPierre Pronchery[B<-sign> I<filename>|I<uri>] 23*b077aed3SPierre Pronchery[B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>] 24*b077aed3SPierre Pronchery[B<-passin> I<arg>] 25*b077aed3SPierre Pronchery[B<-verify> I<filename>] 26*b077aed3SPierre Pronchery[B<-prverify> I<filename>] 27*b077aed3SPierre Pronchery[B<-signature> I<filename>] 28*b077aed3SPierre Pronchery[B<-sigopt> I<nm>:I<v>] 29*b077aed3SPierre Pronchery[B<-hmac> I<key>] 30*b077aed3SPierre Pronchery[B<-mac> I<alg>] 31*b077aed3SPierre Pronchery[B<-macopt> I<nm>:I<v>] 32*b077aed3SPierre Pronchery[B<-fips-fingerprint>] 33*b077aed3SPierre Pronchery{- $OpenSSL::safe::opt_engine_synopsis -}{- output_off() if $disabled{"deprecated-3.0"}; "" 34*b077aed3SPierre Pronchery-}[B<-engine_impl> I<id>]{- 35*b077aed3SPierre Pronchery output_on() if $disabled{"deprecated-3.0"}; "" -} 36*b077aed3SPierre Pronchery{- $OpenSSL::safe::opt_r_synopsis -} 37*b077aed3SPierre Pronchery{- $OpenSSL::safe::opt_provider_synopsis -} 38*b077aed3SPierre Pronchery[I<file> ...] 39*b077aed3SPierre Pronchery 40*b077aed3SPierre Pronchery=head1 DESCRIPTION 41*b077aed3SPierre Pronchery 42*b077aed3SPierre ProncheryThis command output the message digest of a supplied file or files 43*b077aed3SPierre Proncheryin hexadecimal, and also generates and verifies digital 44*b077aed3SPierre Proncherysignatures using message digests. 45*b077aed3SPierre Pronchery 46*b077aed3SPierre ProncheryThe generic name, B<openssl dgst>, may be used with an option specifying the 47*b077aed3SPierre Proncheryalgorithm to be used. 48*b077aed3SPierre ProncheryThe default digest is B<sha256>. 49*b077aed3SPierre ProncheryA supported I<digest> name may also be used as the sub-command name. 50*b077aed3SPierre ProncheryTo see the list of supported algorithms, use C<openssl list -digest-algorithms> 51*b077aed3SPierre Pronchery 52*b077aed3SPierre Pronchery=head1 OPTIONS 53*b077aed3SPierre Pronchery 54*b077aed3SPierre Pronchery=over 4 55*b077aed3SPierre Pronchery 56*b077aed3SPierre Pronchery=item B<-help> 57*b077aed3SPierre Pronchery 58*b077aed3SPierre ProncheryPrint out a usage message. 59*b077aed3SPierre Pronchery 60*b077aed3SPierre Pronchery=item B<-I<digest>> 61*b077aed3SPierre Pronchery 62*b077aed3SPierre ProncherySpecifies name of a supported digest to be used. See option B<-list> below : 63*b077aed3SPierre Pronchery 64*b077aed3SPierre Pronchery=item B<-list> 65*b077aed3SPierre Pronchery 66*b077aed3SPierre ProncheryPrints out a list of supported message digests. 67*b077aed3SPierre Pronchery 68*b077aed3SPierre Pronchery=item B<-c> 69*b077aed3SPierre Pronchery 70*b077aed3SPierre ProncheryPrint out the digest in two digit groups separated by colons, only relevant if 71*b077aed3SPierre Proncherythe B<-hex> option is given as well. 72*b077aed3SPierre Pronchery 73*b077aed3SPierre Pronchery=item B<-d>, B<-debug> 74*b077aed3SPierre Pronchery 75*b077aed3SPierre ProncheryPrint out BIO debugging information. 76*b077aed3SPierre Pronchery 77*b077aed3SPierre Pronchery=item B<-hex> 78*b077aed3SPierre Pronchery 79*b077aed3SPierre ProncheryDigest is to be output as a hex dump. This is the default case for a "normal" 80*b077aed3SPierre Proncherydigest as opposed to a digital signature. See NOTES below for digital 81*b077aed3SPierre Proncherysignatures using B<-hex>. 82*b077aed3SPierre Pronchery 83*b077aed3SPierre Pronchery=item B<-binary> 84*b077aed3SPierre Pronchery 85*b077aed3SPierre ProncheryOutput the digest or signature in binary form. 86*b077aed3SPierre Pronchery 87*b077aed3SPierre Pronchery=item B<-xoflen> I<length> 88*b077aed3SPierre Pronchery 89*b077aed3SPierre ProncherySet the output length for XOF algorithms, such as B<shake128> and B<shake256>. 90*b077aed3SPierre ProncheryThis option is not supported for signing operations. 91*b077aed3SPierre Pronchery 92*b077aed3SPierre ProncheryFor OpenSSL providers it is recommended to set this value for shake algorithms, 93*b077aed3SPierre Proncherysince the default values are set to only supply half of the maximum security 94*b077aed3SPierre Proncherystrength. 95*b077aed3SPierre Pronchery 96*b077aed3SPierre ProncheryFor backwards compatibility reasons the default xoflen length for B<shake128> is 97*b077aed3SPierre Pronchery16 (bytes) which results in a security strength of only 64 bits. To ensure the 98*b077aed3SPierre Proncherymaximum security strength of 128 bits, the xoflen should be set to at least 32. 99*b077aed3SPierre Pronchery 100*b077aed3SPierre ProncheryFor backwards compatibility reasons the default xoflen length for B<shake256> is 101*b077aed3SPierre Pronchery32 (bytes) which results in a security strength of only 128 bits. To ensure the 102*b077aed3SPierre Proncherymaximum security strength of 256 bits, the xoflen should be set to at least 64. 103*b077aed3SPierre Pronchery 104*b077aed3SPierre Pronchery=item B<-r> 105*b077aed3SPierre Pronchery 106*b077aed3SPierre Pronchery=for openssl foreign manual sha1sum(1) 107*b077aed3SPierre Pronchery 108*b077aed3SPierre ProncheryOutput the digest in the "coreutils" format, including newlines. 109*b077aed3SPierre ProncheryUsed by programs like L<sha1sum(1)>. 110*b077aed3SPierre Pronchery 111*b077aed3SPierre Pronchery=item B<-out> I<filename> 112*b077aed3SPierre Pronchery 113*b077aed3SPierre ProncheryFilename to output to, or standard output by default. 114*b077aed3SPierre Pronchery 115*b077aed3SPierre Pronchery=item B<-sign> I<filename>|I<uri> 116*b077aed3SPierre Pronchery 117*b077aed3SPierre ProncheryDigitally sign the digest using the given private key. Note this option 118*b077aed3SPierre Proncherydoes not support Ed25519 or Ed448 private keys. Use the L<openssl-pkeyutl(1)> 119*b077aed3SPierre Proncherycommand instead for this. 120*b077aed3SPierre Pronchery 121*b077aed3SPierre Pronchery=item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> 122*b077aed3SPierre Pronchery 123*b077aed3SPierre ProncheryThe format of the key to sign with; unspecified by default. 124*b077aed3SPierre ProncherySee L<openssl-format-options(1)> for details. 125*b077aed3SPierre Pronchery 126*b077aed3SPierre Pronchery=item B<-sigopt> I<nm>:I<v> 127*b077aed3SPierre Pronchery 128*b077aed3SPierre ProncheryPass options to the signature algorithm during sign or verify operations. 129*b077aed3SPierre ProncheryNames and values of these options are algorithm-specific. 130*b077aed3SPierre Pronchery 131*b077aed3SPierre Pronchery=item B<-passin> I<arg> 132*b077aed3SPierre Pronchery 133*b077aed3SPierre ProncheryThe private key password source. For more information about the format of I<arg> 134*b077aed3SPierre Proncherysee L<openssl-passphrase-options(1)>. 135*b077aed3SPierre Pronchery 136*b077aed3SPierre Pronchery=item B<-verify> I<filename> 137*b077aed3SPierre Pronchery 138*b077aed3SPierre ProncheryVerify the signature using the public key in "filename". 139*b077aed3SPierre ProncheryThe output is either "Verified OK" or "Verification Failure". 140*b077aed3SPierre Pronchery 141*b077aed3SPierre Pronchery=item B<-prverify> I<filename> 142*b077aed3SPierre Pronchery 143*b077aed3SPierre ProncheryVerify the signature using the private key in "filename". 144*b077aed3SPierre Pronchery 145*b077aed3SPierre Pronchery=item B<-signature> I<filename> 146*b077aed3SPierre Pronchery 147*b077aed3SPierre ProncheryThe actual signature to verify. 148*b077aed3SPierre Pronchery 149*b077aed3SPierre Pronchery=item B<-hmac> I<key> 150*b077aed3SPierre Pronchery 151*b077aed3SPierre ProncheryCreate a hashed MAC using "key". 152*b077aed3SPierre Pronchery 153*b077aed3SPierre ProncheryThe L<openssl-mac(1)> command should be preferred to using this command line 154*b077aed3SPierre Proncheryoption. 155*b077aed3SPierre Pronchery 156*b077aed3SPierre Pronchery=item B<-mac> I<alg> 157*b077aed3SPierre Pronchery 158*b077aed3SPierre ProncheryCreate MAC (keyed Message Authentication Code). The most popular MAC 159*b077aed3SPierre Proncheryalgorithm is HMAC (hash-based MAC), but there are other MAC algorithms 160*b077aed3SPierre Proncherywhich are not based on hash, for instance B<gost-mac> algorithm, 161*b077aed3SPierre Proncherysupported by the B<gost> engine. MAC keys and other options should be set 162*b077aed3SPierre Proncheryvia B<-macopt> parameter. 163*b077aed3SPierre Pronchery 164*b077aed3SPierre ProncheryThe L<openssl-mac(1)> command should be preferred to using this command line 165*b077aed3SPierre Proncheryoption. 166*b077aed3SPierre Pronchery 167*b077aed3SPierre Pronchery=item B<-macopt> I<nm>:I<v> 168*b077aed3SPierre Pronchery 169*b077aed3SPierre ProncheryPasses options to MAC algorithm, specified by B<-mac> key. 170*b077aed3SPierre ProncheryFollowing options are supported by both by B<HMAC> and B<gost-mac>: 171*b077aed3SPierre Pronchery 172*b077aed3SPierre Pronchery=over 4 173*b077aed3SPierre Pronchery 174*b077aed3SPierre Pronchery=item B<key>:I<string> 175*b077aed3SPierre Pronchery 176*b077aed3SPierre ProncherySpecifies MAC key as alphanumeric string (use if key contain printable 177*b077aed3SPierre Proncherycharacters only). String length must conform to any restrictions of 178*b077aed3SPierre Proncherythe MAC algorithm for example exactly 32 chars for gost-mac. 179*b077aed3SPierre Pronchery 180*b077aed3SPierre Pronchery=item B<hexkey>:I<string> 181*b077aed3SPierre Pronchery 182*b077aed3SPierre ProncherySpecifies MAC key in hexadecimal form (two hex digits per byte). 183*b077aed3SPierre ProncheryKey length must conform to any restrictions of the MAC algorithm 184*b077aed3SPierre Proncheryfor example exactly 32 chars for gost-mac. 185*b077aed3SPierre Pronchery 186*b077aed3SPierre Pronchery=back 187*b077aed3SPierre Pronchery 188*b077aed3SPierre ProncheryThe L<openssl-mac(1)> command should be preferred to using this command line 189*b077aed3SPierre Proncheryoption. 190*b077aed3SPierre Pronchery 191*b077aed3SPierre Pronchery=item B<-fips-fingerprint> 192*b077aed3SPierre Pronchery 193*b077aed3SPierre ProncheryCompute HMAC using a specific key for certain OpenSSL-FIPS operations. 194*b077aed3SPierre Pronchery 195*b077aed3SPierre Pronchery{- $OpenSSL::safe::opt_r_item -} 196*b077aed3SPierre Pronchery 197*b077aed3SPierre Pronchery{- $OpenSSL::safe::opt_engine_item -} 198*b077aed3SPierre Pronchery{- output_off() if $disabled{"deprecated-3.0"}; "" -} 199*b077aed3SPierre ProncheryThe engine is not used for digests unless the B<-engine_impl> option is 200*b077aed3SPierre Proncheryused or it is configured to do so, see L<config(5)/Engine Configuration Module>. 201*b077aed3SPierre Pronchery 202*b077aed3SPierre Pronchery=item B<-engine_impl> I<id> 203*b077aed3SPierre Pronchery 204*b077aed3SPierre ProncheryWhen used with the B<-engine> option, it specifies to also use 205*b077aed3SPierre Proncheryengine I<id> for digest operations. 206*b077aed3SPierre Pronchery 207*b077aed3SPierre Pronchery{- output_on() if $disabled{"deprecated-3.0"}; "" -} 208*b077aed3SPierre Pronchery{- $OpenSSL::safe::opt_provider_item -} 209*b077aed3SPierre Pronchery 210*b077aed3SPierre Pronchery=item I<file> ... 211*b077aed3SPierre Pronchery 212*b077aed3SPierre ProncheryFile or files to digest. If no files are specified then standard input is 213*b077aed3SPierre Proncheryused. 214*b077aed3SPierre Pronchery 215*b077aed3SPierre Pronchery=back 216*b077aed3SPierre Pronchery 217*b077aed3SPierre Pronchery 218*b077aed3SPierre Pronchery=head1 EXAMPLES 219*b077aed3SPierre Pronchery 220*b077aed3SPierre ProncheryTo create a hex-encoded message digest of a file: 221*b077aed3SPierre Pronchery 222*b077aed3SPierre Pronchery openssl dgst -md5 -hex file.txt 223*b077aed3SPierre Pronchery or 224*b077aed3SPierre Pronchery openssl md5 file.txt 225*b077aed3SPierre Pronchery 226*b077aed3SPierre ProncheryTo sign a file using SHA-256 with binary file output: 227*b077aed3SPierre Pronchery 228*b077aed3SPierre Pronchery openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt 229*b077aed3SPierre Pronchery or 230*b077aed3SPierre Pronchery openssl sha256 -sign privatekey.pem -out signature.sign file.txt 231*b077aed3SPierre Pronchery 232*b077aed3SPierre ProncheryTo verify a signature: 233*b077aed3SPierre Pronchery 234*b077aed3SPierre Pronchery openssl dgst -sha256 -verify publickey.pem \ 235*b077aed3SPierre Pronchery -signature signature.sign \ 236*b077aed3SPierre Pronchery file.txt 237*b077aed3SPierre Pronchery 238*b077aed3SPierre Pronchery 239*b077aed3SPierre Pronchery=head1 NOTES 240*b077aed3SPierre Pronchery 241*b077aed3SPierre ProncheryThe digest mechanisms that are available will depend on the options 242*b077aed3SPierre Proncheryused when building OpenSSL. 243*b077aed3SPierre ProncheryThe C<openssl list -digest-algorithms> command can be used to list them. 244*b077aed3SPierre Pronchery 245*b077aed3SPierre ProncheryNew or agile applications should use probably use SHA-256. Other digests, 246*b077aed3SPierre Proncheryparticularly SHA-1 and MD5, are still widely used for interoperating 247*b077aed3SPierre Proncherywith existing formats and protocols. 248*b077aed3SPierre Pronchery 249*b077aed3SPierre ProncheryWhen signing a file, this command will automatically determine the algorithm 250*b077aed3SPierre Pronchery(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. 251*b077aed3SPierre ProncheryWhen verifying signatures, it only handles the RSA, DSA, or ECDSA signature 252*b077aed3SPierre Proncheryitself, not the related data to identify the signer and algorithm used in 253*b077aed3SPierre Proncheryformats such as x.509, CMS, and S/MIME. 254*b077aed3SPierre Pronchery 255*b077aed3SPierre ProncheryA source of random numbers is required for certain signing algorithms, in 256*b077aed3SPierre Proncheryparticular ECDSA and DSA. 257*b077aed3SPierre Pronchery 258*b077aed3SPierre ProncheryThe signing and verify options should only be used if a single file is 259*b077aed3SPierre Proncherybeing signed or verified. 260*b077aed3SPierre Pronchery 261*b077aed3SPierre ProncheryHex signatures cannot be verified using B<openssl>. Instead, use "xxd -r" 262*b077aed3SPierre Proncheryor similar program to transform the hex signature into a binary signature 263*b077aed3SPierre Proncheryprior to verification. 264*b077aed3SPierre Pronchery 265*b077aed3SPierre ProncheryThe L<openssl-mac(1)> command is preferred over the B<-hmac>, B<-mac> and 266*b077aed3SPierre ProncheryB<-macopt> command line options. 267*b077aed3SPierre Pronchery 268*b077aed3SPierre Pronchery=head1 SEE ALSO 269*b077aed3SPierre Pronchery 270*b077aed3SPierre ProncheryL<openssl-mac(1)> 271*b077aed3SPierre Pronchery 272*b077aed3SPierre Pronchery=head1 HISTORY 273*b077aed3SPierre Pronchery 274*b077aed3SPierre ProncheryThe default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0. 275*b077aed3SPierre ProncheryThe FIPS-related options were removed in OpenSSL 1.1.0. 276*b077aed3SPierre Pronchery 277*b077aed3SPierre ProncheryThe B<-engine> and B<-engine_impl> options were deprecated in OpenSSL 3.0. 278*b077aed3SPierre Pronchery 279*b077aed3SPierre Pronchery=head1 COPYRIGHT 280*b077aed3SPierre Pronchery 281*b077aed3SPierre ProncheryCopyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. 282*b077aed3SPierre Pronchery 283*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 284*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 285*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 286*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 287*b077aed3SPierre Pronchery 288*b077aed3SPierre Pronchery=cut 289