1999-11-10 10:52:17 +08:00
|
|
|
=pod
|
2000-01-07 09:39:59 +08:00
|
|
|
|
1999-11-10 10:52:17 +08:00
|
|
|
=head1 NAME
|
|
|
|
|
2019-08-22 07:04:41 +08:00
|
|
|
openssl-dgst - perform digest operations
|
1999-11-10 10:52:17 +08:00
|
|
|
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
|
2017-08-14 21:32:07 +08:00
|
|
|
B<openssl dgst>
|
2019-10-02 23:13:03 +08:00
|
|
|
[B<-I<digest>>]
|
2017-08-14 21:32:07 +08:00
|
|
|
[B<-help>]
|
1999-11-10 10:52:17 +08:00
|
|
|
[B<-c>]
|
|
|
|
[B<-d>]
|
2000-09-04 07:13:48 +08:00
|
|
|
[B<-hex>]
|
|
|
|
[B<-binary>]
|
2014-08-29 07:11:42 +08:00
|
|
|
[B<-r>]
|
2019-09-26 03:20:11 +08:00
|
|
|
[B<-out> I<filename>]
|
|
|
|
[B<-sign> I<filename>]
|
|
|
|
[B<-keyform> I<arg>]
|
|
|
|
[B<-passin> I<arg>]
|
|
|
|
[B<-verify> I<filename>]
|
|
|
|
[B<-prverify> I<filename>]
|
|
|
|
[B<-signature> I<filename>]
|
|
|
|
[B<-sigopt> I<nm>:I<v>]
|
|
|
|
[B<-hmac> I<key>]
|
2014-08-29 07:11:42 +08:00
|
|
|
[B<-fips-fingerprint>]
|
2019-10-01 16:00:14 +08:00
|
|
|
[B<-rand> I<files>]
|
2019-09-26 03:20:11 +08:00
|
|
|
[B<-engine> I<id>]
|
2016-02-08 12:14:12 +08:00
|
|
|
[B<-engine_impl>]
|
2019-10-01 15:57:37 +08:00
|
|
|
[I<file> ...]
|
1999-11-10 10:52:17 +08:00
|
|
|
|
2017-08-14 21:32:07 +08:00
|
|
|
B<openssl> I<digest> [B<...>]
|
1999-11-10 10:52:17 +08:00
|
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
2000-09-04 07:13:48 +08:00
|
|
|
The digest functions output the message digest of a supplied file or files
|
2014-08-29 07:11:42 +08:00
|
|
|
in hexadecimal. The digest functions also generate and verify digital
|
|
|
|
signatures using message digests.
|
1999-11-10 10:52:17 +08:00
|
|
|
|
2015-12-13 08:25:25 +08:00
|
|
|
The generic name, B<dgst>, may be used with an option specifying the
|
|
|
|
algorithm to be used.
|
|
|
|
The default digest is I<sha256>.
|
2016-02-08 12:14:12 +08:00
|
|
|
A supported I<digest> name may also be used as the command name.
|
|
|
|
To see the list of supported algorithms, use the I<list --digest-commands>
|
2015-12-13 08:25:25 +08:00
|
|
|
command.
|
|
|
|
|
1999-11-10 10:52:17 +08:00
|
|
|
=head1 OPTIONS
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
2016-02-06 00:58:45 +08:00
|
|
|
=item B<-help>
|
|
|
|
|
|
|
|
Print out a usage message.
|
|
|
|
|
2019-10-02 23:13:03 +08:00
|
|
|
=item B<-I<digest>>
|
2016-02-08 12:14:12 +08:00
|
|
|
|
|
|
|
Specifies name of a supported digest to be used. To see the list of
|
2019-09-26 03:20:11 +08:00
|
|
|
supported digests, use the command C<list --digest-commands>.
|
2016-02-08 12:14:12 +08:00
|
|
|
|
1999-11-10 10:52:17 +08:00
|
|
|
=item B<-c>
|
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Print out the digest in two digit groups separated by colons, only relevant if
|
2000-09-04 07:13:48 +08:00
|
|
|
B<hex> format output is used.
|
1999-11-10 10:52:17 +08:00
|
|
|
|
|
|
|
=item B<-d>
|
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Print out BIO debugging information.
|
1999-11-10 10:52:17 +08:00
|
|
|
|
2000-09-04 07:13:48 +08:00
|
|
|
=item B<-hex>
|
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Digest is to be output as a hex dump. This is the default case for a "normal"
|
2014-08-29 07:11:42 +08:00
|
|
|
digest as opposed to a digital signature. See NOTES below for digital
|
|
|
|
signatures using B<-hex>.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
|
|
|
=item B<-binary>
|
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Output the digest or signature in binary form.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2014-08-29 07:11:42 +08:00
|
|
|
=item B<-r>
|
|
|
|
|
2019-03-30 09:22:51 +08:00
|
|
|
Output the digest in the "coreutils" format, including newlines.
|
|
|
|
Used by programs like B<sha1sum>.
|
2014-08-29 07:11:42 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-out> I<filename>
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Filename to output to, or standard output by default.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-sign> I<filename>
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2018-04-05 20:03:37 +08:00
|
|
|
Digitally sign the digest using the private key in "filename". Note this option
|
|
|
|
does not support Ed25519 or Ed448 private keys. Use the B<pkeyutl> command
|
|
|
|
instead for this.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-keyform> I<arg>
|
2009-04-15 23:27:03 +08:00
|
|
|
|
2014-08-29 07:11:42 +08:00
|
|
|
Specifies the key format to sign digest with. The DER, PEM, P12,
|
|
|
|
and ENGINE formats are supported.
|
2009-04-15 23:27:03 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-sigopt> I<nm>:I<v>
|
2009-04-15 23:27:03 +08:00
|
|
|
|
|
|
|
Pass options to the signature algorithm during sign or verify operations.
|
|
|
|
Names and values of these options are algorithm-specific.
|
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-passin> I<arg>
|
2004-12-03 20:26:56 +08:00
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
The private key password source. For more information about the format of B<arg>
|
2019-09-26 03:20:11 +08:00
|
|
|
see L<openssl(1)/Pass phrase options>.
|
2004-12-03 20:26:56 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-verify> I<filename>
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Verify the signature using the public key in "filename".
|
2000-09-04 07:13:48 +08:00
|
|
|
The output is either "Verification OK" or "Verification Failure".
|
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-prverify> I<filename>
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Verify the signature using the private key in "filename".
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-signature> I<filename>
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
The actual signature to verify.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-hmac> I<key>
|
2017-07-06 05:12:35 +08:00
|
|
|
|
|
|
|
Create a hashed MAC using "key".
|
|
|
|
|
2019-09-21 08:29:17 +08:00
|
|
|
The L<openssl-mac(1)> command should be preferred to using this command line
|
|
|
|
option.
|
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-mac> I<alg>
|
2009-04-15 23:27:03 +08:00
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Create MAC (keyed Message Authentication Code). The most popular MAC
|
2009-04-15 23:27:03 +08:00
|
|
|
algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
|
|
|
|
which are not based on hash, for instance B<gost-mac> algorithm,
|
|
|
|
supported by B<ccgost> engine. MAC keys and other options should be set
|
|
|
|
via B<-macopt> parameter.
|
|
|
|
|
2019-09-21 08:29:17 +08:00
|
|
|
The L<openssl-mac(1)> command should be preferred to using this command line
|
|
|
|
option.
|
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-macopt> I<nm>:I<v>
|
2009-04-15 23:27:03 +08:00
|
|
|
|
|
|
|
Passes options to MAC algorithm, specified by B<-mac> key.
|
|
|
|
Following options are supported by both by B<HMAC> and B<gost-mac>:
|
|
|
|
|
2017-04-04 03:39:09 +08:00
|
|
|
=over 4
|
2009-04-15 23:27:03 +08:00
|
|
|
|
|
|
|
=item B<key:string>
|
2014-08-29 07:11:42 +08:00
|
|
|
|
2015-04-14 00:29:52 +08:00
|
|
|
Specifies MAC key as alphanumeric string (use if key contain printable
|
2009-04-15 23:27:03 +08:00
|
|
|
characters only). String length must conform to any restrictions of
|
|
|
|
the MAC algorithm for example exactly 32 chars for gost-mac.
|
|
|
|
|
|
|
|
=item B<hexkey:string>
|
|
|
|
|
|
|
|
Specifies MAC key in hexadecimal form (two hex digits per byte).
|
|
|
|
Key length must conform to any restrictions of the MAC algorithm
|
|
|
|
for example exactly 32 chars for gost-mac.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
2019-09-21 08:29:17 +08:00
|
|
|
The L<openssl-mac(1)> command should be preferred to using this command line
|
|
|
|
option.
|
|
|
|
|
2019-10-01 16:00:14 +08:00
|
|
|
=item B<-rand> I<files>
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2019-10-01 16:00:14 +08:00
|
|
|
The files containing random data used to seed the random number generator.
|
2016-03-20 00:28:58 +08:00
|
|
|
Multiple files can be specified separated by an OS-dependent character.
|
2000-09-04 07:13:48 +08:00
|
|
|
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
|
2016-05-20 20:11:46 +08:00
|
|
|
all others.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-writerand> I<file>
|
2017-07-05 22:58:48 +08:00
|
|
|
|
|
|
|
Writes random data to the specified I<file> upon exit.
|
|
|
|
This can be used with a subsequent B<-rand> flag.
|
|
|
|
|
2014-08-29 07:11:42 +08:00
|
|
|
=item B<-fips-fingerprint>
|
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
|
2014-08-29 07:11:42 +08:00
|
|
|
|
2019-09-26 03:20:11 +08:00
|
|
|
=item B<-engine> I<id>
|
2016-02-08 12:14:12 +08:00
|
|
|
|
|
|
|
Use engine B<id> for operations (including private key storage).
|
|
|
|
This engine is not used as source for digest algorithms, unless it is
|
|
|
|
also specified in the configuration file or B<-engine_impl> is also
|
|
|
|
specified.
|
|
|
|
|
|
|
|
=item B<-engine_impl>
|
|
|
|
|
|
|
|
When used with the B<-engine> option, it specifies to also use
|
|
|
|
engine B<id> for digest operations.
|
|
|
|
|
2019-10-01 15:57:37 +08:00
|
|
|
=item I<file> ...
|
1999-11-10 10:52:17 +08:00
|
|
|
|
2017-03-30 05:38:30 +08:00
|
|
|
File or files to digest. If no files are specified then standard input is
|
1999-11-10 10:52:17 +08:00
|
|
|
used.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
2014-08-29 07:11:42 +08:00
|
|
|
|
|
|
|
=head1 EXAMPLES
|
|
|
|
|
|
|
|
To create a hex-encoded message digest of a file:
|
|
|
|
openssl dgst -md5 -hex file.txt
|
|
|
|
|
|
|
|
To sign a file using SHA-256 with binary file output:
|
|
|
|
openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt
|
|
|
|
|
|
|
|
To verify a signature:
|
|
|
|
openssl dgst -sha256 -verify publickey.pem \
|
|
|
|
-signature signature.sign \
|
|
|
|
file.txt
|
|
|
|
|
|
|
|
|
1999-11-10 10:52:17 +08:00
|
|
|
=head1 NOTES
|
|
|
|
|
2015-08-28 00:28:08 +08:00
|
|
|
The digest mechanisms that are available will depend on the options
|
|
|
|
used when building OpenSSL.
|
|
|
|
The B<list digest-commands> command can be used to list them.
|
|
|
|
|
2014-08-29 07:11:42 +08:00
|
|
|
New or agile applications should use probably use SHA-256. Other digests,
|
|
|
|
particularly SHA-1 and MD5, are still widely used for interoperating
|
|
|
|
with existing formats and protocols.
|
1999-11-10 10:52:17 +08:00
|
|
|
|
2014-08-29 07:11:42 +08:00
|
|
|
When signing a file, B<dgst> will automatically determine the algorithm
|
|
|
|
(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
|
|
|
|
When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
|
|
|
|
itself, not the related data to identify the signer and algorithm used in
|
|
|
|
formats such as x.509, CMS, and S/MIME.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
|
|
|
A source of random numbers is required for certain signing algorithms, in
|
2014-08-29 07:11:42 +08:00
|
|
|
particular ECDSA and DSA.
|
2000-09-04 07:13:48 +08:00
|
|
|
|
|
|
|
The signing and verify options should only be used if a single file is
|
|
|
|
being signed or verified.
|
|
|
|
|
2014-08-29 07:11:42 +08:00
|
|
|
Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r"
|
|
|
|
or similar program to transform the hex signature into a binary signature
|
|
|
|
prior to verification.
|
|
|
|
|
2019-09-21 08:29:17 +08:00
|
|
|
The L<openssl-mac(1)> command is preferred over the B<-hmac>, B<-mac> and
|
|
|
|
B<-macopt> command line options.
|
|
|
|
|
|
|
|
=head1 SEE ALSO
|
|
|
|
|
|
|
|
L<openssl-mac(1)>
|
|
|
|
|
2015-12-13 08:25:25 +08:00
|
|
|
=head1 HISTORY
|
|
|
|
|
2019-02-01 22:03:09 +08:00
|
|
|
The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0.
|
|
|
|
The FIPS-related options were removed in OpenSSL 1.1.0.
|
2014-08-29 07:11:42 +08:00
|
|
|
|
2016-05-18 23:44:05 +08:00
|
|
|
=head1 COPYRIGHT
|
|
|
|
|
2019-03-19 09:22:32 +08:00
|
|
|
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
|
2016-05-18 23:44:05 +08:00
|
|
|
|
2018-12-06 21:04:11 +08:00
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
2016-05-18 23:44:05 +08:00
|
|
|
this file except in compliance with the License. You can obtain a copy
|
|
|
|
in the file LICENSE in the source distribution or at
|
|
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
|
|
|
|
=cut
|