仓颉标准库 std.crypto.digest 摘要运算函数 digest 使用指南:字节数组、字符串与输入流三种重载详解

原创2026-10-14 20:55:521,446 阅读
文章标签:文档知识库

仓颉标准库 std.crypto.digest 摘要运算函数 digest 使用指南:字节数组、字符串与输入流三种重载详解

本文围绕仓颉标准库 std.crypto.digest 包中三个重载的 digest<T> 泛型函数展开,系统讲解如何用统一的泛型入口对 Array<Byte>、String 与 InputStream 三种数据源执行摘要运算。读者将掌握 where T <: Digest 泛型约束的含义、Digest 接口成员契约、三种重载的差异与适用场景,并能结合 stdx.crypto.digest 提供的 MD5、SHA 系列、SM3 等真实算法类编写可运行的摘要计算代码。

一、digest 泛型函数在包中的定位

std.crypto.digest 包为仓颉标准库中的摘要算法能力包,提供常用摘要算法的通用接口,包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3 等(见 digest_package_overview.md)。

该包由两部分组成:

  • 接口层:Digest 接口,是所有摘要算法实现必须遵守的通用契约;
  • 函数层:digest<T> 泛型函数,提供三种重载,屏蔽算法细节,让调用方以同样的写法对不同数据源做摘要运算。

函数层的三个重载在 digest_package_funcs.md 中定义:

函数签名 功能
digest<T>(T, Array<Byte>) where T <: Digest 对字节数组进行摘要运算
digest<T>(T, String) where T <: Digest 对字符串进行摘要运算(已标注 deprecated)
digest<T>(T, InputStream) where T <: Digest 对 InputStream 输入流中的数据进行摘要运算

三者共同点是第一个参数均为"具体的摘要算法"实例(泛型参数 T,受 Digest 接口约束),区别在于第二个参数的数据来源形态。理解这一点后,后文可以逐个展开。

二、前置约束:Digest 接口契约

digest<T> 的泛型约束 where T <: Digest 意味着:传入的算法对象必须实现 Digest 接口。该接口定义于 digest_package_interfaces.md,源码如下:

public interface Digest {
    prop size: Int64
    prop blockSize: Int64
    prop algorithm: String
    func write(buffer: Array<Byte>): Unit
    func finish(to!: Array<Byte>): Unit
    func finish(): Array<Byte>
    func reset(): Unit
}

各成员的契约含义:

成员 功能说明
prop algorithm: String 获取摘要算法的算法名称
prop blockSize: Int64 返回信息块(Block)长度,单位字节
prop size: Int64 返回生成的摘要信息长度,单位字节
func write(buffer: Array<Byte>): Unit 使用给定的 buffer 更新 digest 对象,在 finish 前可多次调用以追加数据
func finish(): Array<Byte> 返回生成的摘要值
func finish(to!: Array<Byte>): Unit 将摘要值写入目标数组 to!
func reset(): Unit 重置 digest 对象到初始状态

需要注意:接口文档明确提醒,调用 finish 后不可以再进行摘要计算,如需要重新计算必须先调用 reset() 重置上下文。这是摘要对象状态的硬性约束,也是后续示例中 reset() 出现的原因。

三、重载一:对字节数组做摘要 digest<T>(T, Array<Byte>)

函数签名与参数说明

public func digest<T>(algorithm: T, data: Array<Byte>): Array<Byte> where T <: Digest
参数 类型 说明
algorithm T(受 Digest 约束) 具体的摘要算法实例
data Array<Byte> 待进行摘要运算的数据

返回值:Array<Byte>,即摘要运算结果。其中 Byte 是内置类型 UInt8 的类型别名,一个字节对应一个元素。

官方示例与运行结果

原文档提供了完整可验证的示例(文中 <!-- verify --> 标记表示该示例经过校验):

import std.crypto.digest.*

main() {
    let data: Array<Byte> = [1, 2, 3, 4, 5]
    let mydigest = MyDigest()
    let digestBytes = digest<MyDigest>(mydigest, data)
    println(digestBytes)
}

// 自定义 Digest
class MyDigest <: Digest {
    public prop size: Int64 {
        get() { 0 }
    }
    public prop blockSize: Int64 {
        get() { 0 }
    }
    public prop algorithm: String {
        get() { "" }
    }
    public func write(buffer: Array<Byte>): Unit { println("buffer = ${buffer}") }
    public func finish(to!: Array<Byte>): Unit { println("to = ${to}") }
    public func finish(): Array<Byte> { [3,2,1] }
    public func reset(): Unit {}
}

运行结果:

buffer = [1, 2, 3, 4, 5]
[3, 2, 1]

运行流程解读

从运行结果可以清晰还原 digest<T>(T, Array<Byte>) 的内部调用链:

  1. 函数收到字节数组 [1, 2, 3, 4, 5],调用算法实例的 write(buffer),将整段数据一次性"喂"给摘要算法 —— 因此输出了 buffer = [1, 2, 3, 4, 5];
  2. 数据写入完毕后,函数调用 finish() 收尾生成摘要值 —— 示例中自定义 MyDigest 返回 [3, 2, 1],该数组即为函数返回值。

这也解释了示例中 MyDigest 为何必须补齐 Digest 接口的全部成员:泛型约束 where T <: Digest 在编译期就要求 T 具备 write、finish、reset 等能力。实际开发中,调用方无需关心 write/finish 的调用时机,digest 函数已将这一过程封装完毕。

四、重载二:对字符串做摘要 digest<T>(T, String)(已废弃)

public func digest<T>(algorithm: T, data: String): Array<Byte> where T <: Digest

功能与字节数组版本一致,仅将 data 类型换为 String。

注意:

该重载在文档中标注为 deprecated,未来版本即将废弃不再使用,官方建议改用 digest<T>(T, Array<Byte>) where T <: Digest 替代。

也就是说,新代码中处理字符串时,应先将字符串转为字节数组(如调用字符串的 toArray() 方法)再传入字节数组重载。这一做法在后续 stdx 算法示例中也能看到:var str: String = "helloworld" 后通过 str.toArray() 得到 Array<Byte> 再调用 write。迁移成本很低,且语义更统一。

五、重载三:对输入流做摘要 digest<T>(T, InputStream)

函数签名与参数说明

public func digest<T>(algorithm: T, input: InputStream): Array<Byte> where T <: Digest
参数 类型 说明
algorithm T(受 Digest 约束) 具体的摘要算法实例
input InputStream 待进行摘要运算的输入流

返回值:Array<Byte>,摘要运算结果。

这一重载的意义在于:当待摘要数据不是一次性可得(例如大文件、网络数据流),可以借助 InputStream 的分块读取能力边读边算,避免把全部数据加载进内存。InputStream 是 std.io 包的核心接口,其契约仅要求实现 read(buffer: Array<Byte>): Int64,即"从输入流读取数据放入 buffer,返回读取的字节数"(见 io_package_interfaces.md)。

官方示例与运行结果

import std.crypto.digest.*
import std.io.*

main() {
    /* 将原始的字节数组 data 转换为一个输入流 BufferedInputStream */
    let data: Array<Byte> = [1, 2, 3, 4, 5]
    let byteBuffer = ByteBuffer(data)
    let bufferedInputStream = BufferedInputStream(byteBuffer)
    let mydigest = MyDigest()
    let digestBytes = digest<MyDigest>(mydigest, bufferedInputStream)
    println(digestBytes)
}

// 自定义 Digest
class MyDigest <: Digest {
    public prop size: Int64 {
        get() { 0 }
    }
    public prop blockSize: Int64 {
        get() { 2 }
    }
    public prop algorithm: String {
        get() { "" }
    }
    public func write(buffer: Array<Byte>): Unit { println("buffer = ${buffer}") }
    public func finish(to!: Array<Byte>): Unit { println("to = ${to}") }
    public func finish(): Array<Byte> { [3,2,1] }
    public func reset(): Unit {}
}

运行结果:

buffer = [1, 2]
buffer = [3, 4]
buffer = [5]
[3, 2, 1]

分块读取原理解读

对比字节数组重载的输出可以发现关键差异:字节数组版本 write 只被调用一次(buffer = [1, 2, 3, 4, 5]),而输入流版本 write 被调用了三次,依次是 [1, 2]、[3, 4]、[5]。

这正是由 MyDigest.blockSize 的值 2 决定的:digest<T>(T, InputStream) 实现内部会按照算法对象暴露的 blockSize(信息块长度,单位字节)从输入流中分块读取数据,每读到一块就调用一次 write(buffer) 增量更新摘要状态,直到流被读完。整个流程可概括为:

  1. 依据 blockSize 从 InputStream 分块 read 数据;
  2. 每块数据调用算法实例的 write(buffer) 增量更新;
  3. 流读取完毕(read 返回 0)后调用 finish() 生成最终摘要。

示例中的流构造链路也值得说明:

  • ByteBuffer(data):基于 Array<Byte> 构建的内存字节流,父类型为 IOStream & Seekable(见 io_package_classes.md),将原始字节数组包装为可读的流;
  • BufferedInputStream(byteBuffer):带缓冲区的输入流包装器,可将其他 InputStream 绑定进来并暂存到缓冲区(默认缓冲容量 4096),同样实现了 InputStream 接口,因此可以作为 digest 的第二个参数传入。

若实际使用真实算法(如 SHA256),其 blockSize 通常为 64 或 128 字节,输入流数据会被自动切成对应的信息块依次处理,调用方完全无需感知分块细节。

六、落到实战:与 stdx.crypto.digest 具体算法的配合

std.crypto.digest 只提供抽象接口与泛型入口,具体算法实现位于 stdx.crypto.digest 包(见 crypto_digest_package_overview.md),包含 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3 共 8 个算法类,它们全部声明为 <: Digest,因此天然满足 digest<T> 的泛型约束。例如:

