JS实现国密SM2/SM4加解密的方法

作者:极速慢跑

时间:2026-11-18

浏览:527

详细讲解在JavaScript环境中通过sm-crypto实现国密SM2非对称与SM4对称加解密的完整方法,包含环境配置、规范对齐、混合加密架构及前后端跨语言联调避坑指南。

文章目录
国密算法 JavaScript sm-crypto 技术指南

系统化梳理前端及 Node.js 环境下 SM2 与 SM4 密码算法的标准化落地方案,规避跨端联调常见的格式与参数陷阱。

JS实现国密SM2/SM4加解密的方法
图 0:国密 SM2/SM4 混合密码工程化实践总览

在 JavaScript 中落地国密算法,核心路径是依靠成熟密码学封装库 sm-crypto,分别使用 SM2 实现非对称密钥交换与敏感参数加解密,使用 SM4 处理大数据量的高速对称加解密。单纯使用 SM2 加密完整请求体会导致前端显著卡顿,而单独使用 SM4 则面临密钥静态泄露风险;因此,工业级实践均采用“SM2 协商会话密钥 + SM4 对称加密报文体”的混合加密方案。

一、开发准备与依赖引入

前端工程化项目(如 Vue、React)或 Node.js 服务端,最广泛使用的国密实现库为 sm-crypto。该库对国密标准 GB/T 32918(SM2)和 GB/T 32907(SM4)提供了高效的纯 JS 实现,无底层 C++ 编译依赖。

在项目终端执行以下命令安装依赖:

npm install sm-crypto --save

在代码中按模块引入所需算法对象:

// ES Module 引入方式(Vue / React / Vite / Webpack)
import { sm2, sm4 } from 'sm-crypto';

// CommonJS 引入方式(Node.js)
const { sm2, sm4 } = require('sm-crypto');

在无打包工具的原生 HTML 页面中,可以通过引入打包好的 CDN 脚本:

<script src="https://cdn.jsdelivr.net/npm/sm-crypto/dist/sm-crypto.js"></script>
<script>
  const { sm2, sm4 } = window.smCrypto;
</script>

二、JS 实现 SM2 非对称加解密

SM2 是一种基于椭圆曲线(ECC-256)的公钥密码算法。公钥用于加密或验签,私钥用于解密或签名。在前端交互中,前端通常仅持有服务端的公钥,用于加密敏感字段或临时对称密钥。

2.1 生成与规整密钥对

SM2 密钥对通常由服务端或硬件密码机统一生成并下发公钥。若需要在前端生成密钥对(例如客户端身份绑定),可通过 sm2.generateKeyPairHex() 生成:

// 生成十六进制公私钥对
const keypair = sm2.generateKeyPairHex();

// 公钥:以 04 开头的 130 位十六进制字符串(未压缩点坐标)
const publicKey = keypair.publicKey; 

// 私钥:64 位十六进制字符串(256 位大整数)
const privateKey = keypair.privateKey;

console.log('PublicKey 长度:', publicKey.length); // 130
console.log('PrivateKey 长度:', privateKey.length); // 64
⚠️ 关键规范:04 公钥前缀处理

国标未压缩公钥由 04 + X坐标(32字节/64Hex) + Y坐标(32字节/64Hex) 构成,全长共 130 个字符。某些后端框架(如部分 Java 工具类)给出的公钥去除了 04 前缀(仅 128 字符)。在调用 JS 加密前,必须检查长度并在开头补全 04,否则算法内部无法正确还原椭圆曲线点。

2.2 公钥加密与私钥解密完整代码

调用 sm2.doEncrypt 时,必须显式指定第三个参数 cipherMode。根据国家密码管理局推荐的新标准(GB/T 32918.4-2016),密文排序结构为 C1C3C2,对应的模式参数为 1。

/**
 * SM2 公钥加密
 * @param {string} text - 明文字符串
 * @param {string} pubKey - 130位带04前缀的公钥
 * @returns {string} 密文十六进制字符串(C1C3C2 格式,带 04 前缀)
 */
