类 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) 点击切换源代码

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

示例 ↑

OpenSSL::Digest.digest("SHA256", "abc")
调用超类方法 
# File openssl/lib/openssl/digest.rb, line 25
def self.digest(name, data)
  super(data, name)
end
new(string [, data]) → Digest 点击切换源代码

根据string 创建一个 Digest 实例，string 是支持的摘要算法的完整名称 (ln) 或简称 (sn)。

如果给出了data（一个字符串），它将用作 Digest 实例的初始输入，即

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

等效于

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

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;
}

公共实例方法

<<(p1)

并非所有消息摘要都可以在一次传递中计算。如果要从多个后续来源计算消息摘要，则可以将每个来源分别传递给 Digest 实例。

示例 ↑

digest = OpenSSL::Digest.new('SHA256')
digest.update('First input')
digest << 'Second input' # equivalent to digest.update('Second input')
result = digest.digest
别名：update
block_length → integer 点击切换源代码

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

示例 ↑

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

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

    GetDigest(self, ctx);

    return INT2NUM(EVP_MD_CTX_block_size(ctx));
}
digest_length → integer 点击切换源代码

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

示例 ↑

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

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

    GetDigest(self, ctx);

    return INT2NUM(EVP_MD_CTX_size(ctx));
}
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 点击切换源代码

返回此 Digest 算法的名称。

示例 ↑

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

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)));
}
reset → self 点击切换源代码

重置 Digest，意味着任何已执行的 Digest#update 操作都被放弃，Digest 恢复到初始状态。

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;
}
update(string) → aString 点击切换源代码

并非所有消息摘要都可以在一次传递中计算。如果要从多个后续来源计算消息摘要，则可以将每个来源分别传递给 Digest 实例。

示例 ↑

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

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;
}
别名：<<

私有实例方法

finish → aString 点击切换源代码 
static VALUE
ossl_digest_finish(int argc, VALUE *argv, VALUE self)
{
    EVP_MD_CTX *ctx;
    VALUE str;
    int out_len;

    GetDigest(self, ctx);
    rb_scan_args(argc, argv, "01", &str);
    out_len = EVP_MD_CTX_size(ctx);

    if (NIL_P(str)) {
        str = rb_str_new(NULL, out_len);
    } else {
        StringValue(str);
        rb_str_resize(str, out_len);
    }

    if (!EVP_DigestFinal_ex(ctx, (unsigned char *)RSTRING_PTR(str), NULL))
        ossl_raise(eDigestError, "EVP_DigestFinal_ex");

    return str;
}