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