# kyberlib
一个强大的 Rust 库，用于 CRYSTALS-Kyber 后量子密码学。
[][05] [][07] [][09] [][08] [][02] [][15]
• [网站][00] • [文档][08] • [报告问题][03] • [功能请求][03] • [贡献指南][04]
## 概述 📖
KyberLib 是一个强大的 Rust 库，专为 **CRYSTALS-Kyber 后量子密码学** 设计，提供强大的安全保证。该库兼容 `no_std`，适用于嵌入式设备，且不进行内存分配。此外，它包含无 unsafe 代码的参考实现，并在 x86_64 平台上默认提供优化的 AVX2 版本。您还可以使用 wasm-bindgen 将其编译为 WebAssembly (WASM)。
## 功能特性 ✨
### 核心功能
- **兼容 `no_std`**：不依赖 Rust 标准库
- **避免内存分配**：仅使用基于栈的数据结构
- **可配置**：通过功能特性启用不同的参数集
- **优化的 x86_64**：对性能关键代码使用汇编，包括默认优化的 AVX2 版本。
- **安全代码**：参考实现没有 `unsafe` 代码块
- **WebAssembly 支持**：可以使用 wasm-bindgen 编译为 WASM。
### 高级功能
- **无分配保证**：KyberLib 保证其所有核心密码操作都无需堆内存分配。
- **汇编优化**：x86_64 汇编实现使用 AVX2 指令以实现高性能。
- **安全性**：KyberLib 的公共 API 表面不包含任何 unsafe 代码。
## 功能 📚
- **密钥生成**：创建公钥/私钥对
- **封装**：使用公钥封装共享密钥
- **解封装**：使用私钥解封装共享密钥
- **密钥交换**：执行认证密钥交换
有关完整的 API 详细信息，请参阅[文档][08]。
## 入门 🚀
只需几分钟即可启动并运行 `kyberlib`。
### 要求
当前支持的最低 Rust 工具链版本为 Rust **1.60** 或更高版本（稳定版）。
### 安装
要在您的机器上安装 `kyberlib`，您需要安装 Rust 工具链。您可以按照 [Rust 网站][13] 上的说明安装 Rust 工具链。
安装 Rust 工具链后，您可以使用以下命令安装 `kyberlib`：
```
cargo install kyberlib
```
## 使用方法 📖
要在项目中使用 `kyberlib` 库，请将以下内容添加到您的 `Cargo.toml` 文件中：
```
[dependencies]
kyberlib = "0.0.6"
```
将以下内容添加到您的 `main.rs` 文件中：
```
extern crate kyberlib;
use kyberlib::*;
```
然后您可以在应用程序代码中使用这些函数。
要在 x86 平台上进行优化，请启用 `avx2` 功能并设置以下 RUSTFLAGS：
```
export RUSTFLAGS="-C target-feature=+aes,+avx2,+sse2,+sse4.1,+bmi2,+popcnt"
```
## Crate 功能特性 📦
### 密钥封装
```
// Generate Keypair
let keys_bob = keypair(&mut rng)?;
// Alice encapsulates a shared secret using Bob's public key
let (ciphertext, shared_secret_alice) = encapsulate(&keys_bob.public, &mut rng)?;
// Bob decapsulates a shared secret using the ciphertext sent by Alice
let shared_secret_bob = decapsulate(&ciphertext, &keys_bob.secret)?;
assert_eq!(shared_secret_alice, shared_secret_bob);
```
### 单方认证密钥交换
```
let mut rng = rand::thread_rng();
// Initialize the key exchange structs
let mut alice = Uake::new();
let mut bob = Uake::new();
// Generate Bob's Keypair
let bob_keys = keypair(&mut rng)?;
// Alice initiates key exchange
let client_init = alice.client_init(&bob_keys.public, &mut rng)?;
// Bob authenticates and responds
let server_response = bob.server_receive(
client_init, &bob_keys.secret, &mut rng
)?;
// Alice decapsulates the shared secret
alice.client_confirm(server_response)?;
// Both key exchange structs now have the same shared secret
assert_eq!(alice.shared_secret, bob.shared_secret);
```
### 双方认证密钥交换
遵循相同的工作流程，只是 Bob 需要 Alice 的公钥：
```
let mut alice = Ake::new();
let mut bob = Ake::new();
let alice_keys = keypair(&mut rng)?;
let bob_keys = keypair(&mut rng)?;
let client_init = alice.client_init(&bob_keys.public, &mut rng)?;
let server_response = bob.server_receive(
client_init, &alice_keys.public, &bob_keys.secret, &mut rng
)?;
alice.client_confirm(server_response, &alice_keys.secret)?;
assert_eq!(alice.shared_secret, bob.shared_secret);
```
## 宏 🦀
KyberLib crate 提供了多个宏来简化常见的密码操作：
- [`kyberlib_generate_key_pair!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_generate_key_pair.html)：为 CCA 安全的 Kyber 密钥封装机制生成公钥和私钥对。
- [`kyberlib_encrypt_message!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_encrypt_message.html)：为给定公钥生成密文和共享密钥。
- [`kyberlib_decrypt_message!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_decrypt_message.html)：为给定密文和私钥生成共享密钥。
- [`kyberlib_uake_client_init!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_client_init.html)：启动单方认证密钥交换。
- [`kyberlib_uake_server_receive!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_server_receive.html)：处理 `kyberlib_uake_client_init()` 请求的输出。
- [`kyberlib_uake_client_confirm!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_client_confirm.html)：解封装并认证来自 `kyberlib_uake_server_receive()` 输出的共享密钥。
- [`kyberlib_ake_client_init!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_ake_client_init.html)：启动双方认证密钥交换。
- [`kyberlib_ake_server_receive!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_uake_server_receive.html)：处理并认证 `kyberlib_ake_client_init()` 请求的输出。
- [`kyberlib_ake_client_confirm!`](https://docs.rs/kyberlib/latest/kyberlib/macro.kyberlib_ake_client_confirm.html)：解封装并认证来自 `kyberlib_ake_server_receive()` 输出的共享密钥。
有关更多详细信息和使用示例，请参阅[宏模块文档](
标签：AI工具, AVX2优化, CRYSTALS-Kyber, NIST后量子密码标准, no_std, Rust库, WASM, wasm-bindgen, WebAssembly, x86_64优化, 公钥密码学, 内存安全, 加密算法, 可视化界面, 后量子密码学, 密码学, 密钥封装, 嵌入式系统, 性能优化, 手动系统调用, 无unsafe代码, 栈分配, 检测绕过, 自动回退, 通知系统, 量子安全