密码摘要接口规范 0.2.0

本包提供 SHA-256 摘要与尽力恒时的文字比较。它只做摘要与比较，不宣称密码存储或消息认证的安全语义；盐、口令派生和凭据寿命仍由使用者另行处理（口令派生见[口令派生](../口令派生/规范.汉语.md)）。

摘要

摘要SHA256十六进制 对输入字符串的原始 UTF-8 字节计算 SHA-256，返回恰好 64 个 ASCII 小写十六进制字符，不加前缀、盐或换行。摘要SHA256字节十六进制 对任意字节串（可含零字节，不按文字解释）做同样的计算，返回同样形态的 64 个字符；对同一段字节，两个函数的结果必然相同。相同输入在浏览器、CF Worker、Node.js 和原生适配中必须得到相同结果。空输入有效。输入不得超过 16 MiB（宿主值桥的交换上限），超过或宿主密码原语失败时调用失败，抛出豫言异常。

恒时相等文字

恒时相等文字 比较两个字符串的 UTF-8 字节，相同返回阳，不同返回阴。长度（按字节）不同时直接返回阴——允许泄露长度；长度相同时遍历全部字节累计差异，循环次数只取决于长度，不因第一个差异提前退出，也没有依赖字节值的分支（差异以平方累加，全部为零才算相等）。它用于比较令牌、摘要等秘密值，避免用逐字符比较造成的提前退出时序差异。

这是尽力恒时的豫言实现：它不使用任何宿主的专有函数（如 Workers 的 timingSafeEqual），编译器与宿主不保证严格的恒时。需要严格恒时保证的场合应在宿主层做同类比较。

一致性样例

• 摘要SHA256十六进制 "abc" 与 摘要SHA256字节十六进制 "abc" 的 UTF-8 字节 都是 ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad；空输入得 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。
• 摘要SHA256字节十六进制 对 00 ff 01 fe 00 00 80 7f 00 与对 0 到 255 的全部字节值，分别与标准实现一致。
• 恒时相等文字 "" "" 为阳；"abc" "abc" 为阳；"abc" "abd"、"abc" "Abc"、"abc" "abcd"、"" "a" 为阴；汉字文相同为阳、差一字为阴；字节数相同而内容不同（如 甲 与 abc）为阴。

边界

本包不提供 HMAC、其他散列算法、盐或口令存储；不保证 恒时相等文字 抵御微架构层面的侧信道。