# rscrypto
[](https://crates.io/crates/rscrypto)
[](https://docs.rs/rscrypto)
[](https://github.com/loadingalias/rscrypto/actions/workflows/ci.yaml)
[](Cargo.toml)
[](#license)
**一个 Rust 加密库，专为需要高性能、可移植性和极简依赖图的系统而设计。**
`rscrypto` 在一致的 API 背后为您提供了哈希、MAC、KDF、密码哈希、签名、密钥交换、AEAD 加密、校验和以及快速的非加密哈希。
只需一个叶级特性（leaf feature）即可实现精简构建。使用 `full` 获取完整的工具箱。无需 C 代码，无需 FFI，无需 OpenSSL，不强制使用任何第三方依赖栈。
最新公开基准测试结果。高于 1.00x 的数值表示 rscrypto 比对比的 Rust 基准更快。
## 为什么选择 rscrypto？
- **使用单一的 crate，而非拼凑的加密栈。** 涵盖了常见的密码学原语家族，无需您去组合半打不同的 API。
- **需要小时即可小。** 诸如 `sha2`、`blake3`、`aes-gcm`、`chacha20poly1305`、`ed25519`、`x25519` 和 `argon2` 这样的叶特性让构建更聚焦。
- **可移植的 Rust 优先。** 可移植的实现是事实来源；经过优化的内核是加速器，而非独立的逻辑分支。
- **在关键处提供硬件加速。** 运行时和编译时分发在支持的 x86/x86_64、Arm/AArch64、IBM Z、POWER、RISC-V、Apple Silicon 和 WASM 目标上使用特定于 ISA 的内核。
- **支持 `no_std`。** 为服务器、CLI、嵌入式目标、裸机实验和 WASM 而构建。
- **默认零第三方依赖。** `getrandom`、`serde` 和 `rayon` 均为按需启用。
- **默认具备安全防护。** 恒定时间验证、不透明错误、归零化的机密数据、严格的算术运算、官方测试向量、模糊测试、Miri 以及跨多个 CPU 目标的 CI。
`rscrypto` 是一个密码学原语库。它**不是** TLS 栈、PKI 工具包、协议实现或经过 FIPS 140-3 验证的模块。
## 安装
最小的 `no_std` SHA-2 构建：
```
[dependencies]
rscrypto = { version = "0.1", default-features = false, features = ["sha2"] }
```
启用操作系统随机性的完整工具箱：
```
[dependencies]
rscrypto = { version = "0.1", features = ["full", "getrandom"] }
```
在受限的 `no_std` 构建中使用 `default-features = false`。仅在需要从操作系统生成盐值、密钥或随机数的 API 时才启用 `getrandom`。
## 快速开始
```
use rscrypto::{Sha256, prelude::*};
let one_shot = Sha256::digest(b"hello world");
let mut h = Sha256::new();
h.update(b"hello ");
h.update(b"world");
assert_eq!(h.finalize(), one_shot);
```
这就是基本的 API 形态：方便时使用一次性接口，需要时使用流式接口。
## 加密数据
```
[dependencies]
rscrypto = { version = "0.1", default-features = false, features = ["chacha20poly1305"] }
```
```
use rscrypto::{aead::Nonce96, Aead, ChaCha20Poly1305, ChaCha20Poly1305Key};
let key = ChaCha20Poly1305Key::from_bytes([0x11; 32]);
let nonce = Nonce96::from_bytes([0x22; Nonce96::LENGTH]);
let cipher = ChaCha20Poly1305::new(&key);
let aad = b"transfer:v1";
let mut message = *b"pay bob 10";
let tag = cipher
.encrypt_in_place(&nonce, aad, &mut message)
.expect("encryption succeeds");
cipher
.decrypt_in_place(&nonce, aad, &mut message, &tag)
.expect("authentication succeeds");
assert_eq!(&message, b"pay bob 10");
```
## 哈希密码
```
[dependencies]
rscrypto = { version = "0.1", default-features = false, features = ["argon2", "phc-strings", "getrandom"] }
```
```
use rscrypto::{Argon2Params, Argon2VerifyPolicy, Argon2id};
let password = b"correct horse battery staple";
let params = Argon2Params::new().build().expect("valid Argon2 params");
let encoded = Argon2id::hash_string(¶ms, password).expect("password hash created");
assert!(
Argon2id::verify_string_with_policy(
password,
&encoded,
&Argon2VerifyPolicy::default(),
)
.is_ok()
);
```
## 功能一览
| 需求 | 包含内容 | 特性路径 |
|---|---|---|
| 加密哈希 | SHA-2, SHA-3, SHAKE, cSHAKE256, BLAKE2, BLAKE3, Ascon-Hash/XOF/CXOF | `hashes` 或叶特性 |
| MAC 和 KDF | HMAC-SHA-2, KMAC256, HKDF-SHA-2, PBKDF2-HMAC-SHA-2 | `auth` 或叶特性 |
| 密码哈希 | Argon2d/i/id, scrypt, PHC 字符串编码/验证 | `auth`, `argon2`, `scrypt`, `phc-strings` |
| 公钥原语 | Ed25519 签名, X25519 密钥交换 | `auth`, `ed25519`, `x25519` |
| AEAD 加密 | AES-128/256-GCM, AES-128/256-GCM-SIV, ChaCha20-Poly1305, XChaCha20-Poly1305, AEGIS-256, Ascon-AEAD128 | `aead` 或叶特性 |
| 校验和 | CRC-16, CRC-24, CRC-32, CRC-32C, CRC-64/XZ, CRC-64/NVMe | `checksums` 或叶特性 |
| 快速非加密哈希 | XXH3-64/128, RapidHash 64/128 | `xxh3`, `rapidhash` |
快速非加密哈希和 CRC 用于索引、校验、去重和完整性管道。请勿将其用于密码、签名、MAC、密钥派生或身份验证。
BLAKE3 使用标准的 BLAKE3 结构，但遵循 `rscrypto` 的部署模型：叶特性构建、可移植的事实来源、可选的并行和 ISA 加速、差异化测试，以及用于受审计约束构建的 `portable-only`。
特性标志经过了刻意的分层设计：
- **叶原语：** `sha2`, `blake3`, `aes-gcm`, `ed25519`, `x25519`, `crc32` 等。
- **家族：** `hashes`, `checksums`, `macs`, `kdfs`, `password-hashing`, `aead`, `signatures`, `key-exchange`。
- **部署控制：** `std`, `alloc`, `getrandom`, `parallel`, `serde`, `serde-secrets`, `portable-only`。
完整的特性清单：[`docs/features.md`](docs/features.md)。公共类型清单：[`docs/types.md`](docs/types.md)。
## 性能
最新公开基准测试结果：Linux 以及 macOS Apple Silicon 平台，与现有的 Rust 基准进行对比。加速比计算方式为 `external_crate_time / rscrypto_time`；高于 `1.00x` 的数值表示 `rscrypto` 更快。
| 领域 | 对比对象 | 结果 |
|---|---|---:|
| **Linux 总体** | 最强的匹配 Rust 基准 | **1.75x 几何平均数** |
| 匹配对比项 | Linux | **3,717 胜 / 5,796 对** |
| 校验和 | `crc`, `crc32fast`, `crc64fast`, `crc-fast` | **4.41x 几何平均数** |
| SHA-3 / SHAKE | RustCrypto `sha3` | **2.18x / 2.60x 几何平均数** |
| BLAKE3, `>=64 KiB` | `blake3` | **2.37x 几何平均数** |
| AEAD | RustCrypto AEADs, `aegis` | **1.84x 几何平均数** |
| Ed25519 签名 | `ed25519-dalek` | **1.57x 几何平均数** |
macOS Apple Silicon 的测试结果包括 AEAD 达到 **2.60x**、校验和达到 **4.18x**，在 SHA-2 和 SHA-3 上则保持了广泛的持平。
有关原始运行数据、测试方法、主机详情和各平台评分卡，请参见 [`benchmark_results/OVERVIEW.md`](benchmark_results/OVERVIEW.md)。
## 可移植性与加速
`rscrypto` 将可移植的 Rust 路径作为逐字节的权威基准。只有在目标和运行时 CPU 支持时，才会选择特定于 ISA 的内核。
| 目标家族 | 加速示例 |
|---|---|
| x86 / x86_64 | SSE4.2, AVX2, AVX-512, AES-NI, SHA-NI, VAES, VPCLMULQDQ |
| Arm / AArch64 / Apple Silicon | NEON, AES, PMULL, SHA2, SHA3, SVE2-PMULL |
| IBM Z | CPACF, MSA, VGFM |
| POWER / ppc64le | POWER8/9/10 向量和加密扩展 |
| RISC-V | RVV, Zbc, Zvkned, Zvbc |
| WASM | 可用处的 SIMD128，全面提供可移植后备方案 |
当您需要确定性分发、受审计约束的构建或仅使用可移植后端时，请使用 `portable-only`。
完整的平台矩阵：[`docs/platforms.md`](docs/platforms.md)。架构说明：[`docs/architecture.md`](docs/architecture.md)。
## 安全态势
- 恒定时间的 MAC、AEAD 和签名验证。
- 不透明的验证错误，避免泄露失败细节。
- 携带机密的类型在释放时进行归零化处理，并屏蔽 `Debug` 输出。
- 针对计数器、长度、偏移量和索引的严格算术运算。
- AEAD 失败时的开放路径会擦除输出缓冲区。
- 可移植和加速后端经过差异化测试，确保逐字节输出一致。
- CI 中运行官方测试向量、模糊测试语料库重放、Miri、`cargo deny` 和 `cargo audit`。
在发布加密代码之前，请阅读 [`docs/security.md`](docs/security.md)。有关合规性态势，请参见 [`docs/compliance.md`](docs/compliance.md)。
漏洞应通过 [GitHub 私有漏洞报告](https://github.com/loadingalias/rscrypto/security/advisories/new)或 [`SECURITY.md`](SECURITY.md) 中的流程进行报告。
## 文档
- API 参考：[docs.rs/rscrypto](https://docs.rs/rscrypto)
- 示例：[`examples/`](examples/)
- 特性标志：[`docs/features.md`](docs/features.md)
- 平台矩阵：[`docs/platforms.md`](docs/platforms.md)
- 安全指南：[`docs/security.md`](docs/security.md)
- 迁移指南：[`docs/migration/`](docs/migration/)
- 基准测试方法：[`docs/benchmarking.md`](docs/benchmarking.md)
- 基准测试结果：[`benchmark_results/OVERVIEW.md`](benchmark_results/OVERVIEW.md)
- 发布历史：[`CHANGELOG.md`](CHANGELOG.md)
## MSRV
Rust **1.91.0**。
[`rust-toolchain.toml`](rust-toolchain.toml) 中固定的 nightly 版本用于 Miri、模糊测试和特殊架构检查。
## 许可证
根据 [Apache-2.0](LICENSE-APACHE) 或 [MIT](LICENSE-MIT) 双重许可，任您选择。