sha3

密码学摘要

SHA3-224/256/384/512 与 SHAKE128/256。它们不是 Keccak-256、SHA-256、HMAC、密码哈希或签名接口。

公开函数

函数	合同
`version()`	包版本 1.0.0。
`hashHex(data, bits=256)` / `hashBytes(data, bits=256)`	bits 仅 224、256、384、512，小写 hex 或自然长度 Buffer。
`hash256Hex(data)` / `hash256Bytes(data)`	固定 SHA3-256 的便捷调用。
`shake128Hex(data, outLen=32)` / `shake256Hex(data, outLen=32)`	outLen 是字节数，hex 长度为两倍；零长度合法，不限制为 128 字节。
`shake128Bytes(data, outLen=32)` / `shake256Bytes(data, outLen=32)`	对应二进制输出 Buffer。
`hashFileHex(path, bits=256, maxInput=268435456, onProgress=null)`	UTF-8 路径，文件固定摘要。
`hashFileBytes(path, bits=256, maxInput=268435456, onProgress=null)`	文件摘要 Buffer。
`sha3Hasher(bits=256, maxInput=268435456)`	Sha3Hasher 流式对象。
`shakeHasher(strength=128, maxInput=268435456)`	ShakeHasher 对象，strength 仅 128、256。

所有 data 函数均有 string/Buffer 重载。文本按 UTF-8 字节处理；任意二进制与 NUL 使用 Buffer，空输入合法。无效参数不静默转为默认值。

流式快照与独立克隆

import sha3

auto h = sha3.sha3Hasher()
h.update("你")
h.update("好")
string digest = h.digestHex()
auto branch = h.clone()
branch.update("!")
assert h.inputBytes == uint64(6)
h.reset()

update(string|Buffer) 追加数据，inputBytes 为 uint64， valid 只表示句柄非空。clone() 创建独立状态； reset() 返回 bool，清空输入与失败状态，保留算法和预算。

Sha3Hasher 的 digestHex(outLen=0) / digestBytes(outLen=0) 默认选择自然长度，显式长度必须精确匹配 28/32/48/64 字节。 ShakeHasher 的默认输出为 32 字节，允许零与更长输出。每次 digest 都是非终结快照，重复结果为同一前缀，不是推进游标的 squeeze。

update 失败不会部分接收输入，后续 update/digest/clone 失败直到 reset。 digest 参数错误不使流失效。独立对象可以并发，共享可变对象需要串行访问。

文件、回调与错误

string digest = sha3.hashFileHex("data.bin",
    onProgress = func(int current, int total, int output) as bool
        return true
    end)

同步回调每块最多 64 KiB，EOF 另通知一次，空文件也通知； current/total 是字节数，未知总长为零，output 恒为零。最后一次 current 可能重复，uint64 计数转换为公开 int 前检查范围。回调可嵌套独立操作，返回 false 抛 CancelledError，EOF 通知也可取消。回调异常保留类别与说明，失败不交付部分摘要。

参数错误为 ValueError，范围/预算错误为 RangeError，分配失败为 MemoryError；文件错误保留 XRT 类别。路径使用 XRT UTF-8 API。预算不是超时控制，不承诺并发修改文件时的快照一致性。

maxInput 必须大于零，默认 256 MiB。分配型输出使用 XRT 默认 512 MiB 预算； hex 临时工作区约为 3*outLen+1 字节，还存在宿主结果复制，不建议盲目分配到上限。

C 接口与所有权

include/xrt_sha3.h 提供 Hash/ShakeHash、OptionsInit/ErrorInit、DigestSize、 HasherCreate/ShakeHasherCreate/Update/CheckOutput/Digest/Clone/Reset/InputBytes/OutBytes/Error/Destroy 和 File。公开 C 核心独立于 xlang/xruntime；XRT 宿主只使用一份实现，在首次包含 XRT 前配置模块。

C 固定摘要输出要求自然长度；SHAKE 零字节可传 NULL。调用方保证输出空间，核心一次性函数不人为限制为分配型接口的 512 MiB。 Options/ResourceLimits 严格验证大小与版本，C 显式零限额表示无业务上限，仍检查累计溢出。

File 借用 Reader，从当前游标读，不回退、不销毁；已知剩余长度可预检，未知长度逐块检查。最终回调成功后才提交摘要，Reader/回调的原始错误优先。

include/sha3_native.h 定义 25 个薄绑定入口。 hex 借用 XRT 临时区，清理/回退后失效，不会被正常后续调用覆盖； Buffer 归调用者所有，C 调用 xrtBufferDestroy，xlang 自动接管。零输出也是合法空串，C 必须查看 XRT 错误区分失败。 adopt 只接受真实句柄并转移所有权，不允许重复接管或伪造指针。

双语范例与验证边界

examples/extlibs/sha3_basic.xl 与 extlibs/sha3/examples/basic.c， examples/extlibs/sha3.xl 与 extlibs/sha3/examples/files.c 分别展示算法、二进制、流状态，以及中文路径、进度、取消、异常和预算，逐行对照固定输出。

tools/check_extlib_sha3.ps1 检查 546 组独立 OpenSSL 边界向量、 8 种地址偏移、12 组已知答案、短输入全切点、23 个生成声明、25 个 native 入口、 176 个分配故障位置、四线程独立对象、文件回调和 C/xlang JIT/AOT/GCC。 tools/check_extlib_sha3.sh 检查 Linux C ASan/UBSan/泄漏及范例输出。门禁绑定输入文件集合和哈希，Node/OpenSSL 仅用于测试答案生成，不是运行依赖。

实现是仓库已有的本地可移植算法，不伪称官方上游发行版。测试不等于 FIPS 认证、独立密码学审计、Linux xlang、大端、32 位/ARM、共享对象并发或吞吐性能验收，也不承诺敏感数据安全擦除。