co-fb-crypto

co-fb-crypto 是一个前端 JS 国密工具库，用来补齐 SM4 的四种常用模式：

• ECB
• CBC
• CFB
• OFB

这个项目的核心目标是解决前端和后端接口联调时的 SM4 数据加解密问题。

仓库里附带了一个 Express 示例服务用于联调验证，但它只是示例，不是 npm 包主体，也不会被打进最终发布包。

这个库和 sm-crypto、gm-crypto 的关系

和 sm-crypto 的关系

本库底层基于 sm-crypto 实现。

你可以理解成：

• sm-crypto 提供底层 SM4 能力
• 本库在外层统一封装四种模式
• 并补了更方便的前端调用方式

和 gm-crypto 的关系

本库没有直接依赖 gm-crypto，但提供了兼容 gm-crypto 使用习惯的 API 形式。

也就是说：

• 不是把 gm-crypto 原库打进来了
• 而是让你可以按类似 gm-crypto 的写法来调用本库

当前支持能力

• 支持 SM4-ECB
• 支持 SM4-CBC
• 支持 SM4-CFB
• 支持 SM4-OFB
• 支持 CommonJS
• 支持 ESM
• 提供 TypeScript 类型声明
• 支持字符串、数组、Uint8Array、ArrayBuffer
• 支持 utf8、hex、base64 输入输出

适用场景

适合这些场景：

• 前后端接口字段需要 SM4 加密后再传输
• 后端协议要求使用 CFB 或 OFB
• 现有项目已经用了 sm-crypto 或 gm-crypto
• 需要一个统一的前端 SM4 四模式工具库

npm 包名说明

当前源码目录仍然叫 fb-crypto，这是本地仓库里的目录名。 实际发布到 npm 的包名是 co-fb-crypto。

安装时请直接使用正式包名：

npm install co-fb-crypto

阅读本文档时，请把所有包引用都理解为 co-fb-crypto。

安装

本地开发

npm install

作为 npm 包使用

npm install co-fb-crypto

前端怎么用

前端最常见的流程是：

1. 把明文数据准备好
2. 调用 encrypt() 加密
3. 把密文传给后端
4. 收到后端密文响应后，再调用 decrypt() 解密

使用方式一：统一 API

这是最推荐的使用方式。

CommonJS

const { encrypt, decrypt } = require('co-fb-crypto')

const key = '0123456789abcdeffedcba9876543210'
const iv = 'fedcba98765432100123456789abcdef'

const cipherText = encrypt('前端要传给后端的数据', key, {
  mode: 'cfb',
  iv,
})

const plainText = decrypt(cipherText, key, {
  mode: 'cfb',
  iv,
})

ESM

import { encrypt, decrypt } from 'co-fb-crypto'

const key = '0123456789abcdeffedcba9876543210'
const iv = 'fedcba98765432100123456789abcdef'

const cipherText = encrypt('前端数据', key, {
  mode: 'ofb',
  iv,
})

const plainText = decrypt(cipherText, key, {
  mode: 'ofb',
  iv,
})

使用方式二：快捷方法

如果你希望按模式直接调用，也可以使用这些快捷方法：

• encryptECB
• decryptECB
• encryptCBC
• decryptCBC
• encryptCFB
• decryptCFB
• encryptOFB
• decryptOFB

示例：

const { encryptCBC, decryptCBC } = require('co-fb-crypto')

const key = '0123456789abcdeffedcba9876543210'
const iv = 'fedcba98765432100123456789abcdef'

const cipherText = encryptCBC('需要 CBC 加密的数据', key, { iv })
const plainText = decryptCBC(cipherText, key, { iv })

使用方式三：兼容 gm-crypto 风格

如果你原来的项目习惯写 gm-crypto 风格，可以这样用：

const { SM4 } = require('co-fb-crypto')

const key = '0123456789abcdeffedcba9876543210'
const iv = 'fedcba98765432100123456789abcdef'

const cipherText = SM4.encrypt('gm 风格调用', key, {
  mode: SM4.constants.CFB,
  iv,
})

const plainText = SM4.decrypt(cipherText, key, {
  mode: SM4.constants.CFB,
  iv,
})

支持的常量：

• SM4.constants.ECB
• SM4.constants.CBC
• SM4.constants.CFB
• SM4.constants.OFB

使用方式四：兼容 sm-crypto 风格

如果你原来的项目习惯写 sm-crypto 风格，可以这样用：

const { sm4 } = require('co-fb-crypto')

const key = '0123456789abcdeffedcba9876543210'
const iv = 'fedcba98765432100123456789abcdef'

const cipherText = sm4.encrypt('sm 风格调用', key, {
  mode: 'ofb',
  iv,
  output: 'array',
})

const plainBytes = sm4.decrypt(cipherText, key, {
  mode: 'ofb',
  iv,
  output: 'array',
})

API 说明

encrypt(plaintext, key, options)

通用加密入口。

decrypt(ciphertext, key, options)

通用解密入口。

SM4.encrypt(data, key, options)

兼容 gm-crypto 风格的加密入口。

SM4.decrypt(data, key, options)

兼容 gm-crypto 风格的解密入口。

sm4.encrypt(data, key, options)

兼容 sm-crypto 风格的加密入口。

sm4.decrypt(data, key, options)

兼容 sm-crypto 风格的解密入口。

options 参数说明

• mode: ecb、cbc、cfb、ofb
• iv: cbc、cfb、ofb 模式下必传，长度必须为 16 字节
• inputEncoding: 默认加密为 utf8，默认解密为 hex
• outputEncoding: 默认加密为 hex，默认解密为 utf8
• output: 兼容 sm-crypto 风格的输出选项
• keyEncoding: 默认 hex
• ivEncoding: 默认 hex
• padding: ecb、cbc 模式默认 pkcs#7

参数要求

• key 必须是 16 字节
• cbc、cfb、ofb 模式下 iv 必须是 16 字节
• CFB 和 OFB 属于流式模式，不需要额外 padding
• 前后端联调时，mode、key、iv、输入输出编码必须完全一致

本地测试

npm test
npm run test:esm

本地联调示例

npm run start:server

示例接口：

• GET /health
• POST /api/encrypt
• POST /api/decrypt