blake2

哈希校验

BLAKE2b/BLAKE2s 的字节、UTF-8 文本、文件和增量接口。内嵌便携 C 实现，复用宿主 XRT/xruntime，不需要额外 BLAKE2 DLL。

一次性与文件 API

下表的 b/s 分别对应 blake2b 和 blake2s 两组函数。BLAKE2b 默认摘要 64 字节、范围 1..64； BLAKE2s 默认 32 字节、范围 1..32。十六进制结果为小写，字符数量是摘要字节数的两倍。

函数	参数与返回
`version()`	返回内置实现的版本字符串。
`blake2b/sHashHex(data, digestSize)`	data 为 Buffer 或 string，返回 string。
`blake2b/sHashBytes(data, digestSize)`	相同输入，返回独立拥有型 Buffer。
`blake2b/sKeyedHex(data, key, digestSize)`	两个 Buffer 或两个 string，返回 string。
`blake2b/sKeyedBytes(data, key, digestSize)`	相同输入，返回独立拥有型 Buffer。
`blake2b/sFileHex(path, maxInput, digestSize, onProgress)`	读取 UTF-8 路径的文件，返回 string。maxInput=268435456，onProgress=null。

文本及密钥按 UTF-8 字节计算；任意二进制使用 Buffer。BLAKE2b 密钥上限为 64 字节， BLAKE2s 为 32 字节，超过上限报错，不截断；空密钥等价于未使用密钥。 keyed hash 是原生 MAC，不是 HMAC，也不是口令存储的密码派生函数。

公开常量：BLAKE2B_OUT_LEN、BLAKE2S_OUT_LEN、 BLAKE2B_KEY_MAX、BLAKE2S_KEY_MAX。短摘要是独立初始化参数，不是完整摘要的前缀截断。

增量对象

blake2b/sHasher(digestSize, maxInput=268435456) 创建无密钥对象， blake2b/sKeyedHasher(Buffer key, digestSize, maxInput=268435456) 创建持有密钥副本的对象。对应类为 Blake2bHasher、Blake2sHasher、Blake2bKeyedHasher、Blake2sKeyedHasher。

成员	合同
`update(Buffer\|string)`	追加输入，空输入有效。
`digestHex()` / `digestBytes()`	读取快照，不结束状态；摘要长度由构造确定，没有额外长度参数。
`inputBytes` / `valid`	成功接收的输入字节数，以及句柄是否非空。
`clone()`	独立的增量状态，后续输入不影响原对象。
`reset() as bool`	清除数据及失败状态，保留摘要长度、密钥和限额，成功返回 true。

import blake2

auto hash = blake2.blake2bHasher(16)
hash.update("ab")
auto branch = hash.clone()
hash.update("c")
branch.update("d")
assert hash.digestHex() == blake2.blake2bHashHex("abc", 16)
println(blake2.blake2bKeyedHex("你好 xlang", "密钥", 16))

update 的参数或限额失败后，需要 reset 才能继续使用；失败的输入不增加计数。不同对象可独立运行，同一个可变对象须串行访问。对象析构释放并清零自己的密钥和状态，不承诺擦除调用方副本、寄存器或系统交换页。

进度与错误

可选回调类型为 (func(int, int, int) as bool)?，参数依次为 inputBytes、 totalBytes、outputBytes；均按字节，未知总长为 0，outputBytes 恒为 0。每块输入通知一次，最后再通知一次；空文件也通知完成。

string digest = blake2.blake2sFileHex("data.bin",
    onProgress = func(int inputBytes, int totalBytes, int outputBytes) as bool
        return true
    end)

回调同步执行，可以嵌套另一独立哈希。返回 false 抛 CancelledError；回调异常保留原类型和消息。读取文件只借用输入，不修改源文件；失败或取消不会返回部分摘要。读取期间不提供防止其他进程修改文件的一致性快照。

非法摘要/密钥长度为 ValueError；输入超限为 RangeError；分配失败为 MemoryError。
打开失败沿用 XRT FileError，读取失败为 IOError；clone 失败状态对象为 RuntimeError。
xlang 工厂及文件接口要求 maxInput 为正，默认 256 MiB；这是累计字节限额，不是 CPU 时间预算。

C API 与范例

核心头为 include/xrt_blake2.h，薄绑定头为 include/blake2_native.h。 xrtBlake2OptionsInit 初始化版本化配置；xrtBlake2b/sHash 写入调用方缓冲。 HasherCreate/Update/Digest/Reset/Clone/Destroy 提供相同增量语义。

C Digest 的长度必须等于 HasherDigestSize。File 借用 reader，从当前游标读到 EOF，不接管 reader 寿命。核心输入限额为零时关闭业务限制，但仍检查计数溢出。模块选择应在首次包含 XRT 前完成，依赖见包清单。

薄绑定 char* 借用当前 XRT 临时区，清理或回退后失效；长期保留需复制。返回 Buffer 由调用方 xrtBufferDestroy。接管同一个句柄多次会破坏所有权，不允许重复 adopt。

教学：examples/extlibs/blake2.xl。对照： examples/extlibs/blake2_basic.xl 与 extlibs/blake2/examples/basic.c，共同预期输出位于 examples/extlibs/blake2_basic.expected.txt。

验证范围

2026-09-27 Windows 固定输入门禁包含 36 项检查：216 条 hashlib 已知答案、38 个实际生成原型、 C/xlang JIT/AOT/GCC、回调异常/取消、reader、16 个分配失败点、四线程独立结果与错误状态、双语黄金输出。

独立 Linux C 使用 ASan/UBSan 和泄漏检查。门禁为 tools/check_extlib_blake2.ps1 与 tools/check_extlib_blake2.sh；不代表 Linux xlang JIT/AOT、32 位/ARM、共享对象并发或性能基准已验收。当前 API 不含 salt/personalization、树模式或 SIMD 加速，也不宣称密码学审计认证。