]>
Commit | Line | Data |
---|---|---|
aba3e65f | 1 | =pod |
19d2bb57 | 2 | |
aba3e65f DSH |
3 | =head1 NAME |
4 | ||
b6b66573 | 5 | openssl-dgst - perform digest operations |
aba3e65f DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
b2bdfb63 | 9 | B<openssl> B<dgst>|I<digest> |
8dc57d76 | 10 | [B<-I<digest>>] |
e75138ab | 11 | [B<-help>] |
aba3e65f DSH |
12 | [B<-c>] |
13 | [B<-d>] | |
bd08a2bd DSH |
14 | [B<-hex>] |
15 | [B<-binary>] | |
d1bea969 | 16 | [B<-r>] |
e8769719 RS |
17 | [B<-out> I<filename>] |
18 | [B<-sign> I<filename>] | |
19 | [B<-keyform> I<arg>] | |
20 | [B<-passin> I<arg>] | |
21 | [B<-verify> I<filename>] | |
22 | [B<-prverify> I<filename>] | |
23 | [B<-signature> I<filename>] | |
24 | [B<-sigopt> I<nm>:I<v>] | |
25 | [B<-hmac> I<key>] | |
d1bea969 | 26 | [B<-fips-fingerprint>] |
fed8bd90 | 27 | [B<-rand> I<files>] |
a397aca4 | 28 | [B<-writerand> I<file>] |
e8769719 | 29 | [B<-engine> I<id>] |
a173a7ee | 30 | [B<-engine_impl>] |
b1c0cc24 | 31 | [I<file> ...] |
aba3e65f | 32 | |
aba3e65f DSH |
33 | =head1 DESCRIPTION |
34 | ||
35a810bb RL |
35 | This command output the message digest of a supplied file or files |
36 | in hexadecimal, and also generates and verifies digital | |
d1bea969 | 37 | signatures using message digests. |
aba3e65f | 38 | |
35a810bb | 39 | The generic name, B<openssl dgst>, may be used with an option specifying the |
9e8b6f04 | 40 | algorithm to be used. |
2f0ea936 | 41 | The default digest is B<sha256>. |
35a810bb RL |
42 | A supported I<digest> name may also be used as the sub-command name. |
43 | To see the list of supported algorithms, use C<openssl list -digest-commands> | |
9e8b6f04 | 44 | |
aba3e65f DSH |
45 | =head1 OPTIONS |
46 | ||
47 | =over 4 | |
48 | ||
169394d4 MR |
49 | =item B<-help> |
50 | ||
51 | Print out a usage message. | |
52 | ||
8dc57d76 | 53 | =item B<-I<digest>> |
a173a7ee RS |
54 | |
55 | Specifies name of a supported digest to be used. To see the list of | |
e8769719 | 56 | supported digests, use the command C<list --digest-commands>. |
a173a7ee | 57 | |
aba3e65f DSH |
58 | =item B<-c> |
59 | ||
c4de074e | 60 | Print out the digest in two digit groups separated by colons, only relevant if |
2f0ea936 | 61 | the B<-hex> option is given as well. |
aba3e65f DSH |
62 | |
63 | =item B<-d> | |
64 | ||
c4de074e | 65 | Print out BIO debugging information. |
aba3e65f | 66 | |
bd08a2bd DSH |
67 | =item B<-hex> |
68 | ||
c4de074e | 69 | Digest is to be output as a hex dump. This is the default case for a "normal" |
d1bea969 RS |
70 | digest as opposed to a digital signature. See NOTES below for digital |
71 | signatures using B<-hex>. | |
bd08a2bd DSH |
72 | |
73 | =item B<-binary> | |
74 | ||
c4de074e | 75 | Output the digest or signature in binary form. |
bd08a2bd | 76 | |
d1bea969 RS |
77 | =item B<-r> |
78 | ||
f3448f54 | 79 | Output the digest in the "coreutils" format, including newlines. |
35a810bb | 80 | Used by programs like L<sha1sum(1)>. |
d1bea969 | 81 | |
e8769719 | 82 | =item B<-out> I<filename> |
bd08a2bd | 83 | |
c4de074e | 84 | Filename to output to, or standard output by default. |
bd08a2bd | 85 | |
e8769719 | 86 | =item B<-sign> I<filename> |
bd08a2bd | 87 | |
e65c959f | 88 | Digitally sign the digest using the private key in "filename". Note this option |
35a810bb RL |
89 | does not support Ed25519 or Ed448 private keys. Use the L<openssl-pkeyutl(1)> |
90 | command instead for this. | |
bd08a2bd | 91 | |
e8769719 | 92 | =item B<-keyform> I<arg> |
e5fa864f | 93 | |
d1bea969 RS |
94 | Specifies the key format to sign digest with. The DER, PEM, P12, |
95 | and ENGINE formats are supported. | |
e5fa864f | 96 | |
e8769719 | 97 | =item B<-sigopt> I<nm>:I<v> |
e5fa864f DSH |
98 | |
99 | Pass options to the signature algorithm during sign or verify operations. | |
100 | Names and values of these options are algorithm-specific. | |
101 | ||
e8769719 | 102 | =item B<-passin> I<arg> |
5b40d7dd | 103 | |
2f0ea936 | 104 | The private key password source. For more information about the format of I<arg> |
3a4e43de | 105 | see L<openssl(1)/Pass Phrase Options>. |
5b40d7dd | 106 | |
e8769719 | 107 | =item B<-verify> I<filename> |
bd08a2bd | 108 | |
c4de074e | 109 | Verify the signature using the public key in "filename". |
bd08a2bd DSH |
110 | The output is either "Verification OK" or "Verification Failure". |
111 | ||
e8769719 | 112 | =item B<-prverify> I<filename> |
bd08a2bd | 113 | |
c4de074e | 114 | Verify the signature using the private key in "filename". |
bd08a2bd | 115 | |
e8769719 | 116 | =item B<-signature> I<filename> |
bd08a2bd | 117 | |
c4de074e | 118 | The actual signature to verify. |
bd08a2bd | 119 | |
e8769719 | 120 | =item B<-hmac> I<key> |
67fdc998 RS |
121 | |
122 | Create a hashed MAC using "key". | |
123 | ||
a941054a P |
124 | The L<openssl-mac(1)> command should be preferred to using this command line |
125 | option. | |
126 | ||
e8769719 | 127 | =item B<-mac> I<alg> |
e5fa864f | 128 | |
c4de074e | 129 | Create MAC (keyed Message Authentication Code). The most popular MAC |
e5fa864f DSH |
130 | algorithm is HMAC (hash-based MAC), but there are other MAC algorithms |
131 | which are not based on hash, for instance B<gost-mac> algorithm, | |
bc9564c2 | 132 | supported by the B<gost> engine. MAC keys and other options should be set |
e5fa864f DSH |
133 | via B<-macopt> parameter. |
134 | ||
a941054a P |
135 | The L<openssl-mac(1)> command should be preferred to using this command line |
136 | option. | |
137 | ||
e8769719 | 138 | =item B<-macopt> I<nm>:I<v> |
e5fa864f DSH |
139 | |
140 | Passes options to MAC algorithm, specified by B<-mac> key. | |
141 | Following options are supported by both by B<HMAC> and B<gost-mac>: | |
142 | ||
e1271ac2 | 143 | =over 4 |
e5fa864f | 144 | |
2f0ea936 | 145 | =item B<key>:I<string> |
d1bea969 | 146 | |
4c583c36 | 147 | Specifies MAC key as alphanumeric string (use if key contain printable |
e5fa864f DSH |
148 | characters only). String length must conform to any restrictions of |
149 | the MAC algorithm for example exactly 32 chars for gost-mac. | |
150 | ||
2f0ea936 | 151 | =item B<hexkey>:I<string> |
e5fa864f DSH |
152 | |
153 | Specifies MAC key in hexadecimal form (two hex digits per byte). | |
154 | Key length must conform to any restrictions of the MAC algorithm | |
155 | for example exactly 32 chars for gost-mac. | |
156 | ||
157 | =back | |
158 | ||
a941054a P |
159 | The L<openssl-mac(1)> command should be preferred to using this command line |
160 | option. | |
161 | ||
a397aca4 | 162 | =item B<-rand> I<files>, B<-writerand> I<file> |
bd08a2bd | 163 | |
a397aca4 | 164 | See L<openssl(1)/Random State Options> for more information. |
3ee1eac2 | 165 | |
d1bea969 RS |
166 | =item B<-fips-fingerprint> |
167 | ||
c4de074e | 168 | Compute HMAC using a specific key for certain OpenSSL-FIPS operations. |
d1bea969 | 169 | |
e8769719 | 170 | =item B<-engine> I<id> |
a173a7ee | 171 | |
2f0ea936 | 172 | Use engine I<id> for operations (including private key storage). |
a173a7ee RS |
173 | This engine is not used as source for digest algorithms, unless it is |
174 | also specified in the configuration file or B<-engine_impl> is also | |
175 | specified. | |
176 | ||
177 | =item B<-engine_impl> | |
178 | ||
179 | When used with the B<-engine> option, it specifies to also use | |
2f0ea936 | 180 | engine I<id> for digest operations. |
a173a7ee | 181 | |
b1c0cc24 | 182 | =item I<file> ... |
aba3e65f | 183 | |
c4de074e | 184 | File or files to digest. If no files are specified then standard input is |
aba3e65f DSH |
185 | used. |
186 | ||
187 | =back | |
188 | ||
d1bea969 RS |
189 | |
190 | =head1 EXAMPLES | |
191 | ||
192 | To create a hex-encoded message digest of a file: | |
193 | openssl dgst -md5 -hex file.txt | |
194 | ||
195 | To sign a file using SHA-256 with binary file output: | |
196 | openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt | |
197 | ||
198 | To verify a signature: | |
199 | openssl dgst -sha256 -verify publickey.pem \ | |
200 | -signature signature.sign \ | |
201 | file.txt | |
202 | ||
203 | ||
aba3e65f DSH |
204 | =head1 NOTES |
205 | ||
c03726ca RS |
206 | The digest mechanisms that are available will depend on the options |
207 | used when building OpenSSL. | |
35a810bb | 208 | The C<openssl list -digest-commands> command can be used to list them. |
c03726ca | 209 | |
d1bea969 RS |
210 | New or agile applications should use probably use SHA-256. Other digests, |
211 | particularly SHA-1 and MD5, are still widely used for interoperating | |
212 | with existing formats and protocols. | |
aba3e65f | 213 | |
35a810bb | 214 | When signing a file, this command will automatically determine the algorithm |
d1bea969 RS |
215 | (RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. |
216 | When verifying signatures, it only handles the RSA, DSA, or ECDSA signature | |
217 | itself, not the related data to identify the signer and algorithm used in | |
218 | formats such as x.509, CMS, and S/MIME. | |
bd08a2bd DSH |
219 | |
220 | A source of random numbers is required for certain signing algorithms, in | |
d1bea969 | 221 | particular ECDSA and DSA. |
bd08a2bd DSH |
222 | |
223 | The signing and verify options should only be used if a single file is | |
224 | being signed or verified. | |
225 | ||
d1bea969 RS |
226 | Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r" |
227 | or similar program to transform the hex signature into a binary signature | |
228 | prior to verification. | |
229 | ||
a941054a P |
230 | The L<openssl-mac(1)> command is preferred over the B<-hmac>, B<-mac> and |
231 | B<-macopt> command line options. | |
232 | ||
233 | =head1 SEE ALSO | |
234 | ||
235 | L<openssl-mac(1)> | |
236 | ||
9e8b6f04 RS |
237 | =head1 HISTORY |
238 | ||
e3ac3654 VM |
239 | The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0. |
240 | The FIPS-related options were removed in OpenSSL 1.1.0. | |
d1bea969 | 241 | |
e2f92610 RS |
242 | =head1 COPYRIGHT |
243 | ||
d7b2124a | 244 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 245 | |
449040b4 | 246 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
247 | this file except in compliance with the License. You can obtain a copy |
248 | in the file LICENSE in the source distribution or at | |
249 | L<https://www.openssl.org/source/license.html>. | |
250 | ||
251 | =cut |