# kyber-package

**Repository Path**: openkylin/kyber-package

## Basic Information

- **Project Name**: kyber-package
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2025-08-12
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kyber-768 后量子密码算法实现

基于 NIST FIPS 203 标准的 Kyber-768（ML-KEM-768）密钥封装机制完整 C 实现，附带 Python 图形化验证平台。

## 项目简介

Kyber 是 NIST 于 2024 年正式发布（FIPS 203）的后量子密钥封装机制，安全性建立在 Module-LWE 困难问题之上，能够抵御经典计算机与量子计算机的攻击。

本实现包含以下特点：

- 完整实现 KeyGen、Encaps、Decaps 三个核心接口
- 结构化设计：Barrett 规约（精确整除+条件调整）、递归 NTT（Cooley-Tukey / Gentleman-Sande）、显式 CBD 采样、2 字节 rej_uniform
- 常数时间密文验证与条件赋值，抵御时序侧信道
- Python 图形化上位机，含功能测试、性能基准、跨实现对比、实时 KEM 演示四个模块

## 目录结构

```
kyber768_impl/
├── include/          # 头文件
├── src/              # C 核心源码
│   ├── kyber.c       # ML-KEM 顶层接口
│   ├── kyber_indcpa.c# K-PKE 内层原语
│   ├── ntt.c         # NTT / 逆 NTT
│   ├── poly.c        # 多项式运算
│   ├── polyvec.c     # 多项式向量运算
│   ├── reduce.c      # Montgomery / Barrett 规约
│   ├── cbd.c         # 中心二项分布采样
│   ├── fips202.c     # SHA3 / SHAKE 哈希原语
│   └── symmetric.c   # 哈希函数封装
├── test/             # C 测试程序
│   ├── test_compare.c# 20 项功能测试 + 确定性输出
│   └── benchmark.c   # 性能基准测试
├── validation/       # Python 验证平台
│   ├── test_kyber.py # 20 组 35 项功能测试
│   ├── benchmark.py  # 性能基准（1000 次迭代）
│   ├── test_compare.py# 跨实现对比分析
│   ├── gui_validator.py# 图形化上位机
│   └── requirements.txt
├── bin/              # 编译输出目录
└── Makefile
```

## 环境要求

### C 实现

| 工具 | 版本要求 |
|------|----------|
| GCC / MinGW-w64 | 9.0 及以上 |
| GNU Make | 4.0 及以上 |
| 操作系统 | Windows（MinGW）/ Linux / macOS |

### Python 验证平台

| 工具 | 版本要求 |
|------|----------|
| Python | 3.9 及以上 |
| kyber-py | 0.4.0 及以上 |
| pycryptodome | 3.0.0 及以上 |

---

## 编译（Build）

### Windows（MinGW-w64）

```powershell
cd C:\Users\qlz\Desktop\kyber768_impl

# 编译功能测试程序
mingw32-make run-compare BUILD=release

# 编译性能基准程序
mingw32-make run-bench BUILD=release
```

编译产物输出至 `bin/` 目录：

```
bin/test_compare.exe
bin/benchmark.exe
```

### Linux / macOS

```bash
cd kyber768_impl

# 编译全部
make all

# 仅编译功能测试
make run-compare

# 仅编译性能基准
make run-bench
```

---

## 测试（Test）

### 方式一：C 测试程序

```powershell
# Windows
.\bin\test_compare.exe
```

```bash
# Linux / macOS
./bin/test_compare.exe
```

预期输出（20/20 通过）：

```
=== Test 1: Sizes ===
  [PASS] Public key size = 1184 bytes
  [PASS] Secret key size = 2400 bytes
  [PASS] Ciphertext size = 1088 bytes
  [PASS] Shared secret size = 32 bytes
...
Result: 20/20 tests passed
```

---

### 方式二：Python 功能测试（20 组 35 项）

```bash
# 安装依赖
python -m pip install kyber-py pycryptodome

# 运行测试
python validation/test_kyber.py
```

预期输出：

```
╔════════════════════════════════════════╗
║   Kyber-768 Python 功能测试（20 项）   ║
╚════════════════════════════════════════╝
...
║  结果：35/35 测试通过                 ║
```

---

### 方式三：Python 性能基准

```bash
python validation/benchmark.py
```

参考结果（Windows AMD64，Python 3.13）：

| 操作     | 均值     | 相对 KeyGen |
|----------|----------|-------------|
| KeyGen   | 2.46 ms  | 1.00×       |
| Encaps   | 3.13 ms  | 1.27×       |
| Decaps   | 4.29 ms  | 1.74×       |
| Full KEM | 9.92 ms  | 4.03×       |

---

### 方式四：跨实现对比

```bash
python validation/test_compare.py
```

该脚本将 kyber-py 参考实现与本 C 实现进行对比，验证各自内部自洽性并分析差异根因。

预期结果：18/18 项通过，kyber-py 与本实现各自内部 SS_enc == SS_dec，跨实现差异来源于 `rej_uniform` 字节布局不同（符合预期）。

---

### 方式五：图形化上位机

```bash
python validation/gui_validator.py
```

启动后包含四个标签页：

| 标签页 | 功能 |
|--------|------|
| 功能测试（20 项） | 一键运行全部测试，进度条实时更新 |
| 性能基准 | 可调迭代次数，卡片式显示各操作耗时 |
| 跨实现对比 | 与 C 实现对比，输出差异根因分析 |
| 实时 KEM 演示 | 单次或连续 10 次 KEM，可视化 PK/SK/CT/SS |

---

## 参数规格（Kyber-768）

| 参数 | 值 | 说明 |
|------|----|------|
| n | 256 | 多项式次数 |
| q | 3329 | 模数 |
| k | 3 | 模块秩 |
| η₁ | 2 | 密钥噪声参数 |
| η₂ | 2 | 加密噪声参数 |
| 公钥 | 1184 字节 | |
| 私钥 | 2400 字节 | |
| 密文 | 1088 字节 | |
| 共享密钥 | 32 字节 | |

---

## 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。

## 参考资料

- [FIPS 203 标准文档](https://csrc.nist.gov/pubs/fips/203/final)
- [CRYSTALS-Kyber 参考实现](https://github.com/pq-crystals/kyber)
- [kyber-py Python 库](https://github.com/jack4818/kyber-py)