跳至主要內容

TypeScript 数据、编码与错误

TypeScript 数据、编码与错误

密码 API 处理的是字节。字符串只是输入或传输层表示；在写算法调用前，先为每个字段确定“文本还是二进制”和“Hex 还是 Base64”。

何时使用哪种类型

数据应用层类型字符串解释示例
订单、用户标识、AADstringUTF-8order=...、merchant@gmkit.cn
文件、图片、压缩包、协议帧Uint8Array不经过文本编解码00 ff 80 41
key、IV、nonce、公私钥API 指定的 string | Uint8Array字符串按 Hex16 字节 key 写成 32 个 Hex 字符
密文、签名、tagstring | Uint8Array由 InputFormat/OutputFormat 指定数据库存 Base64，调用时写 InputFormat.BASE64

stringToBytes 与 bytesToString 只用于 UTF-8 文本。任意二进制经过 bytesToString 后可能出现替换字符，不能再无损还原；这类数据直接保留为 Uint8Array。

编码、解码和失败比较

下面的文件由文档测试直接执行。它同时覆盖不可打印字节、UTF-8、显式编码、非法输入和认证值比较。

// 1. 准备二进制：该字节序列包含 NUL、非 ASCII 字节和字母 A。
const binary = Uint8Array.of(0x00, 0xff, 0x80, 0x41);

// 2. 编码二进制：协议字段分别输出为小写 Hex 和 RFC 4648 Base64。
const hex = encodeOutput(binary, OutputFormat.HEX);
const base64 = encodeOutput(binary, OutputFormat.BASE64);
assert.equal(hex, '00ff8041');
assert.equal(base64, 'AP+AQQ==');

// 3. 显式解码：接收方按协议声明的格式恢复相同字节。
assert.equal(constantTimeEqual(decodeInput(hex, InputFormat.HEX), binary), true);
assert.equal(constantTimeEqual(decodeInput(base64, InputFormat.BASE64), binary), true);

// 4. UTF-8 往返：文本转换与任意二进制转换分开处理。
const plaintext = '订单 GMKIT-DEMO-0001';
assert.equal(bytesToString(stringToBytes(plaintext)), plaintext);
assert.equal(bytesToHex(hexToBytes(hex)), hex);
assert.equal(bytesToBase64(base64ToBytes(base64)), base64);

// 5. Hex 边界：奇数长度会在高位补 0；非 Hex 字符必须被拒绝。
assert.equal(bytesToHex(hexToBytes('abc')), '0abc');
assert.throws(() => decodeInput('00xz', InputFormat.HEX));

// 6. 比较失败断言：长度相同但内容不同的认证值必须返回 false。
const tampered = Uint8Array.from(binary);
tampered[3] ^= 0x01;
assert.equal(constantTimeEqual(binary, tampered), false);

0.10.1 的 Hex 边界

  • hexToBytes('abc') 按 0abc 处理，这是已发布兼容行为。
  • 非 Hex 字符会抛出 Error。
  • bytesToHex 始终输出小写、不带 0x。
  • 跨系统协议应要求偶数长度；不要利用奇数长度补零行为定义新格式。

显式编码

API输入输出默认值
decodeInput(data, inputFormat)Hex/Base64 字符串或原始字节Uint8ArrayinputFormat = InputFormat.HEX
encodeOutput(bytes, outputFormat)Uint8Array编码字符串outputFormat = OutputFormat.HEX
hexToBytes / bytesToHexHex 与字节对应另一种表示无
base64ToBytes / bytesToBase64Base64 与字节对应另一种表示无

主手册要求协议字段同时固定值和编码；接收端按照 schema 指定的格式解码，不根据内容猜测。例如：

{
  "ciphertext": "W2...",
  "encoding": "base64"
}

随机源

configureRNG('strict') 的作用是：系统和调用方都没有提供 CSPRNG 时抛错。它不会创建随机源，也不会证明宿主随机源质量。

环境/配置0.10.1 行为接入要求
浏览器有 crypto.getRandomValues使用 Web Crypto页面使用 HTTPS；启动时执行固定向量和随机长度检查
Node.js 可用系统密码模块使用系统 CSPRNGNode.js 18 及以上
已调用 setCustomRNG自定义函数优先只能注入宿主提供的 CSPRNG；返回值必须是精确长度 Uint8Array
没有 CSPRNG 且策略为 strict抛出 Error正式环境使用这一策略
没有 CSPRNG 且沿用默认 warn警告后使用非安全兼容值不能生成生产密钥、签名随机数或 nonce

自定义随机源属于高级能力，普通 Node.js 和现代浏览器不需要注入。

false 与异常的边界

操作失败结果调用方处理
SM2 验签签名不匹配、身份不匹配以及验签解析失败返回 false统一作为“不接受该签名”，不要依赖内部解析失败类型
SM4-GCM/CCM 解密tag、AAD 或密文不匹配时抛出 Error丢弃所有输出并记录不含密钥/明文的审计信息
SM2 解密密钥、格式、曲线点或 C3 校验失败时抛出 Error不尝试把失败结果当明文继续处理
编码与参数校验长度、范围、格式非法时抛出 Error在协议边界返回明确的输入错误
constantTimeEqual任一值为空、长度不同或内容不同返回 false用于比较已解码的 MAC/tag 字节

JavaScript/JIT 不保证严格恒时；constantTimeEqual 只避免相同长度数据按首个不同字节提前返回。

完整参数见 TypeScript 通用 API。

最近更新: