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