Debian Codegraph @

upstream/debian-unstable/man1/openssl-dgst.1ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL-DGST 1SSL"
58 .TH OPENSSL-DGST 1SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 openssl\-dgst \- perform digest operations
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 \&\fBopenssl\fR \fBdgst\fR|\fIdigest\fR
68 [\fB\-\fR\f(BIdigest\fR]
69 [\fB\-list\fR]
70 [\fB\-help\fR]
71 [\fB\-c\fR]
72 [\fB\-d\fR]
73 [\fB\-debug\fR]
74 [\fB\-hex\fR]
75 [\fB\-binary\fR]
76 [\fB\-xoflen\fR \fIlength\fR]
77 [\fB\-r\fR]
78 [\fB\-out\fR \fIfilename\fR]
79 [\fB\-sign\fR \fIfilename\fR|\fIuri\fR]
80 [\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR]
81 [\fB\-passin\fR \fIarg\fR]
82 [\fB\-verify\fR \fIfilename\fR]
83 [\fB\-prverify\fR \fIfilename\fR]
84 [\fB\-signature\fR \fIfilename\fR]
85 [\fB\-sigopt\fR \fInm\fR:\fIv\fR]
86 [\fB\-hmac\fR \fIkey\fR]
87 [\fB\-mac\fR \fIalg\fR]
88 [\fB\-macopt\fR \fInm\fR:\fIv\fR]
89 [\fB\-fips\-fingerprint\fR]
90 [\fB\-engine\fR \fIid\fR]
91 [\fB\-engine_impl\fR \fIid\fR]
92 [\fB\-rand\fR \fIfiles\fR]
93 [\fB\-writerand\fR \fIfile\fR]
94 [\fB\-provider\fR \fIname\fR]
95 [\fB\-provider\-path\fR \fIpath\fR]
96 [\fB\-provparam\fR \fI[name:]key=value\fR]
97 [\fB\-propquery\fR \fIpropq\fR]
98 [\fIfile\fR ...]
99 .SH DESCRIPTION
100 .IX Header "DESCRIPTION"
101 This command output the message digest of a supplied file or files
102 in hexadecimal, and also generates and verifies digital
103 signatures using message digests.
104 .PP
105 The generic name, \fBopenssl dgst\fR, may be used with an option specifying the
106 algorithm to be used.
107 The default digest is \fBsha256\fR.
108 A supported \fIdigest\fR name may also be used as the sub-command name.
109 To see the list of supported algorithms, use \f(CW\*(C`openssl list \-digest\-algorithms\*(C'\fR
110 .SH OPTIONS
111 .IX Header "OPTIONS"
112 .IP \fB\-help\fR 4
113 .IX Item "-help"
114 Print out a usage message.
115 .IP \fB\-\fR\f(BIdigest\fR 4
116 .IX Item "-digest"
117 Specifies name of a supported digest to be used. See option \fB\-list\fR below :
118 .IP \fB\-list\fR 4
119 .IX Item "-list"
120 Prints out a list of supported message digests.
121 .IP \fB\-c\fR 4
122 .IX Item "-c"
123 Print out the digest in two digit groups separated by colons, only relevant if
124 the \fB\-hex\fR option is given as well.
125 .IP "\fB\-d\fR, \fB\-debug\fR" 4
126 .IX Item "-d, -debug"
127 Print out BIO debugging information.
128 .IP \fB\-hex\fR 4
129 .IX Item "-hex"
130 Digest is to be output as a hex dump. This is the default case for a "normal"
131 digest as opposed to a digital signature. See NOTES below for digital
132 signatures using \fB\-hex\fR.
133 .IP \fB\-binary\fR 4
134 .IX Item "-binary"
135 Output the digest or signature in binary form.
136 .IP "\fB\-xoflen\fR \fIlength\fR" 4
137 .IX Item "-xoflen length"
138 Set the output length for XOF algorithms, such as \fBshake128\fR and \fBshake256\fR.
139 This option is not supported for signing operations.
140 .Sp
141 For OpenSSL providers it is required to set this value for shake algorithms,
142 since the previous default values were only set to supply half of the maximum
143 security strength.
144 .Sp
145 To ensure the maximum security strength of 128 bits, the xoflen for \fBshake128\fR
146 should be set to at least 32 (bytes). For compatibility with previous versions
147 of OpenSSL, it may be set to 16, resulting in a security strength of only 64
148 bits.
149 .Sp
150 To ensure the maximum security strength of 256 bits, the xoflen for \fBshake256\fR
151 should be set to at least 64 (bytes). For compatibility with previous versions
152 of OpenSSL, it may be set to 32, resulting in a security strength of only 128
153 bits.
154 .IP \fB\-r\fR 4
155 .IX Item "-r"
156 Output the digest in the "coreutils" format, including newlines.
157 Used by programs like \fBsha1sum\fR\|(1).
158 .IP "\fB\-out\fR \fIfilename\fR" 4
159 .IX Item "-out filename"
160 Filename to output to, or standard output by default.
161 .IP "\fB\-sign\fR \fIfilename\fR|\fIuri\fR" 4
162 .IX Item "-sign filename|uri"
163 Digitally sign the digest using the given private key.
164 .Sp
165 Note that for algorithms that only support one-shot signing
166 (such as Ed25519, ED448, ML\-DSA\-44, ML\-DSA\-65 andML\-DSA\-87) the digest must not
167 be set. For these algorithms the input is buffered (and not digested) before
168 signing. For these algorithms, if the input is larger than 16MB an error
169 will occur.
170 .IP "\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR" 4
171 .IX Item "-keyform DER|PEM|P12|ENGINE"
172 The format of the key to sign with; unspecified by default.
173 See \fBopenssl\-format\-options\fR\|(1) for details.
174 .IP "\fB\-sigopt\fR \fInm\fR:\fIv\fR" 4
175 .IX Item "-sigopt nm:v"
176 Pass options to the signature algorithm during sign or verify operations.
177 Names and values of these options are algorithm-specific and documented
178 in "Signature parameters" in \fBprovider\-signature\fR\|(7).
179 .IP "\fB\-passin\fR \fIarg\fR" 4
180 .IX Item "-passin arg"
181 The private key password source. For more information about the format of \fIarg\fR
182 see \fBopenssl\-passphrase\-options\fR\|(1).
183 .IP "\fB\-verify\fR \fIfilename\fR" 4
184 .IX Item "-verify filename"
185 Verify the signature using the public key in "filename".
186 The output is either "Verified OK" or "Verification Failure".
187 .IP "\fB\-prverify\fR \fIfilename\fR" 4
188 .IX Item "-prverify filename"
189 Verify the signature using the private key in "filename".
190 .IP "\fB\-signature\fR \fIfilename\fR" 4
191 .IX Item "-signature filename"
192 The actual signature to verify.
193 .IP "\fB\-hmac\fR \fIkey\fR" 4
194 .IX Item "-hmac key"
195 Create a hashed MAC using "key".
196 .Sp
197 The \fBopenssl\-mac\fR\|(1) command should be preferred to using this command line
198 option.
199 .IP "\fB\-mac\fR \fIalg\fR" 4
200 .IX Item "-mac alg"
201 Create MAC (keyed Message Authentication Code). The most popular MAC
202 algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
203 which are not based on hash, for instance \fBgost-mac\fR algorithm,
204 supported by the \fBgost\fR engine. MAC keys and other options should be set
205 via \fB\-macopt\fR parameter.
206 .Sp
207 The \fBopenssl\-mac\fR\|(1) command should be preferred to using this command line
208 option.
209 .IP "\fB\-macopt\fR \fInm\fR:\fIv\fR" 4
210 .IX Item "-macopt nm:v"
211 Passes options to MAC algorithm, specified by \fB\-mac\fR key.
212 Following options are supported by both by \fBHMAC\fR and \fBgost-mac\fR:
213 .RS 4
214 .IP \fBkey\fR:\fIstring\fR 4
215 .IX Item "key:string"
216 Specifies MAC key as alphanumeric string (use if key contain printable
217 characters only). String length must conform to any restrictions of
218 the MAC algorithm for example exactly 32 chars for gost-mac.
219 .IP \fBhexkey\fR:\fIstring\fR 4
220 .IX Item "hexkey:string"
221 Specifies MAC key in hexadecimal form (two hex digits per byte).
222 Key length must conform to any restrictions of the MAC algorithm
223 for example exactly 32 chars for gost-mac.
224 .RE
225 .RS 4
226 .Sp
227 The \fBopenssl\-mac\fR\|(1) command should be preferred to using this command line
228 option.
229 .RE
230 .IP \fB\-fips\-fingerprint\fR 4
231 .IX Item "-fips-fingerprint"
232 Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
233 .IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4
234 .IX Item "-rand files, -writerand file"
235 See "Random State Options" in \fBopenssl\fR\|(1) for details.
236 .IP "\fB\-engine\fR \fIid\fR" 4
237 .IX Item "-engine id"
238 See "Engine Options" in \fBopenssl\fR\|(1).
239 This option is deprecated.
240 .Sp
241 The engine is not used for digests unless the \fB\-engine_impl\fR option is
242 used or it is configured to do so, see "Engine Configuration Module" in \fBconfig\fR\|(5).
243 .IP "\fB\-engine_impl\fR \fIid\fR" 4
244 .IX Item "-engine_impl id"
245 When used with the \fB\-engine\fR option, it specifies to also use
246 engine \fIid\fR for digest operations.
247 .IP "\fB\-provider\fR \fIname\fR" 4
248 .IX Item "-provider name"
249 .PD 0
250 .IP "\fB\-provider\-path\fR \fIpath\fR" 4
251 .IX Item "-provider-path path"
252 .IP "\fB\-provparam\fR \fI[name:]key=value\fR" 4
253 .IX Item "-provparam [name:]key=value"
254 .IP "\fB\-propquery\fR \fIpropq\fR" 4
255 .IX Item "-propquery propq"
256 .PD
257 See "Provider Options" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7).
258 .IP "\fIfile\fR ..." 4
259 .IX Item "file ..."
260 File or files to digest. If no files are specified then standard input is
261 used.
262 .SH EXAMPLES
263 .IX Header "EXAMPLES"
264 To create a hex-encoded message digest of a file:
265 .PP
266 .Vb 3
267 \& openssl dgst \-md5 \-hex file.txt
268 \& or
269 \& openssl md5 file.txt
270 .Ve
271 .PP
272 To sign a file using SHA\-256 with binary file output:
273 .PP
274 .Vb 3
275 \& openssl dgst \-sha256 \-sign privatekey.pem \-out signature.sign file.txt
276 \& or
277 \& openssl sha256 \-sign privatekey.pem \-out signature.sign file.txt
278 .Ve
279 .PP
280 To verify a signature:
281 .PP
282 .Vb 3
283 \& openssl dgst \-sha256 \-verify publickey.pem \e
284 \& \-signature signature.sign \e
285 \& file.txt
286 .Ve
287 .SH NOTES
288 .IX Header "NOTES"
289 The digest mechanisms that are available will depend on the options
290 used when building OpenSSL.
291 The \f(CW\*(C`openssl list \-digest\-algorithms\*(C'\fR command can be used to list them.
292 .PP
293 New or agile applications should use probably use SHA\-256. Other digests,
294 particularly SHA\-1 and MD5, are still widely used for interoperating
295 with existing formats and protocols.
296 .PP
297 When signing a file, this command will automatically determine the algorithm
298 (RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
299 When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
300 itself, not the related data to identify the signer and algorithm used in
301 formats such as x.509, CMS, and S/MIME.
302 .PP
303 A source of random numbers is required for certain signing algorithms, in
304 particular ECDSA and DSA.
305 .PP
306 The signing and verify options should only be used if a single file is
307 being signed or verified.
308 .PP
309 Hex signatures cannot be verified using \fBopenssl\fR. Instead, use "xxd \-r"
310 or similar program to transform the hex signature into a binary signature
311 prior to verification.
312 .PP
313 The \fBopenssl\-mac\fR\|(1) command is preferred over the \fB\-hmac\fR, \fB\-mac\fR and
314 \&\fB\-macopt\fR command line options.
315 .SH "SEE ALSO"
316 .IX Header "SEE ALSO"
317 \&\fBopenssl\-mac\fR\|(1)
318 .SH HISTORY
319 .IX Header "HISTORY"
320 The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0.
321 The FIPS-related options were removed in OpenSSL 1.1.0.
322 .PP
323 The \fB\-engine\fR and \fB\-engine_impl\fR options were deprecated in OpenSSL 3.0.
324 .SH COPYRIGHT
325 .IX Header "COPYRIGHT"
326 Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved.
327 .PP
328 Licensed under the Apache License 2.0 (the "License"). You may not use
329 this file except in compliance with the License. You can obtain a copy
330 in the file LICENSE in the source distribution or at
331 <https://www.openssl.org/source/license.html>.