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