# 密码模块设计实验

**Repository Path**: cloud-lumiere/cryptography-module

## Basic Information

- **Project Name**: 密码模块设计实验
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SM3/SM4 安全二级密码模块

基于 SM3/SM4 国密算法的软件密码模块，符合 **GM/T 0028-2014《密码模块安全要求》安全二级**标准。

项目源代码保留在仓库中，最终保留交付的可执行文件见dist目录下。

具体实验设计和测试过程详见[实验报告.md](实验报告.md)

## 项目源代码结构

```
密码模块/
├── sm3.py                      # SM3 密码杂凑算法核心实现
├── sm4.py                      # SM4 分组密码算法核心实现
├── security_wrapper.py         # 安全边界层
│   ├── SecureBuffer            # 可变内存缓冲区（ctypes），析构自动置零
│   ├── hmac_sm3()              # HMAC-SM3 实现（RFC 2104）
│   ├── IntegrityChecker        # 完整性自检引擎
│   ├── Authenticator           # 加盐SM3口令鉴别 + 失败锁定
│   ├── AccessController        # 基于角色的访问控制（Admin/User/Auditor）
│   └── AntiDebug               # 反调试检测
├── crypto_module.py            # 密码模块主类（有限状态机 + 密码服务接口）
│   ├── SM4SecureEngine         # SM4安全引擎（轮密钥SecureBuffer管理，用后置零）
│   ├── CryptoModule            # 状态机：INIT→READY→AUTHED→BUSY→ERROR
│   ├── SM4-ECB/CBC             # 带PKCS7填充的分组加密
│   ├── HMAC-SM3                # 消息认证码
│   └── SM3-HASH                # 密码杂凑
├── crypto_module_entry.py      # 交互式命令行入口
├── test_crypto_module.py       # 47个自动化测试用例
├── build_tools/
│   └── compute_integrity.py    # 构建时完整性基准值生成脚本
├── README.md
└── 实验报告.md
```

## 安全特性

| 安全域 | 实现方式 |
|--------|----------|
| **完整性自检** | 构建时预计算SM3杂凑→硬编码到二进制；运行时 `IntegrityChecker.verify()` 验证代码文件完整性 |
| **角色鉴别** | Admin/User/Auditor 三权分立，SM3加盐存储口令，5次失败锁定账户 |
| **访问控制** | 基于角色的权限矩阵，`AccessController.check()` 拦截非法操作 |
| **CSP置零** | `SecureBuffer`（ctypes 可变缓冲区）物理覆盖，轮密钥用后即时置零 |
| **核准模式** | 仅 SM4-ECB、SM4-CBC、SM3-HASH、HMAC-SM3 为核准模式；非核准模式立即标记 |
| **错误状态** | ERROR 态禁止任何数据输出，不可恢复（需重启进程） |
| **反调试** | `sys.gettrace()` + Windows `IsDebuggerPresent()` 检测，触发后自动置零 |
| **编译部署** | 支持 Nuitka/Cython 编译为原生二进制，移除源文件 |

## 快速开始

```bash
# 运行全部测试
python -m unittest test_crypto_module -v

# 启动交互式命令行
python crypto_module_entry.py
```

### 交互式命令

| 命令 | 说明 | 权限 |
|------|------|------|
| `login <user> <pass>` | 登录 | 所有人 |
| `logout` | 登出 | 已认证 |
| `set_mode <mode>` | 设置核准模式 | Admin |
| `import_key <hex>` | 导入16字节SM4密钥 | Admin |
| `set_iv <hex>` | 设置CBC模式IV | Admin |
| `encrypt <hex>` | 加密（PKCS7填充） | Admin/User |
| `decrypt <hex>` | 解密 | Admin/User |
| `hash <hex>` | SM3杂凑 | Admin/User |
| `hmac <key> <msg>` | HMAC-SM3 | Admin/User |
| `status` | 查询模块状态 | 已认证 |
| `zeroize` | 销毁所有CSP | Admin |
| `unlock <user>` | 解锁账户 | Admin |

### 预置账户

| 用户名 | 密码 | 角色 | 权限范围 |
|--------|------|------|----------|
| `admin` | `Admin@123` | Admin | 全部操作（加密/解密/密钥导入/置零/审计/配置） |
| `user` | `User@123` | User | 加密/解密/状态查询 |
| `auditor` | `Audit@123` | Auditor | 审计/状态查询（只读） |

### 快速演示

```python
from crypto_module import CryptoModule
from security_wrapper import Authenticator, IntegrityChecker

# 设置口令
Authenticator.set_password('admin', 'Admin@123')

# 初始化模块
module = CryptoModule()
module.initialize()

# 登录
module.login('admin', 'Admin@123')

# 设置核准模式
module.set_mode('SM4-ECB')

# 导入密钥
module.import_key('0123456789abcdeffedcba9876543210')

# 加密
cipher = module.encrypt('0123456789abcdeffedcba9876543210')
print(f'Ciphertext: {cipher}')

# 解密
plain = module.decrypt(cipher)
print(f'Plaintext: {plain}')

# 安全置零
module.zeroize()
```

## 测试覆盖

47 个测试用例覆盖：

- **SM3已知向量测试**：空串、abc、长消息
- **SM4已知向量测试**：加解密、双向验证
- **SecureBuffer测试**：读写、置零、长度校验、析构置零
- **HMAC-SM3测试**：基本功能、密钥区分、长密钥
- **Authenticator测试**：成功/失败、未知用户、锁定、解锁
- **AccessController测试**：未认证、角色权限验证
- **PKCS7测试**：填充、去填充、对齐数据、非法填充
- **CryptoModule测试**：状态机、ECB/CBC加解密、权限拦截、置零、错误态、核准模式
- **AntiDebug测试**：无调试器检测
- **IntegrityChecker测试**：无哈希、正确哈希验证

## 编译部署

### Nuitka 编译（推荐）

```bash
nuitka --standalone --onefile --enable-plugin=python-version --output-dir=dist crypto_module_entry.py
```

### Cython 编译

```bash
cythonize -i crypto_module.py sm3.py sm4.py security_wrapper.py
```

编译后移除所有 `.py` 源文件，仅保留二进制文件作为密码模块交付物。

## 许可证

本作品用于教学和实验用途。