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