# CryptoDesign

**Repository Path**: Cohawv/crypto-design

## Basic Information

- **Project Name**: CryptoDesign
- **Description**: 密码学课程设计，主要实现了基于国密算法（sm2、sm3、sm4）的安全实时聊天系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-05
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# CryptoChat - 基于国密算法的安全即时通讯系统

## 项目简介

CryptoChat 是一个采用中国国家密码管理局发布的商用密码算法（SM2/SM3/SM4）构建的安全即时通讯系统。本项目采用客户端-服务器架构，支持文字消息、图片传输、文件传输、群组聊天、好友管理等功能，适合作为密码学课程设计或安全通讯学习项目。

## 技术架构

### 核心技术栈

| 组件 | 技术选型 |
|------|----------|
| 编程语言 | Python 3.13 |
| 图形界面 | PyQt5 |
| 密码算法 | GmSSL / gmssl-python (SM2/SM3/SM4) |
| 数据库 | SQLite3 |
| 网络通信 | Socket + 自定义二进制协议 |

### 项目目录结构

```
crypto-design/
├── client/                 # 客户端模块
│   ├── 03_gui_views/       # GUI视图层
│   │   ├── chat_window.py      # 聊天窗口
│   │   ├── login_window.py     # 登录窗口
│   │   ├── register_window.py  # 注册窗口
│   │   └── root_window.py      # 根窗口
│   ├── assist-docs/        # 开发文档
│   ├── test-client/        # 客户端测试
│   ├── keys/               # 密钥存储目录
│   ├── main_client_01.py   # 客户端入口
│   ├── gui_controller_02.py # GUI控制器
│   ├── crypto_engine_04.py  # 密码引擎
│   ├── key_manager_05.py    # 密钥管理器
│   ├── network_handler_06.py # 网络处理
│   └── local_storage_07.py  # 本地存储
├── server/                 # 服务端模块
│   ├── start_server_01.py  # 服务端入口
│   ├── user_manager_02.py  # 用户管理
│   ├── message_router_03.py # 消息路由
│   └── database_handler_06.py # 数据库处理
├── common/                 # 公共模块
│   └── data_serializer.py  # 数据序列化
├── test/                   # 测试模块
├── keys/                   # 服务端密钥
└── config.py               # 配置文件
```

## 功能特性

### 用户管理

- 用户注册与登录
- 密码强度校验
- 用户信息查询
- 好友关系管理（添加、删除、查看）

### 消息通讯

- 私聊消息（端到端加密）
- 群组消息（群密钥加密）
- 离线消息存储与接收
- 图片消息传输
- 文件消息传输

### 密码安全

- **SM2**：用于密钥交换和数字签名
- **SM3**：用于消息摘要和密码学哈希
- **SM4-GCM**：用于消息加密和认证
- 会话密钥动态协商
- 群组密钥广播更新

## 环境配置

### 依赖要求

```
Python >= 3.13
PyQt5 >= 5.15
gmssl-python >= 0.2
```

### 安装步骤

1. 克隆项目到本地

```bash
git clone https://gitee.com/Cohawv/crypto-design.git
cd crypto-design
```

2. 安装 Python 依赖

```bash
pip install -r requirements.txt
```

3. 安装 GmSSL（用于 SM2 密钥操作）

- **Windows**: 从 [GmSSL 官网](https://gmssl.org/) 下载安装包
- **Linux**: `sudo apt-get install gmssl` 或从源码编译
- **macOS**: `brew install gmssl`

4. 初始化数据库

项目启动时会自动创建 SQLite 数据库文件 `all-data.db`，无需手动初始化。

## 运行指南

### 启动服务端

在项目根目录执行：

```bash
python -m server.start_server_01
```

或直接运行：

```bash
python server/start_server_01.py
```

默认监听地址：`0.0.0.0:9999`

### 启动客户端

在项目根目录执行：

```bash
python -m client.main_client_01
```

或直接运行：

```bash
python client/main_client_01.py
```

### 使用流程

1. **注册账号**：在客户端点击"注册"按钮，填写用户名和密码
2. **登录**：使用注册的账号登录系统
3. **添加好友**：通过搜索用户名添加好友
4. **创建/加入群组**：与好友创建群组或加入已有群组
5. **发送消息**：选择聊天对象，发送文字、图片或文件

## 密码模块说明

### SM3Hasher

SM3 哈希计算器，支持流式哈希和文件哈希：

```python
from client.crypto_engine_04 import SM3Hasher

hasher = SM3Hasher()
hash_result = hasher.hash_string("hello world")
```

### SM4

SM4-GCM 加密模式，支持对称加密：

```python
from client.crypto_engine_04 import SM4

cipher = SM4(key=session_key)
ciphertext = cipher.encrypt(plaintext, iv=iv)
plaintext = cipher.decrypt(ciphertext, key=session_key, iv=iv)
```

### GenShareKey

会话密钥派生，基于 SM2 椭圆曲线计算共享秘密：

```python
from client.crypto_engine_04 import GenShareKey

gk = GenShareKey()
# 生成临时密钥对
local_keypair = gk.generate_temp_keypair()
# 与对方公钥计算共享密钥
result = gk.derive_sm4_session_key(local_private_key, peer_public_key)
```

## 配置说明

项目配置文件 `config.py` 中可修改以下配置：

- 服务端地址和端口
- 数据库路径
- 密钥存储路径
- 消息超时设置
- 会话密钥有效期

## 常见问题

### 1. GmSSL 命令未找到

确保 GmSSL 已正确安装并添加到系统 PATH 环境变量。Windows 用户可能需要重启终端。

### 2. 密钥文件权限错误

确保 `client/keys/` 和 `keys/` 目录有正确的读写权限。

### 3. 数据库锁定

多个客户端同时访问可能导致数据库锁定，建议服务端和客户端在不同终端运行。

### 4. SM4-GCM 加密失败

确保每次加密使用唯一的 IV（初始化向量），不要重复使用相同的 IV。

## 开发文档

更多技术细节和 API 说明请参阅：

- `CLAUDE.md` - 开发规范和架构说明
- `AGENT.md` - 项目开发计划和目标
- `client/README-Client.md` - 客户端模块详解
- `client/assist-docs/crypto_engine_04_API.md` - 密码引擎 API 文档
- `server/README-Server.md` - 服务端模块详解

## 许可证

本项目仅供学习和研究使用。

## 注意事项

1. 本项目为课程设计项目，生产环境使用请自行评估安全性
2. 密码学实现仅供参考，实际部署请使用经过安全审计的密码库
3. 密钥文件应妥善保管，切勿提交到公开仓库