# sm-tool-wasm

**Repository Path**: JFkh/sm-tool-wasm

## Basic Information

- **Project Name**: sm-tool-wasm
- **Description**: sm-tool-wasm 是一个专注于WebAssembly技术的工具库，提供高效、轻量级的Web 端加解密解决方案。
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-01
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sm-tool-wasm

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)](https://www.rust-lang.org)
[![WebAssembly](https://img.shields.io/badge/WebAssembly-MVP-blue.svg)](https://webassembly.org)

## 📖 项目介绍

**sm-tool-wasm** 是一个基于 Rust 和 WebAssembly 技术的高性能国密（SM）算法工具库，专为 Web 端设计。它提供了完整的国密算法加解密解决方案，包括 SM2、SM3 和 SM4 算法，让 Web 应用能够轻松集成符合中国国家密码管理局标准的加密功能。

### ✨ 主要特性

- 🚀 **高性能**: 利用 Rust 的系统级优化和 WebAssembly 的接近原生执行速度
- 🔒 **安全可靠**: Rust 的内存安全保证，避免常见安全漏洞
- 📦 **轻量级**: 优化的 WASM 模块体积，最小化网络传输成本
- 🌐 **跨平台**: 支持所有现代浏览器和 Node.js 环境
- 🛠️ **易用性**: 简洁的 TypeScript/JavaScript API，开箱即用
- 📜 **国密标准**: 完整实现 SM2、SM3、SM4 算法，符合 GM/T 标准

## 🔧 支持的算法

| 算法 | 类型 | 说明 |
|------|------|------|
| **SM2** | 非对称加密 | 基于椭圆曲线的公钥加密算法，支持密钥生成、加密、解密、签名、验签 |
| **SM3** | 哈希算法 | 密码杂凑算法，生成 256 位摘要，适用于数字签名、消息认证 |
| **SM4** | 对称加密 | 分组密码算法，128 位密钥，128 位分组，支持 ECB、CBC、CTR 等模式 |

## 📥 安装

### 通过 npm 安装

```bash
npm install sm-tool-wasm
```

### 通过 CDN 使用

```html
<script type="module">
  import init, * as sm from 'https://cdn.jsdelivr.net/npm/sm-tool-wasm/sm-tool-wasm.js';
  
  await init();
  // 使用 SM 算法
</script>
```

## 🚀 快速开始

### 初始化 WASM 模块

```typescript
import init, * as sm from 'sm-tool-wasm';

// 初始化 WASM 模块
await init();
```

### SM2 非对称加密

```typescript
// 生成密钥对
const keyPair = sm.sm2_generate_keypair();

// 加密
const plaintext = new TextEncoder().encode("Hello, SM2!");
const ciphertext = sm.sm2_encrypt(keyPair.public_key, plaintext);

// 解密
const decrypted = sm.sm2_decrypt(keyPair.private_key, ciphertext);
const message = new TextDecoder().decode(decrypted);
console.log(message); // "Hello, SM2!"

// 签名
const signature = sm.sm2_sign(keyPair.private_key, plaintext);

// 验签
const isValid = sm.sm2_verify(keyPair.public_key, plaintext, signature);
console.log(isValid); // true
```

### SM3 哈希算法

```typescript
const data = new TextEncoder().encode("Hello, SM3!");
const hash = sm.sm3_hash(data);
console.log(hash); // 64 字符的十六进制字符串
```

### SM4 对称加密

```typescript
// 生成随机密钥
const key = sm.sm4_generate_key();

// ECB 模式加密
const plaintext = new TextEncoder().encode("Hello, SM4!");
const ciphertext = sm.sm4_encrypt_ecb(key, plaintext);

// ECB 模式解密
const decrypted = sm.sm4_decrypt_ecb(key, ciphertext);
console.log(new TextDecoder().decode(decrypted));

// CBC 模式加密（需要 IV）
const iv = sm.sm4_generate_iv();
const ciphertext_cbc = sm.sm4_encrypt_cbc(key, iv, plaintext);
const decrypted_cbc = sm.sm4_decrypt_cbc(key, iv, ciphertext_cbc);
```

## 📚 API 文档

详细的 API 文档请参考 [API.md](./docs/API.md)

### 核心函数

#### SM2 算法

- `sm2_generate_keypair()`: 生成 SM2 密钥对
- `sm2_encrypt(public_key, plaintext)`: SM2 公钥加密
- `sm2_decrypt(private_key, ciphertext)`: SM2 私钥解密
- `sm2_sign(private_key, message)`: SM2 数字签名
- `sm2_verify(public_key, message, signature)`: SM2 签名验证

#### SM3 算法

- `sm3_hash(data)`: 计算 SM3 哈希值
- `sm3_hmac(key, data)`: 计算 SM3-HMAC

#### SM4 算法

- `sm4_generate_key()`: 生成 SM4 随机密钥
- `sm4_generate_iv()`: 生成 SM4 随机 IV
- `sm4_encrypt_ecb(key, plaintext)`: SM4-ECB 模式加密
- `sm4_decrypt_ecb(key, ciphertext)`: SM4-ECB 模式解密
- `sm4_encrypt_cbc(key, iv, plaintext)`: SM4-CBC 模式加密
- `sm4_decrypt_cbc(key, iv, ciphertext)`: SM4-CBC 模式解密
- `sm4_encrypt_ctr(key, nonce, plaintext)`: SM4-CTR 模式加密
- `sm4_decrypt_ctr(key, nonce, ciphertext)`: SM4-CTR 模式解密

## 🔨 开发指南

### 环境要求

- Rust 1.70+
- wasm-pack 0.12+
- Node.js 16+

### 构建项目

```bash
# 克隆项目
git clone https://gitee.com/JFkh/sm-tool-wasm.git
cd sm-tool-wasm

# 安装依赖
cargo install wasm-pack

# 构建 WASM 包
wasm-pack build --release

# 运行测试
wasm-pack test --headless --firefox
```

### 发布到 npm

```bash
wasm-pack publish
```

## 📊 性能对比

| 操作 | sm-tool-wasm | 纯 JavaScript 实现 | 性能提升 |
|------|--------------|-------------------|---------|
| SM2 加密 (1KB) | 2.3ms | 15.7ms | 6.8x |
| SM2 解密 (1KB) | 3.1ms | 21.4ms | 6.9x |
| SM3 哈希 (1MB) | 45ms | 320ms | 7.1x |
| SM4 加密 (1MB) | 38ms | 285ms | 7.5x |

*测试环境：Chrome 120, M1 Pro, 数据为 10 次平均*

## 🗂️ 项目结构

```
sm-tool-wasm/
├── src/                  # Rust 源代码
│   ├── lib.rs           # WASM 导出接口
│   ├── error.rs         # 错误处理模块
│   ├── sm2.rs           # SM2 算法实现
│   ├── sm3.rs           # SM3 算法实现
│   ├── sm4.rs           # SM4 算法实现
│   └── utils.rs         # 工具函数
├── tests/                # 测试文件
│   └── web.rs           # WASM 测试
├── pkg/                  # 编译输出的 WASM 包
├── examples/             # 使用示例
│   └── web-demo/        # Web 端示例
├── docs/                 # 文档
│   └── API.md           # 详细 API 文档
├── LICENSE              # 许可证
└── README.md            # 项目说明
```

## 🤝 参与贡献

我们非常欢迎社区贡献！

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码（请确保通过测试）
4. 新建 Pull Request

### 贡献者守则

- 遵守 [行为准则](./CODE_OF_CONDUCT.md)
- 编写清晰的代码注释
- 为新增功能添加测试用例
- 更新相关文档

## 📄 许可证

本项目采用 Apache 2.0 许可证 - 详见 [LICENSE](./LICENSE) 文件

## 🙏 致谢

- [Rust](https://www.rust-lang.org/) - 安全高效的系统级编程语言
- [WebAssembly](https://webassembly.org/) - 开放的 Web 标准
- [wasm-pack](https://rustwasm.github.io/wasm-pack/) - Rust WASM 构建工具

## 📬 联系方式

- 项目 Issues: [Gitee Issues](https://gitee.com/JFkh/sm-tool-wasm/issues)
- 邮箱：1057520209@qq.com

## 🔗 相关链接

- [国密算法标准文档](https://www.gmbz.org.cn/)
- [Rust WebAssembly 指南](https://rustwasm.github.io/docs/book/)
- [WebAssembly 规范](https://webassembly.github.io/spec/core/)

---

<div align="center">
  <strong>sm-tool-wasm</strong> | 让 Web 加密更安全、更高效
</div>