function sm2Encrypt(text, pubKey) {
  // 规整公钥:若缺少 04 前缀则自动补齐
  let formattedPubKey = pubKey;
  if (formattedPubKey.length === 128) {
    formattedPubKey = '04' + formattedPubKey;
  }
  
  // cipherMode: 1 表示 C1C3C2(新国标推荐),0 表示 C1C2C3(老标准)
  const cipherMode = 1;
  
  // sm-crypto 默认 doEncrypt 输出不带 04 前缀的 C1C3C2 密文
  const rawCipher = sm2.doEncrypt(text, formattedPubKey, cipherMode);
  
  // 许多 Java/Go 服务端解析器要求密文必须以 04 开头标识未压缩点
  const fullCipher = rawCipher.startsWith('04') ? rawCipher : '04' + rawCipher;
  return fullCipher;
}

/**
 * SM2 私钥解密
 * @param {string} cipherHex - 密文十六进制字符串
 * @param {string} priKey - 64位私钥
 * @returns {string} 解密后的明文字符串
 */
function sm2Decrypt(cipherHex, priKey) {
  const cipherMode = 1;
  
  // 若传入带 04 前缀,则剥离 04 前缀以适配 doDecrypt 接收要求
  let cleanCipher = cipherHex;
  if (cleanCipher.startsWith('04')) {
    cleanCipher = cleanCipher.substring(2);
  }
  
  const decryptedText = sm2.doDecrypt(cleanCipher, priKey, cipherMode);
  return decryptedText;
}

// 运行测试
const testMsg = "Hello 国密 SM2 安全通信";
const cipher = sm2Encrypt(testMsg, publicKey);
const decrypted = sm2Decrypt(cipher, privateKey);
console.log("SM2 解密验证是否一致:", testMsg === decrypted); // true
JS实现国密SM2/SM4加解密的方法
图 1:SM2 加密步骤拆解与 C1C3C2 数据段剖析

三、JS 实现 SM4 对称加解密

SM4 是一种分组密码算法,分组长度和密钥长度均为 128 位(16 字节)。由于对称计算速度极快,适合对各种体积的业务报文、表单数据和文件流进行加解密。

3.1 ECB 模式与 CBC 模式对比

SM4 最常用的工作模式为 ECB(电子密码本模式) 和 CBC(密文分组链接模式)。

  • ECB 模式: 不需要初始向量(IV),各个 16 字节明文块独立加密。缺点是相同的明文块始终产生完全相同的密文块,无法抵御选择明文攻击与模式识别,生产环境极不推荐用于整体报文。
  • CBC 模式: 引入 16 字节随机初始向量(IV)。后一个密文块依赖于前一个密文块的运算结果,使得即使明文相同,加密出的密文也截然不同,安全强度高,是前后端接口加密的强制标准。
JS实现国密SM2/SM4加解密的方法
图 2:SM4 对称加密 ECB 与 CBC 模式工作机制及填充对比

3.2 SM4 加解密完整实现代码

sm4.encrypt 与 sm4.decrypt 默认采用 PKCS#7 填充模式。密钥和 IV 均需满足 128 位(16 字节,对应 32 个十六进制字符或 16 个 ASCII 字符)。

/**
 * 生成 16 字节安全的十六进制随机字符串(用作 SM4 密钥或 IV)
 */
function generateRandomHex16() {
  const arr = new Uint8Array(16);
  if (typeof window !== 'undefined' && window.crypto) {
    window.crypto.getRandomValues(arr);
  } else {
    const crypto = require('crypto');
    const bytes = crypto.randomBytes(16);
    return bytes.toString('hex');
  }
  return Array.from(arr, b => b.toString(16).padStart(2, '0')).join('');
}

/**
 * SM4 CBC 模式加密
 * @param {string} plainText - 待加密明文
 * @param {string} hexKey - 32位十六进制密钥 (16字节)
 * @param {string} hexIv - 32位十六进制初始向量 (16字节)
 * @returns {string} 密文十六进制字符串
 */