public class SHA256 <: Digest {
    public init()
}

真实算法使用示例(SHA256)

以 sample_digest.md 中校验过的 SHA256 示例为参照,实际项目中可这样计算字符串的摘要:

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var sha256Instance = SHA256()
    sha256Instance.write(str.toArray())
    var md: Array<Byte> = sha256Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果(对 "helloworld"):

936a185caaa266bb9cbe981e9e05cb78cd732b0b3280eb944412bb6f8f8f07af

这里采用的是 write + finish 的成员函数调用方式;若改用本文介绍的 digest 泛型函数,只需将上述手动两步封装成一次调用:

import std.crypto.digest.*
import stdx.crypto.digest.*

main() {
    var str: String = "helloworld"
    let sha256Instance = SHA256()
    let md = digest<SHA256>(sha256Instance, str.toArray())
    // md 即摘要字节序列,可用 stdx.encoding.hex 的 toHexString 转成十六进制字符串
}

摘要结果默认是 Array<Byte>,展示时通常借助 stdx.encoding.hex 包的 toHexString(data: Array): String 转换为十六进制字符串,与各类常见摘要工具的展示形式一致。

各算法对同一输入 "helloworld" 的校验结果如下,可作为自测参照:

算法 十六进制摘要(helloworld)
MD5 fc5e038d38a57032085441e7fe7010b0
SHA1 6adfb183a4a2c94a2f92dab5ade762a47889a5a1
SHA224 b033d770602994efa135c5248af300d81567ad5b59cec4bccbf15bcc
SHA256 936a185caaa266bb9cbe981e9e05cb78cd732b0b3280eb944412bb6f8f8f07af
SHA384 97982a5b1414b9078103a1c008c4e3526c27b41cdbcf80790560a40f2a9bf2ed4427ab1428789915ed4b3dc07c454bd9
SHA512 1594244d52f2d8c12b142bb61f47bc2eaf503d6d9ca8480cae9fcf112f66e4967dc5e8fa98285e36db8af1b8ffa8b84cb15e0fbcf836c3deb803c13f37659a60
SM3 c70c5f73da4e8b8b73478af54241469566f6497e16c053a03a0170fa00078283

HMAC 的补充说明

HMAC 类同样实现 Digest 接口,构造时需传入密钥与算法类型(HashType),如 HMAC(key, HashType.SHA512)。其静态方法 HMAC.equal(mac1, mac2) 比较两个摘要时不采用短路比较,从而防止 timing attack 类型的时间侧信道攻击(见 digest_package_classes.md)。此外,与普通算法一样,HMAC 在调用 finish() 后也必须先 reset() 才能继续计算 —— 这与本文第三、五节强调的状态约束完全一致。

运行环境依赖:OpenSSL 3

stdx.crypto.digest 的算法实现基于 OpenSSL 3 的 crypto 动态库,使用前必须安装相应依赖(详见 crypto_digest_package_overview.md):

  • Linux:安装 OpenSSL 3 开发包,确保存在 libcrypto.so 与 libcrypto.so.3(如 Ubuntu 22.04 执行 sudo apt install libssl-dev);自编译安装时需将库目录加入 LD_LIBRARY_PATH 与 LIBRARY_PATH;
  • Windows:确保存在 libcrypto.dll.a(或 libcrypto.lib)与 libcrypto-3-x64.dll,并分别配置 LIBRARY_PATH 与 PATH 环境变量;
  • macOS:brew install openssl@3,确保存在 libcrypto.dylib 与 libcrypto.3.dylib。

若未安装或版本过低,程序运行时会抛出异常 CryptoException:Can not load openssl library or function xxx。CryptoException 是 crypto 包的通用异常类,定义于 digest_package_exceptions.md,支持无参构造与携带 message 字符串构造两种方式。

七、使用要点小结

  1. 数据源决定重载选择:一次性字节数据用 digest<T>(T, Array<Byte>);大体积或流式数据用 digest<T>(T, InputStream),可边读边算避免整段载入内存;digest<T>(T, String) 已废弃,字符串先 toArray() 再走字节数组重载;
  2. 算法对象必须实现 Digest:where T <: Digest 在编译期强约束,传入 stdx.crypto.digest 的 MD5、SHA 系列、SM3、HMAC 实例均可;
  3. 注意摘要对象状态机:finish() 之后对象不能再继续计算,必须 reset() 重置上下文;digest 泛型函数内部已封装好 write → finish 的调用流程;
  4. 输入流重载按 blockSize 分块:Digest 的 blockSize 属性决定分块粒度,流式处理时 write 会被多次调用;
  5. 环境前提:具体算法类依赖 OpenSSL 3 动态库,部署环境需按平台预先配置。

如需进一步阅读,可继续查阅 Digest 接口定义、stdx 算法类全集 以及 算法综合示例。

登录后查看全文
CangjieCorpus