# SM4-Crypto

基于 [sm-crypto](https://github.com/JuneAndLion/sm-crypto) 的 SM4 加密解密工具库。

## 功能特性

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

## 安装

```bash
npm install sm4-crypto sm-crypto
```

## 快速开始

```javascript
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 模式

```javascript
// 基本用法
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 模式

```javascript
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 密钥

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

### UTF8 IV

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

### None 填充

```javascript
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，安全性高 | ✅ |

## 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test
```

## License

MIT