function sm4CbcEncrypt(plainText, hexKey, hexIv) {
  return sm4.encrypt(plainText, hexKey, {
    mode: 'cbc',
    iv: hexIv,
    padding: 'pkcs#7' // 默认即为 pkcs#7
  });
}

/**
 * SM4 CBC 模式解密
 * @param {string} cipherHex - 密文十六进制字符串
 * @param {string} hexKey - 32位十六进制密钥
 * @param {string} hexIv - 32位十六进制初始向量
 * @returns {string} 解密后字符串
 */
function sm4CbcDecrypt(cipherHex, hexKey, hexIv) {
  return sm4.decrypt(cipherHex, hexKey, {
    mode: 'cbc',
    iv: hexIv,
    padding: 'pkcs#7'
  });
}

// 运行测试
const testKey = generateRandomHex16();
const testIv = generateRandomHex16();
const testData = JSON.stringify({ orderId: "ORD20261117", amount: 998.50 });

const sm4Cipher = sm4CbcEncrypt(testData, testKey, testIv);
const sm4Plain = sm4CbcDecrypt(sm4Cipher, testKey, testIv);
console.log("SM4 CBC 解密是否一致:", testData === sm4Plain); // true

四、工程实战:基于 SM2+SM4 的混合加密架构

在真实的前后端数据交互中,客户端每次发送请求时,动态生成一次性 SM4 密钥(一事一密),用它加密整个 HTTP 请求体;再使用服务端的 SM2 公钥加密这个短小的 SM4 密钥。

JS实现国密SM2/SM4加解密的方法
图 3:SM2 + SM4 端到端混合加密与传输时序架构

4.1 前端客户端封装器

前端将业务数据对象、后端下发的 SM2 公钥传入打包函数,组装成网络传输专用的统一安全结构体:

/**
 * 前端混合加密请求封包函数
 * @param {object} requestData - 待发送的业务 JSON 对象
 * @param {string} serverSm2PubKey - 服务端 SM2 130位公钥
 * @returns {object} 包含加密后密钥、IV及密文的载荷
 */
function packSecurePayload(requestData, serverSm2PubKey) {
  // 1. 生成一次性 SM4 会话密钥和 CBC 向量
  const sessionKeyHex = generateRandomHex16();
  const ivHex = generateRandomHex16();

  // 2. 使用 SM4 加密完整业务体
  const jsonStr = JSON.stringify(requestData);
  const cipherText = sm4CbcEncrypt(jsonStr, sessionKeyHex, ivHex);

  // 3. 使用服务端 SM2 公钥加密 sessionKey
  const encryptedKey = sm2Encrypt(sessionKeyHex, serverSm2PubKey);

  // 4. 返回组装载荷
  return {
    encKey: encryptedKey,
    iv: ivHex,
    cipherText: cipherText,
    timestamp: Date.now()
  };
}

4.2 服务端对应解密验证示例(Node.js / 伪代码逻辑)

/**
 * 服务端接收到载荷后的反向解密流程
 * @param {object} payload - 前端提交的载荷对象
 * @param {string} serverSm2PriKey - 服务端保密的 SM2 私钥
 * @returns {object} 原始业务 JSON 对象
 */
function unpackSecurePayload(payload, serverSm2PriKey) {
  const { encKey, iv, cipherText } = payload;

  // 1. 私钥解密获取原始 SM4 SessionKey
  const sessionKeyHex = sm2Decrypt(encKey, serverSm2PriKey);

  // 2. SM4 CBC 解密业务密文
  const rawJson = sm4CbcDecrypt(cipherText, sessionKeyHex, iv);

  // 3. 反序列化
  return JSON.parse(rawJson);
}

五、前后端跨语言联调避坑与对齐清单

在实际项目落地中,前端 JS 通常需要与 Java(基于 BouncyCastle、Hutool)、Go(基于 tjfoc/gmsm)或 C/C++ 密码中间件联调。绝大多数“解密失败”均非算法缺陷,而是协议格式未严格对齐。下表总结了最核心的排查项:

JS实现国密SM2/SM4加解密的方法
图 4:前后端国密跨语言联调 4 大核心核对清单
核对项 前端 JS (sm-crypto) 表现 后端(Java/Go/C)常见表现 解决方案与统一标准
SM2 密文排列顺序 默认采用新国标 C1C3C2 (mode 1)。 部分老旧系统或早期 BC 库默认采用旧规范 C1C2C3 (mode 0)。 优先升级对齐新国标 C1C3C2;无法修改后端时,前端指定 cipherMode: 0。
公钥 04 坐标标识 接收 130 位十六进制(带 04 未压缩标识)。 某些框架导出公钥仅 128 位,剥离了 04。 前端加密前判断 length === 128,是则主动补齐 04 前缀。
SM2 密文 04 前缀 doEncrypt 默认生成不带 04 的密文。 Java BouncyCastle 解密器通常强制要求密文以 04 开头。 前端加密后统一加上 04,服务端解密时若遇到 04 前缀则兼容剥离。
编码方式转换 API 输入输出默认全为 Hex 十六进制字符串。 接口传输通常使用 Base64 传递二进制 byte[]。 统一规定:加密后将 Hex 转换为 Base64 传输,后端收到后由 Base64 还原。
SM4 填充模式 默认采用 PKCS#7(每块 16 字节)。 易被误配置为 NoPadding 或 ZeroPadding。 后端密码配置必须明确声明为 SM4/CBC/PKCS7Padding(或 PKCS5Padding)。

5.1 密文顺序互转实用工具函数

当服务端使用老旧组件且无法修改配置时,前端可使用以下切片工具函数直接在 C1C3C2 与 C1C2C3 之间相互转换:

/**
 * SM2 密文顺序转换:C1C3C2 -> C1C2C3
 * @param {string} c1c3c2Hex - 16进制密文(可带或不带04)
 * @returns {string} 转换后的 C1C2C3 16进制密文
 */
function convertC1C3C2ToC1C2C3(c1c3c2Hex) {
  const has04 = c1c3c2Hex.startsWith('04');
  const clean = has04 ? c1c3c2Hex.slice(2) : c1c3c2Hex;
  
  // C1 固定 64 字节 = 128 字符
  const c1 = clean.slice(0, 128);
  // C3 固定 32 字节 = 64 字符
  const c3 = clean.slice(128, 128 + 64);
  // C2 为后续剩余全部字符
  const c2 = clean.slice(128 + 64);

  return (has04 ? '04' : '') + c1 + c2 + c3;
}

/**
 * SM2 密文顺序转换:C1C2C3 -> C1C3C2
 */
function convertC1C2C3ToC1C3C2(c1c2c3Hex) {
  const has04 = c1c2c3Hex.startsWith('04');
  const clean = has04 ? c1c2c3Hex.slice(2) : c1c2c3Hex;

  const c1 = clean.slice(0, 128);
  // C3 在最后 64 个字符
  const c3 = clean.slice(clean.length - 64);
  // C2 在中间
  const c2 = clean.slice(128, clean.length - 64);

  return (has04 ? '04' : '') + c1 + c3 + c2;
}

六、总结与落地建议

在前端实现国密 SM2/SM4 加解密时,牢记两项核心工程原则:

  1. 职责分离原则: 严禁使用 SM2 直接加密长文本或海量数据。SM2 仅充当会话密钥分发的信使,大数据量必须由 SM4(首选 CBC 模式)完成吞吐。
  2. 基准向量优先原则: 在前后端首次联调时,切忌直接在业务接口上测试。双方应先用一组写死的明文、固定 SM2 密钥对与固定 SM4 密钥/IV(即标准测试向量),在单步加解密层面核实结果完全一致,再接入动态会话流程。这样可迅速定位编码、前缀或模式排序问题,显著提升联调交付效率。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章