hashlib4cj 统一哈希 API 深度解析:IHash 接口与 HashResult 设计实战指南

原创2026-10-14 22:37:081,178 阅读
文章标签:密码学

hashlib4cj 统一哈希 API 深度解析:IHash 接口与 HashResult 设计实战指南

hashlib4cj 是一个用仓颉(Cangjie)语言实现的哈希算法库,内置 80+ 种哈希函数。本文以官方 API 文档 doc/feature_api.md 为骨架,结合 src/ihash.cj、src/hash.cj、src/hashresult.cj 等源码实现与 HLT 测试用例,系统讲解其核心抽象接口 IHash 与结果类型 HashResult 的设计。读完本文,你将掌握一次性哈希计算、增量哈希计算、流/文件哈希处理、多类型输入输出的统一转换规则,以及如何在 cjpm.toml 中引入依赖并写出可运行的哈希计算代码。

一、API 总览:一套接口,覆盖全部哈希算法

hashlib4cj 的设计核心在于统一抽象:无论底层是加密哈希(Keccak、RIPEMD、Whirlpool、GOST)、非加密哈希(Murmur、FNV、SipHash)还是校验和(CRC、Adler-32),上层都通过同一个接口 IHash 对外提供服务,计算结果统一封装为 HashResult。这种设计让调用方无需关心具体算法的内部状态机,只需掌握 compute*(一次性)与 transform*(增量)两组方法即可。

从源码看,接口定义的成员分为三大类:

  1. 只读属性:name、blockSize、hashSize,用于描述算法的元信息;
  2. 一次性哈希计算:compute* 系列,一次调用即返回 HashResult;
  3. 增量哈希计算:transform* 系列配合 transformFinal(),可分段喂入数据后统一收尾。

此外,src/ihash_info.cj 中还有 IHash32 <: IHash、IHash64 <: IHash、IHash128 <: IHash、ICrypto <: IHash & IBlockHash、IHMAC 等细分接口,用于按位宽、按加密属性对算法族分类,但它们的公共行为全部继承自 IHash。

二、IHash 接口详解

2.1 接口定义原文

接口完整定义如下(与 src/ihash.cj 一致):

public interface IHash {
    prop name: String
    prop blockSize: Int64
    prop hashSize: Int64

    // 初始化
    func initialize(): Unit

    /*一次性哈希计算*/
    func computeAny(data: Any): HashResult
    func computeByte(data: Byte): HashResult
    func computeBool(data: Bool): HashResult
    func computeRune(data: Rune): HashResult
    func computeStringUTF8(data: String): HashResult
    func computeInt16(data: Int16): HashResult
    func computeInt32(data: Int32): HashResult
    func computeInt64(data: Int64): HashResult
    func computeUInt16(data: UInt16): HashResult
    func computeUInt32(data: UInt32): HashResult
    func computeUInt64(data: UInt64): HashResult
    func computeFloat32(data: Float32): HashResult
    func computeFloat64(data: Float64): HashResult
    func computeRunes(data: Array<Rune>): HashResult
    func computeBytes(data: Array<Byte>): HashResult
    func computeInt16s(data: Array<Int16>): HashResult
    func computeInt32s(data: Array<Int32>): HashResult
    func computeInt64s(data: Array<Int64>): HashResult
    func computeUInt16s(data: Array<UInt16>): HashResult
    func computeUInt32s(data: Array<UInt32>): HashResult
    func computeUInt64s(data: Array<UInt64>): HashResult
    func computeFloat32s(data: Array<Float32>): HashResult
    func computeFloat64s(data: Array<Float64>): HashResult
    func computeStream(data: IOStream, length!: Int64): HashResult
    func computeFile(fileName: String, from: Int64, length: Int64): HashResult
    func computeFileFromPath(fileName: Path, from: Int64, length: Int64): HashResult

