siphash

带密钥哈希

SipHash-2-4，64 位与独立域分离的 128 位摘要。用于短消息带密钥哈希和哈希表抗碰撞，不是加密、密码存储或签名接口。

函数与输入

API	返回值与合同
`version()` / `SIPHASH_KEY_LEN`	包版本 1.0.0 / 密钥长度 16 字节。
`hash64(data, key)`	uint64，保留最高位，不用 int 接收。
`hash64Hex(data, key)` / `hash64Bytes(data, key)`	16 字符小写 hex / 8 字节 Buffer。
`hash128Hex(data, key)` / `hash128Bytes(data, key)`	32 字符小写 hex / 16 字节 Buffer。
`hashFile64(path, key, maxInput=268435456, onProgress=null)`	uint64，UTF-8 路径。
`hashFile64Hex(...)` / `hashFile64Bytes(...)`	相同参数，64 位文件摘要。
`hashFile128Hex(...)` / `hashFile128Bytes(...)`	相同参数，128 位文件摘要。
`hasher(key, maxInput=268435456)`	SipHasher 流式对象。

data/key 各自支持 string 或 Buffer，一次性函数的四种组合全部可用。文本按 UTF-8 字节计数，二进制及 NUL 用 Buffer。密钥必须恰好 16 字节，不填零、不截断、不提供默认密钥。真实用途需要保密的随机密钥，范例的固定密钥仅用于复现。

hex 和 Buffer 是小端摘要字节序列，不是直接格式化 uint64 数值。 128 位结果不能由两个 64 位结果拼接得到。

流式快照

import siphash
string key = "0123456789abcdef" // 仅用于范例
auto h = siphash.hasher(key)
h.update("你")
h.update("好")
assert h.inputBytes == uint64(6)
string tag = h.digest128Hex()
auto branch = h.clone()
branch.update("!")
h.reset()

update(string|Buffer)、digest64()、 digest64Hex()、digest64Bytes()、 digest128Hex()、digest128Bytes()、 clone()、reset()、inputBytes 和 valid。

create 复制密钥；digest 为非终结快照，可重复读后继续 update； clone 为独立状态；reset 保留密钥和预算，清空输入与失败状态。 update 失败后需要 reset，不能把不完整输入当作成功摘要。 valid 只表示句柄非空。独立对象可并发，同一个可变对象需要调用方串行访问。

文件、回调与预算

string tag = siphash.hashFile128Hex("data.bin", key,
    onProgress = func(int current, int total, int output) as bool
        return true
    end)

同步回调在每块（最多 64 KiB）和 EOF 时触发；空文件也通知。 current/total 按字节，未知 total 为零，output 恒为零；最终 current 可能重复。公开 int 计数有溢出检查。返回 false 抛 CancelledError，最终回调也可以取消；抛错保留原始类型和消息，回调可重入独立操作。失败不提交部分摘要。

maxInput 必须大于零，默认 256 MiB。参数错误为 ValueError，预算/计数范围为 RangeError，分配失败为 MemoryError，句柄错误为 StateError；文件与回调错误保留原始类型。预算不是超时控制，不打断阻塞读取，也不承诺文件被并发修改时的快照一致性。

C API 与所有权

include/xrt_siphash.h 提供 OptionsInit、ErrorInit、Hash64、Hash128、 HasherCreate/Update/Digest64/Digest128/Clone/Reset/InputBytes/Error/Destroy、 File64/File128。64 位算法直接复用 XRT；核心独立于 xlang/xruntime，宿主只编译一份 XRT，首次包含前配置模块。

C key 指针要求至少 16 字节可读，输出空间由调用方保证。 0 可以是合法数值摘要，必须用 XRT 错误状态区分失败。 Options/Limits 严格检查大小和版本，NULL 使用默认预算， C 显式零限额表示不设业务上限，累计溢出仍会报错。

File 借用 Reader，从当前游标读，不回退、不销毁。能获知剩余长度时预检，否则逐块检查；最终回调成功后才交付摘要。

include/siphash_native.h 为 43 个薄绑定入口给出精确声明。 hex 借用 XRT 临时区，清理/回退前有效，后续正常调用不会覆盖； Buffer 为独立所有权，C 用 xrtBufferDestroy，xlang 自动接管。 adopt 只接受真实句柄并转移所有权，不允许重复接管。

双语范例与验证范围

examples/extlibs/siphash_basic.xl 对照 extlibs/siphash/examples/basic.c，展示单次哈希、UTF-8、二进制、流式分支；examples/extlibs/siphash.xl 对照 extlibs/siphash/examples/files.c，展示中文路径、回调、取消、异常与预算。

tools/check_extlib_siphash.ps1 检查 128 个上游已知答案、 4 种密钥 x 8 种地址偏移 x 81 种长度、短输入全切点、百万字节输入、全部 43 个 native API 和 41 个生成声明、4 线程独立对象、 192 个分配故障位置、C/xlang JIT/AOT/GCC 及双语范例。 tools/check_extlib_siphash.sh 检查 Linux C ASan/UBSan/泄漏及范例输出。

范例摘要由固定版本上游参考实现独立产生并由门禁复核，参考代码只用于测试，不进入运行库。 128 位核心为本地维护实现，不伪称未改动的上游发行版。

门禁冻结输入集合与哈希，实际结果见仓库带日期记录。这些测试不是密码学认证、独立安全审计、吞吐性能测试、Linux xlang、大端、32 位/ARM 或同一对象并发认证；销毁对象擦除堆状态，不承诺擦除调用方密钥及所有临时副本。