跳至主要內容

TypeScript 使用手册

TypeScript 使用手册

本手册只描述 gmkitx 0.10.1 已发布行为。一次性密码操作使用带算法前缀的具名导出；类用于保存密钥、配置或增量摘要状态。

安装

Node.js 最低版本为 18。依赖锁定文件应与项目一同提交：

npm install gmkitx@0.10.1
环境写法入口文件约束
ESM / TypeScriptimport { sm3Digest } from 'gmkitx'dist/index.js包声明 sideEffects: false，支持按具名导出使用
CommonJSconst { sm3Digest } = require('gmkitx')dist/index.cjsNode.js 18 及以上
浏览器脚本GMKit.sm3Digest('abc')dist/index.global.js全局对象名固定为 GMKit，页面必须由 HTTPS 提供安全随机源

浏览器脚本可固定到已发布版本：

<script src="https://cdn.jsdelivr.net/npm/gmkitx@0.10.1/dist/index.global.js"></script>

不要深度导入未写入 exports 的 dist/* 文件。稳定的包入口只有 gmkitx 和 gmkitx/package.json。

首次运行

先检查运行能力、启用严格随机策略，再核对一个固定向量。样例中的 12 字节随机值只验证 CSPRNG 可用；业务代码还要为每个加密协议定义 nonce 的保存和去重方式。

// 1. 检查运行环境：BigInt 与 UTF-8 codec 是 gmkitx 的基础运行条件。
const environment = getEnvReport();
assert.equal(environment.hasBigInt, true);
assert.equal(environment.hasTextEncoder, true);
assert.equal(environment.hasTextDecoder, true);

// 2. 配置随机源：正式环境没有 CSPRNG 时立即报错，不允许退回非安全随机数。
configureRNG('strict');
const nonce = getRandomBytes(12);
assert.equal(nonce.length, 12);

// 3. 计算固定向量：SM3("abc") 必须得到标准的 32 字节摘要。
const digest = sm3Digest('abc');
assert.equal(
  digest,
  '66c7f0f462eeedd9d1f2d46bdc10e4e2'
    + '4167c4875cf2f7a2297da02b8f4ba8e0',
);

// 4. 非法参数断言：随机字节长度必须是正安全整数。
assert.throws(() => getRandomBytes(0));

运行结果：

TypeScript manual start example passed

开始前固定四条数据规则

  1. 业务字符串按 UTF-8 处理；任意二进制使用 Uint8Array。
  2. key、IV、nonce、公钥、私钥的字符串形式按各 API 规定使用 Hex。
  3. 密文、签名和 tag 进入协议时，明确保存 hex 或 base64，接收端传入对应 InputFormat。
  4. 正式环境在首次随机操作前调用 configureRNG('strict')。没有 CSPRNG 时让进程启动失败，不继续生成密钥、签名或 nonce。

按任务阅读

基础数据、编码与错误先固定 UTF-8、字节、Hex、Base64 和失败语义。身份与密钥SM2签名验签、小数据加解密、公钥处理和密钥交换。摘要与认证SM3、SHA-2、HMAC固定向量、共享密钥认证和增量摘要。业务数据SM4先完成 GCM，再按既有协议选择 CCM 或非 AEAD 模式。协议指定ZUC密钥流、EEA3、EIA3 和 bitLength。受限环境高级能力自定义 RNG、TextCodec、ASN.1 和低层状态。

常用入口

任务本手册使用的入口改用类的条件
SM2 一次性操作sm2GenerateKeyPair、sm2Sign、sm2Verify、sm2Encrypt、sm2Decrypt需要在一个对象中长期持有同一密钥时使用 SM2
摘要与 HMACsm3Digest、sm3Hmac、sha256/384/512、hmacSha256/384/512分块输入时使用 SM3、SHA256/384/512
SM4sm4Encrypt、sm4Decrypt、sm4DecryptBytes固定 key 和 mode 重复调用时使用 SM4；每条消息仍须使用新的 nonce
ZUCzucEncrypt、zucDecryptBytes、zucKeystream、zucKeystreamWords、eea3Encrypt、eia3固定 key/IV 处理一段会话流时使用 ZUC

本手册只使用新接入路径。维护已发布兼容行为时，统一查阅旧系统迁移，不要把迁移分支带回新协议。

对接完成条件

  • 固定向量通过，运行环境报告符合部署要求。
  • 每个外部字符串字段都有明确编码，不依赖内容猜测格式。
  • 签名验签同时保存 userId、签名结构和外层编码。
  • 认证加密同时保存 nonce、AAD 约定、ciphertext、tag、编码和 schema 版本。
  • 测试覆盖正确输入、篡改输入和格式非法输入。

具体函数参数与全部重载见 TypeScript API 说明书。

最近更新: