Quantus-Network/qp-rusty-crystals

# Rusty Crystals ML-DSA (CRYSTALS-Dilithium) 后量子数字签名方案的 Rust 实现，支持分层确定性 (HD) 钱包。 此 workspace 提供了与 BIP-32、BIP-39 和 BIP-44 标准兼容的后量子密码学原语和 HD 钱包功能。 ## 安全特性 此实现提供了企业级的内存安全： - **敏感数据的编译期复制防护** - `SensitiveBytes32`、`SensitiveBytes64`、`Keypair`、`SecretKey`、`ExtendedPrivKey` 和 `WormholePair` 故意**不**实现 `Clone`。密钥材料只能被移动。任何复制都必须通过 `to_bytes()`/`from_bytes()` 显式往返进行，使得复制操作在调用处可见。 - **自动内存清零** - 传递给构造函数的源数组以及所有包装器内容在 drop 时会被清零 (`ZeroizeOnDrop`)。传递给 `mnemonic_to_seed` 的助记词字符串被包装在 `Zeroizing` 中，并在**每条**退出路径（包括解析失败和 panic unwind）上进行清除。 - **显式敏感数据处理** - API 要求使用 `(&mut entropy).into()` 语法，使敏感操作变得显眼，并在传输时清零调用者的缓冲区。 - **有限制的派生路径** - `derive_key_from_seed` 和 `generate_wormhole_from_seed` 会拒绝字节长度超过 `MAX_DERIVATION_PATH_BYTES` (256) 或段数超过 `MAX_DERIVATION_DEPTH` (16) 的路径，**在任何内存分配或 HMAC 工作之前**，防止通过攻击者控制的深层路径进行 DoS。 ``` // Secure by design - entropy is zeroized after conversion let mut entropy = [0u8; 32]; getrandom::getrandom(&mut entropy).unwrap(); let keypair = ml_dsa_87::Keypair::generate((&mut entropy).into()); // entropy is now [0,0,0,...] - no sensitive data left in memory // If you genuinely need a second copy of a keypair, you must opt in explicitly: let kp_bytes = keypair.to_bytes(); let keypair2 = ml_dsa_87::Keypair::from_bytes(&kp_bytes)?; // Prefer passing &Keypair instead of duplicating secrets. ``` 这消除了密码学应用中与敏感数据处理相关的整类安全漏洞。 ## 概述 此 workspace 包含两个独立的 crate： - **`qp-rusty-crystals-dilithium`** - ML-DSA 数字签名实现 - **`qp-rusty-crystals-hdwallet`** - 用于后量子密钥的 HD 钱包 ## 用法 ### ML-DSA 数字签名 ``` [dependencies] qp-rusty-crystals-dilithium = "2.0.0" getrandom = "0.2" # For secure entropy generation if needed ``` **安全提示**：在为密码学操作生成熵时，请务必使用密码学安全的随机源。切勿使用可预测的字符串、时间戳或用户输入作为熵。 ``` use qp_rusty_crystals_dilithium::ml_dsa_87; // Generate secure entropy let mut entropy = [0u8; 32]; getrandom::getrandom(&mut entropy).expect("Failed to generate entropy"); // Generate keypair let keypair = ml_dsa_87::Keypair::generate((&mut entropy).into()).expect("Failed to generate keypair"); // Sign message let message = b"Hello, post-quantum world!"; let signature = keypair.sign(message, None, None); // Verify signature let is_valid = keypair.verify(message, &signature, None); ``` ### HD 钱包 ``` [dependencies] qp-rusty-crystals-hdwallet = "1.0.0" ``` ``` use qp_rusty_crystals_hdwallet::{generate_mnemonic, HDLattice}; // Generate secure seed for mnemonic let mut seed = [0u8; 32]; getrandom::getrandom(&mut seed).expect("Failed to generate seed"); // Generate mnemonic let mnemonic = generate_mnemonic((&mut seed).into())?; // Create HD wallet let hd_wallet = HDLattice::from_mnemonic(&mnemonic, None)?; // Derive keys using BIP-44 path let keys = hd_wallet.generate_derived_keys("44'/0'/0'/0'/0'")?; ``` ## Crates ### qp-rusty-crystals-dilithium ML-DSA 数字签名实现： - **ML-DSA-44, ML-DSA-65, ML-DSA-87** - 所有安全级别 - **符合 NIST 标准** - 已通过官方测试向量验证 - **纯 Rust 实现** - 内存安全，无 unsafe 代码 - **高性能** - 经优化的实现 ### qp-rusty-crystals-hdwallet 后量子 HD 钱包： - **兼容 BIP-39** - 助记词生成/恢复 - **BIP-32 派生** - 分层确定性密钥 - **BIP-44 路径** - 标准派生路径 - **仅限强化密钥** - 安全的后量子派生 ## 测试 运行所有测试： ``` cargo test --workspace ``` 获取测试覆盖率： ``` cargo install cargo-tarpaulin cargo tarpaulin --workspace ``` ### NIST KAT 测试 'verify_integration_tests.rs' 中的 test_nist_kat 测试用例涵盖了从 PQCrystals 为 ML-DSA-87 生成的 NIST KAT 测试用例。 我们从 PQ-Crystals 的 C 代码中导出了该测试文件，并在此处导入进行测试。 要重新生成此文件... ``` git clone https://github.com/pq-crystals/dilithium cd dilithium/ref make nistkat ./nistkat/PQCgenKAT_sign5 cp ./nistkat/PQCsignKAT_Dilithium5.rsp ??? ``` ## 代码覆盖率 此仓库的所有关键逻辑和功能均达到了 100% 的代码覆盖率。 ```./coverage.sh``` ## 许可证 [GPL-3.0](LICENSE) - 详情请参阅 LICENSE 文件。 ## 鸣谢 ml-dsa 的代码几乎是原样借鉴自 [Quantum Blockchain 的移植版本](https://github.com/Quantum-Blockchains/dilithium) ，即 [pq-crystals](https://github.com/pq-crystals/dilithium) 的 Rust 移植。

标签：CVE, HD钱包, ML-DSA, Rust, 内存安全, 加密算法库, 可视化界面, 后量子密码学, 数字签名, 网络流量审计, 通知系统