GmSSL/doc/apps/dgst.pod

=pod

=encoding utf8 

=head1 NAME

dgst, sha, sha1, mdc2, ripemd160, sha224, sm3, sha384, sha512, md4, md5, blake2b, blake2s - message digests

=head1 SYNOPSIS

B<gmssl> B<dgst>
[B<-help>]
[B<-I<digest>>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
[B<-r>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
[B<-passin arg>]
[B<-verify filename>]
[B<-prverify filename>]
[B<-signature filename>]
[B<-hmac key>]
[B<-fips-fingerprint>]
[B<-engine id>]
[B<-engine_impl>]
[B<file...>]

B<gmssl>
[I<digest>]
[B<...>]

=head1 DESCRIPTION

The digest functions output the message digest of a supplied file or files
in hexadecimal.  The digest functions also generate and verify digital
signatures using message digests.

The generic name, B<dgst>, may be used with an option specifying the
algorithm to be used.
The default digest is I<sm3>.
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>
command.

摘要功能输出所提供文件的消息摘要或是十六进制文件。摘要功能还能使用消息摘要生成和验证数字签名。

通用名称dgst可以与指定要使用算法的选项一起使用。默认的摘要是sm3.支持的digest名称也可作为命令名称。要查看支持的算法列表，请使用list --digest-commands。

=head1 OPTIONS

=over 4

=item B<-help>

Print out a usage message.

输出使用信息。

=item B<-I<digest>>

Specifies name of a supported digest to be used. To see the list of
supported digests, use the command I<list --digest-commands>.

指定要使用支持摘要的名称。要查看支持的摘要列表，使用命令list --digest-commands。

=item B<-c>

print out the digest in two digit groups separated by colons, only relevant if
B<hex> format output is used.

打印两个数组中的摘要的时候用冒号来分隔开。仅仅设置了hex格式输出时有效。

=item B<-d>

print out BIO debugging information.

打印出BIO调试信息值。

=item B<-hex>

digest is to be output as a hex dump. This is the default case for a "normal"
digest as opposed to a digital signature.  See NOTES below for digital
signatures using B<-hex>.

摘要将作为十六进制转储输出。 这是“正常”摘要的默认情况，而不是数字签名。 请参阅下面的注释使用-hex的数字签名。

=item B<-binary>

output the digest or signature in binary form.

以二进制的形式来显示摘要结果值。

=item B<-r>

output the digest in the "coreutils" format used by programs like B<sha1sum>.

用coreutils格式来输出摘要值，被一些像shalsum的程序使用。

=item B<-out filename>

filename to output to, or standard output by default.

输出对象文件名，默认为标准输出。

=item B<-sign filename>

digitally sign the digest using the private key in "filename".

用filename中的私钥文件对数据进行签名。

=item B<-keyform arg>

Specifies the key format to sign digest with. The DER, PEM, P12,
and ENGINE formats are supported.

指定了签署摘要的密钥格式。该命令中仅仅支持DER，PEM，P12以及ENGINE格式。

=item B<-sigopt nm:v>

Pass options to the signature algorithm during sign or verify operations.
Names and values of these options are algorithm-specific.

签名或验证签名的操作中，签名算法参数的选项值。

=item B<-passin arg>

the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.

私钥密码源。

=item B<-verify filename>

verify the signature using the public key in "filename".
The output is either "Verification OK" or "Verification Failure".

使用filename中的公钥验证签名。
输出要么是验证通过要么是验证失败。

=item B<-prverify filename>

verify the signature using the private key in "filename".

使用filename中的公钥验证签名。

=item B<-signature filename>

the actual signature to verify.

实际要验证的签名

=item B<-hmac key>

create a hashed MAC using "key".

用key创建哈希MAC

=item B<-mac alg>

create MAC (keyed Message Authentication Code). The most popular MAC
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.

创建MAC（密钥消息认证码）。 最流行的MAC算法是HMAC（基于散列的MAC），但是还有其他MAC算法不是基于哈希的，比如gost-mac算法，由ccgost引擎支持。 应通过-macopt参数设置MAC密钥和其他选项。

=item B<-macopt nm:v>

Passes options to MAC algorithm, specified by B<-mac> key.
Following options are supported by both by B<HMAC> and B<gost-mac>:

通过命令到MAC算法，由-mac指定。

=over 8

=item B<key:string>

Specifies MAC key as alphanumeric string (use if key contain printable
characters only). String length must conform to any restrictions of
the MAC algorithm for example exactly 32 chars for gost-mac.

指定MAC密钥值作为字母字符串。字符串长度必须符合摘要算法的限制条件，例如对gost-mac来说是32字节。

=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.

指定MAC密钥值作为十六进制字符串。字符串长度必须符合摘要算法的限制条件，例如对gost-mac来说是32字节。

=back

=item B<-rand file(s)>

a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.

产生随机数种子的文件

=item B<-fips-fingerprint>

compute HMAC using a specific key
for certain GmSSL-FIPS operations.

用指定的密钥计算HMAC，为了有关的GMSSL-FIPS操作。

=item B<-engine id>

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.

使用引擎ID进行操作（包括私钥存储）。 此引擎不用作摘要算法的源，除非在配置文件中也指定了引擎，还指定了-engine_impl。

=item B<-engine_impl>

When used with the B<-engine> option, it specifies to also use
engine B<id> for digest operations.

当与-engine选项一起使用时，它还指定还使用引擎ID进行摘要操作。

=item B<file...>

file or files to digest. If no files are specified then standard input is
used.

要摘要的文件。如果没有指定文件，就使用标准输入。

=back


=head1 EXAMPLES

To create a hex-encoded message digest of a file:
 gmssl dgst -md5 -hex file.txt

To sign a file using SHA-256 with binary file output:
 gmssl dgst -sm3 -sign privatekey.pem -out signature.sign file.txt

To verify a signature:
 gmssl dgst -sm3 -verify publickey.pem \
 -signature signature.sign \
 file.txt


=head1 NOTES

The digest mechanisms that are available will depend on the options
used when building GmSSL.
The B<list digest-commands> command can be used to list them.

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.

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.

A source of random numbers is required for certain signing algorithms, in
particular ECDSA and DSA.

The signing and verify options should only be used if a single file is
being signed or verified.

Hex signatures cannot be verified using B<gmssl>.  Instead, use "xxd -r"
or similar program to transform the hex signature into a binary signature
prior to verification.

=head1 HISTORY

The default digest was changed from MD5 to SM3 in GmSSL 2.0
The FIPS-related options were removed in GmSSL 2.0

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the GmSSL license (the "License").  You may not use
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