- NAME
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- EXAMPLES
- NOTES
- HISTORY
- COPYRIGHT

# NAME

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

# SYNOPSIS

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

gmssl [digest] [...]

# 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, dgst, may be used with an option specifying the algorithm to be used. The default digest is sm3. A supported digest name may also be used as the command name. To see the list of supported algorithms, use the list --digest-commands command.

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

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

# OPTIONS

-help

  Print out a usage message.

  输出使用信息。

-digest

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

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

-c

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

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

-d

  print out BIO debugging information.

  打印出BIO调试信息值。

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

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

-binary

  output the digest or signature in binary form.

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

-r

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

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

-out filename

  filename to output to, or standard output by default.

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

-sign filename

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

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

-keyform arg

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

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

-sigopt nm:v

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

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

-passin arg

  the private key password source. For more information about the format of arg see the PASS PHRASE ARGUMENTS section in -verify filename

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

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

-prverify filename

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

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

-signature filename

  the actual signature to verify.

  实际要验证的签名

-hmac key

  create a hashed MAC using "key".

  用key创建哈希MAC

-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 gost-mac algorithm, supported by ccgost engine. MAC keys and other options should be set via -macopt parameter.

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

-macopt nm:v

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

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

  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字节。

  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字节。

-rand file(s)

  a file or files containing random data used to seed the random number generator, or an EGD socket (see -fips-fingerprint

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

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

-engine id

  Use engine 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 -engine_impl is also specified.

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

-engine_impl

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

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

file...

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

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

# 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

# NOTES

The digest mechanisms that are available will depend on the options used when building GmSSL. The 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, 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 gmssl. Instead, use "xxd -r" or similar program to transform the hex signature into a binary signature prior to verification.

# HISTORY

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

# 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 https://www.openssl.org/source/license.html.