class OpenSSL::Digest

OpenSSL::Digest 允许你计算任意数据的消息摘要（有时也互换地称为“哈希”），这些摘要在密码学上是安全的，即 Digest 实现了一个安全的单向函数。

单向函数提供了一些有用的属性。例如，给定两个不同的输入，两者产生相同输出的概率非常低。结合每个消息摘要算法都有一个固定长度的输出（只有几个字节）这一事实，摘要通常用于为任意数据创建唯一的标识符。一个常见的例子是为存储在数据库中的二进制文档创建唯一的 ID。

单向函数的另一个有用的特性（因此得名）是，给定一个摘要，没有任何关于产生它的原始数据的指示，即识别原始输入的唯一方法是通过暴力破解所有可能的输入组合。

这些特性使得单向函数也成为公钥签名算法的理想伴侣：不必签署整个文档，而是先使用速度快得多的消息摘要算法生成文档的哈希，然后只需使用较慢的公钥算法签署其输出的几个字节。要验证已签名文档的完整性，只需重新计算哈希并验证它是否与签名中的哈希相等即可。

你可以在终端中运行以下命令来获取系统支持的所有摘要算法的列表

openssl list -digest-algorithms

在 OpenSSL 1.1.1 支持的消息摘要算法中，包括

SHA224、SHA256、SHA384、SHA512、SHA512-224 和 SHA512-256
SHA3-224、SHA3-256、SHA3-384 和 SHA3-512
BLAKE2s256 和 BLAKE2b512

可以使用名称实例化这些算法中的每一个

digest = OpenSSL::Digest.new('SHA256')

“破解”消息摘要算法意味着违背其单向函数特性，即产生冲突或找到一种比暴力破解等更有效的方式来获取原始数据。大多数支持的摘要算法在这种意义上可以被认为是破解的，即使是非常流行的 MD5 和 SHA1 算法也是如此。如果安全是您最关心的问题，那么您可能应该依赖 SHA224、SHA256、SHA384 或 SHA512。

哈希文件¶ ↑

data = File.binread('document')
sha256 = OpenSSL::Digest.new('SHA256')
digest = sha256.digest(data)

一次哈希多个数据块¶ ↑

data1 = File.binread('file1')
data2 = File.binread('file2')
data3 = File.binread('file3')
sha256 = OpenSSL::Digest.new('SHA256')
sha256 << data1
sha256 << data2
sha256 << data3
digest = sha256.digest

重用 `Digest` 实例¶ ↑

data1 = File.binread('file1')
sha256 = OpenSSL::Digest.new('SHA256')
digest1 = sha256.digest(data1)

data2 = File.binread('file2')
sha256.reset
digest2 = sha256.digest(data2)

公共类方法

digest (name, data)

源代码

# File ext/openssl/lib/openssl/digest.rb, line 25
def self.digest(name, data)
  super(data, name)
end

返回使用 name Digest 计算的哈希值。name 是支持的摘要算法的长名称或短名称。

示例¶ ↑

OpenSSL::Digest.digest("SHA256", "abc")

调用父类方法

OpenSSL::Digest.digests → array[string...]

源代码

static VALUE
ossl_s_digests(VALUE self)
{
    VALUE ary;

    ary = rb_ary_new();
    OBJ_NAME_do_all_sorted(OBJ_NAME_TYPE_MD_METH,
                    add_digest_name_to_ary,
                    (void*)ary);

    return ary;
}

以数组形式返回所有可用摘要的名称。

new(string [, data]) → Digest

源代码

static VALUE
ossl_digest_initialize(int argc, VALUE *argv, VALUE self)
{
    EVP_MD_CTX *ctx;
    const EVP_MD *md;
    VALUE type, data;

    rb_scan_args(argc, argv, "11", &type, &data);
    md = ossl_evp_get_digestbyname(type);
    if (!NIL_P(data)) StringValue(data);

    TypedData_Get_Struct(self, EVP_MD_CTX, &ossl_digest_type, ctx);
    if (!ctx) {
        RTYPEDDATA_DATA(self) = ctx = EVP_MD_CTX_new();
        if (!ctx)
            ossl_raise(eDigestError, "EVP_MD_CTX_new");
    }

    if (!EVP_DigestInit_ex(ctx, md, NULL))
        ossl_raise(eDigestError, "Digest initialization failed");

    if (!NIL_P(data)) return ossl_digest_update(self, data);
    return self;
}

基于 string 创建 Digest 实例，string 是支持的摘要算法的 ln（长名称）或 sn（短名称）。可以通过调用 OpenSSL::Digest.digests 获取支持的算法列表。

