SM4-Crypto

基于 sm-crypto 的 SM4 加密解密工具库。

功能特性

• 🔐 支持 ECB、CBC 加密模式
• 🔄 支持多种密钥格式：hex、base64
• 📝 支持多种 IV 格式：utf8、hex
• 📦 支持密文格式：hex
• 🎯 支持 PKCS#7 和 None 填充方式
• 🇨🇳 完美支持中文字符加密解密

安装

npm install sm4-crypto sm-crypto

快速开始

const { sm4Encode, sm4Decode } = require('sm4-crypto');

// ECB 模式（无需 IV）
const encrypted = sm4Encode({
  content: 'Hello, SM4!',
  key: '0123456789abcdef0123456789abcdef'
});

const decrypted = sm4Decode({
  content: encrypted,
  key: '0123456789abcdef0123456789abcdef'
});

// CBC 模式（需要 IV）
const encryptedCBC = sm4Encode({
  content: 'Hello, SM4!',
  mode: 'cbc',
  key: '0123456789abcdef0123456789abcdef',
  iv: 'fedcba9876543210fedcba9876543210'
});

const decryptedCBC = sm4Decode({
  content: encryptedCBC,
  mode: 'cbc',
  key: '0123456789abcdef0123456789abcdef',
  iv: 'fedcba9876543210fedcba9876543210'
});

API 文档

sm4Encode(options)

SM4 加密函数

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | content | string | ✅ | - | 待加密内容 | | mode | string | ❌ | 'ecb' | 加密模式：ecb/cbc | | key | string | ✅ | - | 密钥 (16字节) | | keyFormat | string | ❌ | 'hex' | 密钥格式：hex/base64 | | iv | string | ❌ | - | IV偏移量（cbc模式必填，16字节） | | ivFormat | string | ❌ | 'hex' | IV格式：utf8/hex | | cipherMode | string | ❌ | 'hex' | 密文格式：hex | | padding | string | ❌ | 'pkcs#7' | 填充方式：pkcs#7/none |

返回值： 加密后的密文字符串

sm4Decode(options)

SM4 解密函数

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | content | string | ✅ | - | 待解密密文 | | mode | string | ❌ | 'ecb' | 加密模式：ecb/cbc | | key | string | ✅ | - | 密钥 (16字节) | | keyFormat | string | ❌ | 'hex' | 密钥格式：hex/base64 | | iv | string | ❌ | - | IV偏移量（cbc模式必填，16字节） | | ivFormat | string | ❌ | 'hex' | IV格式：utf8/hex | | cipherMode | string | ❌ | 'hex' | 密文格式：hex | | padding | string | ❌ | 'pkcs#7' | 填充方式：pkcs#7/none |

返回值： 解密后的原文字符串

使用示例

ECB 模式

// 基本用法
const { sm4Encode, sm4Decode } = require('sm4-crypto');

const encrypted = sm4Encode({
  content: 'Hello, SM4! 你好，世界！',
  mode: 'ecb',
  key: '0123456789abcdef0123456789abcdef'
});

const decrypted = sm4Decode({
  content: encrypted,
  mode: 'ecb',
  key: '0123456789abcdef0123456789abcdef'
});

CBC 模式

const encrypted = sm4Encode({
  content: 'CBC Mode Test',
  mode: 'cbc',
  key: '0123456789abcdef0123456789abcdef',
  keyFormat: 'hex',
  iv: 'fedcba9876543210fedcba9876543210',
  ivFormat: 'hex'
});

const decrypted = sm4Decode({
  content: encrypted,
  mode: 'cbc',
  key: '0123456789abcdef0123456789abcdef',
  keyFormat: 'hex',
  iv: 'fedcba9876543210fedcba9876543210',
  ivFormat: 'hex'
});

Base64 密钥

const encrypted = sm4Encode({
  content: 'Base64 Key Test',
  mode: 'ecb',
  key: 'ASNFZ4mrze8BI0VniavN7w==',  // Base64 格式密钥
  keyFormat: 'base64'
});

UTF8 IV

const encrypted = sm4Encode({
  content: 'UTF8 IV Test',
  mode: 'cbc',
  key: '0123456789abcdef0123456789abcdef',
  iv: 'fedcba9876543210',  // UTF8 IV（会自动转为16字节hex）
  ivFormat: 'utf8'
});

None 填充

const encrypted = sm4Encode({
  content: '1234567890abcdef',  // 必须16字节对齐
  mode: 'ecb',
  key: '0123456789abcdef0123456789abcdef',
  padding: 'none'
});

参数说明

密钥长度

• SM4 密钥固定为 128 位（16字节）
• Hex 格式：32 个十六进制字符
• Base64 格式：24 个字符 + 2 个 padding（==）

IV 长度

• SM4 IV 固定为 128 位（16字节）
• Hex 格式：32 个十六进制字符
• UTF8 格式：最多 16 个字符

填充方式

| 方式 | 说明 | |------|------| | pkcs#7 | 默认，自动填充到16字节倍数 | | none | 不填充，输入必须16字节对齐 |

加密模式

| 模式 | 说明 | 是否需要IV | |------|------|----------| | ecb | 电子密码本模式，每个块独立加密 | ❌ | | cbc | 密码块链接模式，需要IV，安全性高 | ✅ |

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

License

MIT