    /*增量哈希计算*/
    /*结束计算,返回计算的结果*/
    func transformFinal(): HashResult
    func transformBytes(data: Array<Byte>): Unit
    func transformBytes(data: Array<Byte>, index: Int64): Unit
    func transformBytes(data: Array<Byte>, index: Int64, length: Int64): Unit
    func transformAny(data: Any): Unit
    func transformByte(data: Byte): Unit
    func transformBool(data: Bool): Unit
    func transformRune(data: Rune): Unit
    func transformStringUTF8(data: String): Unit
    func transformInt16(data: Int16): Unit
    func transformInt32(data: Int32): Unit
    func transformInt64(data: Int64): Unit
    func transformUInt16(data: UInt16): Unit
    func transformUInt32(data: UInt32): Unit
    func transformUInt64(data: UInt64): Unit
    func transformFloat32(data: Float32): Unit
    func transformFloat64(data: Float64): Unit
    func transformRunes(data: Array<Rune>): Unit
    func transformInt16Array(data: Array<Int16>): Unit
    func transformInt32s(data: Array<Int32>): Unit
    func transformInt64s(data: Array<Int64>): Unit
    func transformUInt16s(data: Array<UInt16>): Unit
    func transformUInt32s(data: Array<UInt32>): Unit
    func transformUInt64s(data: Array<UInt64>): Unit
    func transformFloat32s(data: Array<Float32>): Unit
    func transformFloat64s(data: Array<Float64>): Unit
    func transformStream(data: IOStream, length!: Int64): Unit
    func transformFile(fileName: String, from: Int64, length: Int64): Unit
    func transformFile(fileName: Path, from: Int64, length: Int64): Unit
}

2.2 三个元信息属性

  • name:返回算法类名,由 src/hash.cj 中通过 TypeInfo.of(this).name 反射得到;
  • hashSize:摘要字节数(即 HashResult 的字节长度);
  • blockSize:底层算法一次处理的数据块字节数。

块类哈希的这两个值在基类构造时注入,例如 src/crypto/sha3/keccak/keccak_base.cj 中 Keccak 的 hashSize 取 HashSize 枚举对应值、blockSize 为 200 - hashSize * 2(对应标准海绵结构速率 rate)。位宽枚举定义在 src/hash_size.cj 中:

public enum HashSize {
    | HashSize128
    | HashSize160
    | HashSize192
    | HashSize224
    | HashSize256
    | HashSize384
    | HashSize512
    public func getInt(): Int64 {
        match (this) {
            case HashSize128 => 16
            case HashSize160 => 20
            case HashSize192 => 24
            case HashSize224 => 28
            case HashSize256 => 32
            case HashSize384 => 48
            case HashSize512 => 64
        }
    }
}

2.3 initialize():复用实例前必须重置

initialize() 用于将哈希对象恢复到初始状态。以 src/hash.cj 的 computeBytes 为例,完整生命周期是:

initialize()      // 1. 重置内部状态
transformBytes(data)  // 2. 喂入数据
let result = transformFinal()  // 3. 收尾并取结果
initialize()      // 4. 再次重置,便于复用

因此同一个哈希实例可以被反复调用 compute* / transform*,无需每次重新 new。

三、一次性哈希计算:compute 系列

3.1 标量输入

computeByte、computeBool、computeRune、computeInt16/32/64、computeUInt16/32/64、computeFloat32/64、computeStringUTF8 分别接受对应标量类型。其实现均收敛为“先转字节数组,再调用 computeBytes”,例如:

public func computeByte(data: Byte): HashResult {
    let temp: Array<Byte> = [data]
    return computeBytes(temp)
}

3.2 数组输入

computeBytes、computeRunes、computeInt16s、computeInt32s、computeInt64s、computeUInt16s、computeUInt32s、computeUInt64s、computeFloat32s、computeFloat64s 接受 Array 类型,内部通过 src/toolkit/bit_converter.cj 的 convertInt16sToBytes、convertUInt32sToBytes 等函数批量转换为字节。

3.3 类型统一转换规则(重要)

无论标量还是数组,所有类型最终都经过 convertToBytes / getBytes 按**小端(Little Endian)**写入字节(见 src/toolkit/bit_converter.cj):

  • Bool:true → [1],false → [0];
  • Rune / 各整数 / 浮点数:按位宽写入小端字节,例如 Float32 写 4 字节、Float64 写 8 字节;
  • String:value.toArray() 得到 UTF-8 字节序列。

特别注意:README 的“特别说明”提醒,参考项目 HashLib 中字符串默认按 UTF-16 编码,因此直接使用 String 相关 API(computeStringUTF8 / transformStringUTF8)计算哈希时,结果与参考项目不同。这是本项目有意为之的设计,跨语言对比摘要值时务必注意编码约定。

