GMKitX 架构文档

提示

提示：本章要点

• 概述
• 目录结构
• 设计原则
• 核心模块说明
• 使用示例

概述

GMKitX 采用模块化、可扩展的架构设计，便于后续功能扩展和维护。

目录结构

gmkit/
├── src/                      # 源代码目录
│   ├── crypto/              # 密码算法实现（按算法分类）
│   │   ├── sm2/            # SM2 椭圆曲线算法
│   │   │   ├── index.ts    # SM2 主要功能实现
│   │   │   ├── curve.ts    # 椭圆曲线参数和工具
│   │   │   └── class.ts    # SM2 面向对象 API
│   │   ├── sm3/            # SM3 哈希算法
│   │   │   ├── index.ts    # SM3 主要功能实现
│   │   │   └── class.ts    # SM3 面向对象 API
│   │   ├── sm4/            # SM4 分组密码算法
│   │   │   ├── index.ts    # SM4 主要功能实现
│   │   │   └── class.ts    # SM4 面向对象 API
│   │   ├── zuc/            # ZUC 流密码算法
│   │   │   ├── index.ts    # ZUC 主要功能实现
│   │   │   ├── core.ts     # ZUC 核心状态机
│   │   │   └── class.ts    # ZUC 面向对象 API
│   │   └── sha/            # SHA 系列哈希算法
│   │       ├── index.ts    # SHA 主要功能实现
│   │       └── class.ts    # SHA 面向对象 API
│   ├── core/               # 核心工具模块
│   │   ├── utils.ts        # 通用工具函数
│   │   └── asn1.ts         # ASN.1 编解码
│   ├── types/              # 类型定义
│   │   └── constants.ts    # 常量定义
│   └── index.ts            # 主入口文件
├── demo/                    # Demo 应用
├── demo-vue/                # Vue Demo
├── docs/                    # 文档站点
├── test/                    # 测试文件
├── dist/                    # 构建输出（gitignored）
└── package.json            # 包配置

设计原则

1. 模块化设计

每个算法都有独立的目录，包含：

项目	说明
index.ts	函数式 API 实现
class.ts	面向对象 API 实现
其他文件	算法特定的工具和参数

2. 分层架构

项目	说明
crypto/	密码算法层 - 实现具体的加密算法
core/	核心工具层 - 提供通用功能支持
types/	类型定义层 - 统一的类型和常量
index.ts	导出层 - 统一的对外接口

3. 可扩展性

新增算法只需：

1. 在 crypto/ 下创建新目录
2. 实现函数式和面向对象 API
3. 在 index.ts 中导出

4. 双 API 支持

项目	说明
函数式 API	适合简单场景和函数式编程
面向对象 API	适合需要状态管理的复杂场景

核心模块说明

crypto/sm2/

SM2 椭圆曲线公钥密码算法实现。

主要功能:

• 密钥对生成
• 公钥加密 / 私钥解密
• 数字签名 / 签名验证

特点:

• 基于 @noble/curves 实现椭圆曲线运算
• 支持自定义曲线参数
• 完整的中文注释

crypto/sm3/

SM3 密码哈希算法实现。

主要功能:

• 消息摘要计算
• HMAC 实现

特点:

• 纯 TypeScript 实现
• 高性能的位操作
• 详细的中文注释

crypto/sm4/

SM4 分组密码算法实现。

主要功能:

• ECB/CBC/CTR/CFB/OFB/GCM 模式加解密
• 多种填充模式支持

特点:

• 完整的 S盒实现
• 支持多种工作模式
• 清晰的中文注释

crypto/zuc/

ZUC 流密码算法实现。

主要功能:

• ZUC-128 加解密
• 密钥流生成
• EEA3/EIA3 辅助函数

crypto/sha/

SHA 系列哈希算法实现（基于 @noble/hashes）。

主要功能:

• SHA-1 / SHA-256 / SHA-384 / SHA-512
• HMAC-SHA

core/

核心工具模块，提供通用功能。

包含:

• utils.ts: 字节转换、XOR 运算等
• asn1.ts: ASN.1 编解码工具

types/

类型定义和常量。

包含:

• 密码模式常量
• 填充模式常量
• SM2 密文模式
• OID 定义

使用示例

函数式 API

import { digest, sm4Encrypt, generateKeyPair } from 'gmkitx';

// SM3 哈希
const hash = digest('Hello, World!');

// SM4 加密
const key = '0123456789abcdeffedcba9876543210';
const encrypted = sm4Encrypt(key, 'secret message');

// SM2 密钥生成
const keyPair = generateKeyPair();

面向对象 API

import { SM2, SM3, SM4, CipherMode } from 'gmkitx';

// SM3 哈希
const sm3 = new SM3();
sm3.update('Hello');
sm3.update(' World!');
const hash = sm3.digest();

// SM4 加密
const key = '0123456789abcdeffedcba9876543210';
const iv = 'fedcba98765432100123456789abcdef';
const sm4 = new SM4(key, { mode: CipherMode.CBC, iv });
const encrypted = sm4.encrypt('secret message');

// SM2 签名
const sm2 = SM2.generateKeyPair();
const signature = sm2.sign('message');
const isValid = sm2.verify('message', signature);

未来扩展计划

项目	说明
更多国密算法	SM9: 标识密码算法；ZUC-256: 更高安全级别的序列密码
性能优化	WebAssembly 加速；Web Worker 支持
更多功能	密钥导出格式（PEM、DER）；更丰富的互操作向量与示例

贡献指南

1. 遵循现有的目录结构
2. 保持代码的模块化和可测试性
3. 添加完整的中文注释
4. 编写充分的单元测试
5. 更新相关文档

技术栈

项目	说明
TypeScript	类型安全的开发体验
tsup	库打包
Vite	文档与演示构建
Vitest	测试框架
@noble/curves	椭圆曲线库
@noble/hashes	哈希库

许可证

Apache 2.0