如果给定 data（一个 String），它将用作 Digest 实例的初始输入，即

digest = OpenSSL::Digest.new('sha256', 'digestdata')

等价于

digest = OpenSSL::Digest.new('sha256')
digest.update('digestdata')

公共实例方法

别名为：update

block_length → integer

源代码

static VALUE
ossl_digest_block_length(VALUE self)
{
    EVP_MD_CTX *ctx;

    GetDigest(self, ctx);

    return INT2NUM(EVP_MD_CTX_block_size(ctx));
}

返回摘要算法的块长度，即单个块的字节长度。大多数现代算法将要摘要的消息划分为一系列连续处理的固定大小的块。

示例¶ ↑

digest = OpenSSL::Digest.new('SHA1')
puts digest.block_length # => 64

digest_length → integer

源代码

static VALUE
ossl_digest_size(VALUE self)
{
    EVP_MD_CTX *ctx;

    GetDigest(self, ctx);

    return INT2NUM(EVP_MD_CTX_size(ctx));
}

返回摘要的输出大小，即最终消息摘要结果的字节长度。

示例¶ ↑

digest = OpenSSL::Digest.new('SHA1')
puts digest.digest_length # => 20

initialize_copy (p1)

源代码

static VALUE
ossl_digest_copy(VALUE self, VALUE other)
{
    EVP_MD_CTX *ctx1, *ctx2;

    rb_check_frozen(self);
    if (self == other) return self;

    TypedData_Get_Struct(self, EVP_MD_CTX, &ossl_digest_type, ctx1);
    if (!ctx1) {
        RTYPEDDATA_DATA(self) = ctx1 = EVP_MD_CTX_new();
        if (!ctx1)
            ossl_raise(eDigestError, "EVP_MD_CTX_new");
    }
    GetDigest(other, ctx2);

    if (!EVP_MD_CTX_copy(ctx1, ctx2)) {
        ossl_raise(eDigestError, NULL);
    }
    return self;
}

name → string

源代码

static VALUE
ossl_digest_name(VALUE self)
{
    EVP_MD_CTX *ctx;

    GetDigest(self, ctx);

    return rb_str_new_cstr(EVP_MD_name(EVP_MD_CTX_get0_md(ctx)));
}

返回此 Digest 算法的短名称，该名称可能与提供的原始名称略有不同。

示例¶ ↑

digest = OpenSSL::Digest.new('SHA512')
puts digest.name # => SHA512

reset → self

源代码

static VALUE
ossl_digest_reset(VALUE self)
{
    EVP_MD_CTX *ctx;

    GetDigest(self, ctx);
    if (EVP_DigestInit_ex(ctx, EVP_MD_CTX_get0_md(ctx), NULL) != 1) {
        ossl_raise(eDigestError, "Digest initialization failed.");
    }

    return self;
}

重置 Digest，即放弃任何已执行的 Digest#update，并将 Digest 再次设置为其初始状态。

update(string) → aString

源代码

static VALUE
ossl_digest_update(VALUE self, VALUE data)
{
    EVP_MD_CTX *ctx;

    StringValue(data);
    GetDigest(self, ctx);

    if (!EVP_DigestUpdate(ctx, RSTRING_PTR(data), RSTRING_LEN(data)))
        ossl_raise(eDigestError, "EVP_DigestUpdate");

    return self;
}

并非每个消息摘要都可以一次性计算。如果要从多个后续源计算消息摘要，则可以将每个源单独传递给 Digest 实例。

示例¶ ↑

digest = OpenSSL::Digest.new('SHA256')
digest.update('First input')
digest << 'Second input' # equivalent to digest.update('Second input')
result = digest.digest

也别名为：<<

私有实例方法

finish → aString

源代码

static VALUE
ossl_digest_finish(VALUE self)
{
    EVP_MD_CTX *ctx;
    VALUE str;

    GetDigest(self, ctx);
    str = rb_str_new(NULL, EVP_MD_CTX_size(ctx));
    if (!EVP_DigestFinal_ex(ctx, (unsigned char *)RSTRING_PTR(str), NULL))
        ossl_raise(eDigestError, "EVP_DigestFinal_ex");

    return str;
}

class OpenSSL::Digest

哈希文件¶ ↑

一次哈希多个数据块¶ ↑

重用 Digest 实例¶ ↑

示例¶ ↑

示例¶ ↑

示例¶ ↑

示例¶ ↑

示例¶ ↑

重用 `Digest` 实例¶ ↑