3.4 computeAny / transformAny:多态分发

computeAny(data: Any) 在 src/hash.cj 中通过 match 按运行时类型自动分发到对应 compute* 方法,transformAny 同理(src/hash.cj)。若类型不支持,抛出 Exception("unsupport data type ...")。这一设计让上层业务可以传入任意受支持类型而无需手写分支。

四、增量哈希计算:transform 系列

当数据是分片到达(如网络包、大文件流式读取)时,可使用增量模式:

import hashlib4cj.crypto.Gost

main(): Unit {
    let gost = Gost()
    gost.transformInt8(4)
    gost.transformStringUTF8("hashlib4cj")
    let res1 = gost.transformFinal()
    println(res1)
}

执行结果为:

2DC3ED61D86DEB390588C495A33A01C0859745F64E725E0CBBEE72F0E6D04A44

要点:

  • transformBytes(data) / transformBytes(data, index) / transformBytes(data, index, length) 支持按偏移与长度喂入子区间;index < 0 或剩余长度非法时会抛出异常(见 src/hash.cj);
  • transformFinal() 结束计算并返回 HashResult,之后内部自动重置;
  • 增量喂入与一次性计算结果必须一致,这正是 HLT 测试 testMultipleTransformsWithRandomData 的核心断言(见 src/test/HLT/hashes_hlt_base_test.cj):把随机数据拆成多段 transformBytes,与整体 computeBytes 的 HashResult 用 @Expect 比对相等。

五、HashResult:统一的结果类型

5.1 构造与输出 API 原文

public class HashResult {
    public init(data: UInt32)
    public init(data: Int32)
    public init(data: UInt64)
    public init(data: Int64)
    public init(data: Array<Byte>)
    /*多种输出*/
    public func getBytes(): Array<Byte>
    public func getUInt32(): UInt32
    public func getInt32(): Int32
    public func getUInt64(): UInt64
    public func getInt64(): Int64
    public func toString(): String
    public func equals(other: HashResult): Bool
    public operator func ==(rhs: HashResult): Bool
    public func clone(): HashResult
    public func getHashCode(): Int64
}

5.2 实现细节(src/hashresult.cj)

HashResult 内部仅持有一个 Array<Byte>,构造时:

  • 传入 UInt32 / Int32 / UInt64 / Int64:通过 convertToBytes 转换为小端字节序列;
  • 传入 Array<Byte>:直接引用该字节数组。

输出时:

  • getBytes() 返回原始字节数组;
  • getUInt32() / getInt32() / getUInt64() / getInt64() 使用 readLittleEndian 从字节序列按小端解析出数值——对 32 位哈希(如 AP、BKDR)取前 4 字节,对 64 位哈希取前 8 字节;
  • toString() 将字节转换为大写十六进制字符串(toHexString(hash).toAsciiUpper()),因此打印出的摘要均为大写字母形式;
  • equals(other) 与运算符重载 == 均按字节序列逐位比较,HashResult 实现了 Equatable<HashResult> 与 ToString;
  • clone() 返回一份相同字节序列的新实例;
  • getHashCode() 基于 Base64 编码串的 hashCode() 生成,便于在哈希表等容器中使用。

HLT 测试 src/test/HLT/hashresult_test.cj 用随机字节验证了 getBytes() 与 getUInt32() / getUInt64() 小端读取的一致性。

六、流与文件的哈希计算

6.1 computeStream / transformStream

接口中 length 参数带 ! 标记表示命名参数(有默认值),默认 -1 表示读取到流末尾;传入非负值时只处理指定长度的字节。在 src/hash.cj 的实现中:

  • 若流是 Seekable 且 position + length > length,抛出 Exception("The length is greater than the file size");若当前位置已到末尾则直接返回;
  • 读取端协程 readerSpawn 按 Hash.BUFFER_SIZE 分块读取并放入 BlockingQueue<Array<Byte>>;
  • 计算端协程 hasherSpawn 从队列取块调用 transformBytes,实现读与算并行的流水线处理。

