# dilithium-package

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

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dilithium2 后量子数字签名算法实现

基于 CRYSTALS-Dilithium 的 C 语言实现，安全级别：**Dilithium2**（NIST 安全级别 2，相当于 AES-128）。

## 项目简介

Dilithium 是 NIST 后量子密码标准化项目（FIPS 204）选定的数字签名方案，基于格密码学中的 Module-LWE 问题，能够抵抗量子计算机攻击。

本项目实现了 Dilithium2 安全级别，密钥与签名参数如下：

| 参数 | 大小 |
|------|------|
| 公钥 | 1312 字节 |
| 私钥 | 2560 字节 |
| 签名 | 2420 字节 |

## 项目结构

```
Dilithium/
├── src/                    # 核心源代码
│   ├── sign.c/h            # 签名与验证主函数
│   ├── poly.c/h            # 多项式运算
│   ├── polyvec.c/h         # 多项式向量运算
│   ├── ntt.c/h             # 数论变换（NTT）加速多项式乘法
│   ├── packing.c/h         # 密钥和签名的打包/解包
│   ├── rounding.c/h        # 舍入运算
│   ├── reduce.c/h          # 模运算
│   ├── fips202.c/h         # SHA3/SHAKE 哈希函数
│   ├── symmetric-shake.c   # 对称密码原语（SHAKE 版本）
│   ├── randombytes.c/h     # 密码学安全随机数生成
│   ├── params.h            # 算法参数定义
│   ├── config.h            # 编译配置
│   └── api.h               # 公开 API 接口
├── test/                   # 测试程序
│   ├── test_basic.c        # 基本功能测试
│   ├── test_dilithium.c    # 大规模正确性测试
│   ├── test_vectors.c      # 测试向量验证
│   ├── test_output.c       # 测试向量输出（供上位机验证）
│   ├── test_speed.c        # 性能基准测试
│   ├── test_mul.c          # 多项式乘法性能测试
│   ├── dilithium_verify.py # Python 上位机一致性验证工具
│   ├── cpucycles.c/h       # CPU 周期计数
│   └── speed_print.c/h     # 性能结果格式化输出
├── nistkat/                # NIST KAT 生成工具
└── Makefile                # 构建配置
```

## 编译构建

### 前置要求

- GCC（支持 C11）
- Make
- Windows 平台需链接 `bcrypt`（Makefile 已配置）

### 编译所有测试程序

```bash
make all
```

生成以下可执行文件：

| 程序 | 说明 |
|------|------|
| `test_basic.exe` | 基本功能测试 |
| `test_dilithium.exe` | 大规模正确性测试 |
| `test_vectors.exe` | 测试向量验证 |
| `test_output.exe` | 测试向量输出 |
| `test_speed.exe` | 性能基准测试 |
| `test_mul.exe` | 多项式乘法测试 |

### 清理构建文件

```bash
make clean
```

## 使用方法

### 1. 基本功能测试

测试密钥生成、签名、有效签名验证及无效签名拒绝：

```bash
./test_basic
```

### 2. 大规模正确性测试

执行 10,000 次签名和验证操作，确保算法正确性：

```bash
./test_dilithium
```

### 3. 测试向量验证

使用内置测试向量验证实现的一致性：

```bash
./test_vectors
```

### 4. 性能测试

输出密钥生成、签名、验证操作的平均时间和 CPU 周期数：

```bash
./test_speed
```

### 5. Python 上位机一致性验证

`test_output.exe` 生成测试向量并写入标准输出，Python 工具捕获后与参考库（`dilithium-py`）逐组比对，验证三项检验（密钥生成、签名、验证）的通过率。

安装依赖：

```bash
pip install dilithium-py
```

运行验证：

```bash
python ./test/dilithium_verify.py run --exe ./test_output.exe
```

也支持从文件解析测试向量：

```bash
python ./test/dilithium_verify.py parse --file vectors.txt
```

## API 说明

### 密钥生成

```c
int crypto_sign_keypair(uint8_t *pk, uint8_t *sk);
```

### 签名（附消息）

```c
int crypto_sign(uint8_t *sm, size_t *smlen,
                const uint8_t *m, size_t mlen,
                const uint8_t *ctx, size_t ctxlen,
                const uint8_t *sk);
```

### 验证（附消息）

```c
int crypto_sign_open(uint8_t *m, size_t *mlen,
                     const uint8_t *sm, size_t smlen,
                     const uint8_t *ctx, size_t ctxlen,
                     const uint8_t *pk);
```

### 分离式签名

```c
int crypto_sign_signature(uint8_t *sig, size_t *siglen,
                          const uint8_t *m, size_t mlen,
                          const uint8_t *ctx, size_t ctxlen,
                          const uint8_t *sk);

int crypto_sign_verify(const uint8_t *sig, size_t siglen,
                       const uint8_t *m, size_t mlen,
                       const uint8_t *ctx, size_t ctxlen,
                       const uint8_t *pk);
```

所有函数成功返回 `0`，失败返回非 `0`。支持可选的上下文字符串 `ctx` 以增强域分离安全性。

### 使用示例

```c
#include "api.h"
#include "randombytes.h"

uint8_t pk[CRYPTO_PUBLICKEYBYTES];
uint8_t sk[CRYPTO_SECRETKEYBYTES];
uint8_t sig[CRYPTO_BYTES];
uint8_t msg[] = "Hello, Dilithium!";
size_t siglen;

// 生成密钥对
crypto_sign_keypair(pk, sk);

// 分离式签名
crypto_sign_signature(sig, &siglen, msg, sizeof(msg), NULL, 0, sk);

// 验证签名
int ret = crypto_sign_verify(sig, siglen, msg, sizeof(msg), NULL, 0, pk);
// ret == 0 表示验证成功
```

## 技术特性

- 基于 **Module-LWE** 问题的格密码学方案
- 使用 **SHAKE256** 作为可扩展输出函数（XOF）
- 采用 **Fiat-Shamir with Aborts** 框架实现非交互式签名
- **NTT**（数论变换）加速多项式乘法，显著提升性能

## 安全说明

本实现为参考实现，优先保证正确性与可读性，适用于研究和教学目的。生产环境请使用经过安全审计的优化实现。

## 参考资料

- [CRYSTALS-Dilithium 官方网站](https://pq-crystals.org/dilithium/)
- [FIPS 204 标准文档](https://csrc.nist.gov/pubs/fips/204/final)
- [NIST PQC 标准化项目](https://csrc.nist.gov/projects/post-quantum-cryptography)