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