Hash.BUFFER_SIZE 定义于 src/hash.cj:public static var BUFFER_SIZE: Int64 = 64 * 1024(默认 64 KiB)。HLT 测试 testHashStream 会分别以 blockSize=26 与 blockSize=BUFFER_SIZE 两种缓冲尺寸,用 1~BUFFER_SIZE*20+511 等 22 种长度验证 computeStream 与 computeBytes 结果一致,并断言超长/超界读取会抛异常(见 src/test/HLT/hashes_hlt_base_test.cj)。

6.2 computeFile / transformFile

computeFile(fileName: String, from: Int64, length: Int64) 与 computeFileFromPath(fileName: Path, ...) 用于直接对文件做一次性哈希;transformFile 支持在增量计算中嵌入文件片段。实现(src/hash.cj):

public func computeFile(fileName: String, from: Int64, length: Int64): HashResult {
    initialize()
    transformFile(fileName, from, length)
    let result = transformFinal()
    initialize()
    return result
}

参数语义:

  • from:文件内起始偏移(SeekPosition.Begin(from)),可用于只校验文件的某一段;
  • length:需要处理的字节数,-1 表示从 from 读到文件末尾;
  • 底层复用 transformStream 的并行流水线。

testHashFile(src/test/HLT/hashes_hlt_base_test.cj)验证了“文件整体计算 == 内存 computeBytes”、“transformBytes 分段 + transformFile 片段 + transformBytes 收尾 == 整体一次性计算”两条等价性。

七、实现类如何接入 IHash

7.1 两条实现路径

从源码结构看,具体算法通过两个抽象基类接入 IHash:

  • 块哈希:src/blockhash.cj 的 BlockHash <: Hash & IBlockHash,内部维护 HashBuffer 缓冲(src/hashbuffer.cj),数据先填满缓冲区再调用子类的 transformBlock,transformFinal 时先 finish() 再 getResult()。加密哈希如 Echo256(super(HashSize256))即走此路径。
  • 非块哈希:src/multiple_transform_nonblock.cj 的 MultipleTransformNonBlock <: Hash & INonBlockHash,把多次 transformBytes 的输入先聚合(aggregate)成一段连续字节,再一次性 computeAggregatedBytes。例如 32 位哈希 AP(super(4, 1))、Murmur2 均属于此类。

7.2 IFastHash32:免装箱的快速路径

IHash32 的若干实现(如 Murmur2)还实现了 src/ihash_info.cj 中的 IFastHash32,直接返回 Int32 而非 HashResult,并提供 computeStringFast、computeBytesFast 等针对标量/数组的快速重载,适合高频散列场景,避免构造结果对象。

八、完整实战:从引入依赖到运行

8.1 引入依赖

在 cjpm.toml 的 [dependencies] 中添加:

hashlib4cj = { git = "https://gitcode.com/FriskKA/hashlib4cj", branch = "main" }

然后在控制台执行:

cjpm update

8.2 编译构建

cjpm build

当前项目 cjpm.toml 中声明 cjc-version = "0.58.3",README 约束支持仓颉版本 0.58.3。

8.3 基本计算示例

对字符串做一次性哈希(UTF-8 编码):

import hashlib4cj.crypto.sha3.echo.Echo256

main(): Unit {
    let echo = Echo256()
    let res = echo.computeStringUTF8("hashlib4cj")
    println(res)
}

执行结果(toString() 的大写十六进制输出):

40484FF47B824758E508AB20C478008738569B2BC6DF3C5745285B31A58A36F3

8.4 多类型输出示例

HashResult 支持多种输入与输出,可将摘要按小端解析为数值:

import hashlib4cj.crypto.Gost

main(): Unit {
    let gost = Gost()
    let res = gost.computeInt32(4)
    println(res.getInt64())
}

执行结果:

-3174266761618810304

九、测试与正确性保障

仓库以双层测试体系保障 API 行为:

这意味着对任何实现了 IHash 的新算法,只要通过这套测试模板,其一次性/增量/流/文件四种计算路径的一致性即得到保证。

十、小结

IHash + HashResult 构成了 hashlib4cj 的统一 API 骨架:compute* 提供零门槛的一次性计算,transform* + transformFinal() 提供大数据的增量与流式处理,HashResult 屏蔽了各算法输出位宽的差异,提供字节、整数与十六进制字符串三种视图。理解这套接口,即可在仓颉项目中自由组合 80+ 种哈希算法,并安全地在一次性、增量、流、文件四种场景间切换。

登录后查看全文
hashlib4cj