allensarkisyan/shamir_zero

# `ShamirZero` - Rust 实现的 Shamir 秘密共享

[](https://crates.io/crates/shamir-zero) [](https://docs.rs/shamir_zero) [](LICENSE-MIT) [](LICENSE-APACHE) [](https://github.com/allensarkisyan/shamir_zero/actions/workflows/codeql.yml)   [](https://codecov.io/gh/allensarkisyan/shamir_zero) [](https://securityscorecards.dev/viewer/?uri=github.com/allensarkisyan/shamir_zero) ## 原始源代码 [`github.com/hashicorp/vault/shamir/shamir.go`](https://github.com/hashicorp/vault/blob/v2.0.1/shamir/shamir.go) IBM / HashiCorp Vault 的 Shamir 秘密共享的 Rust 实现（最初使用 Go 编写，遵循 MPL-2.0 协议） **一个快速、零 `unsafe`、加密安全的 Rust Shamir 秘密共享 (SSS) 实现。** 将任何秘密拆分为 `n` 份，这样任何 `k` 份（阈值）都可以重建原始秘密，而 `k-1` 份不会泄露任何信息。 ## 功能 ### `fast-inverse`（默认启用） - 纯 Rust 实现，无 `unsafe`，除 `rand` 外无其他依赖 - 使用最新的 `SysRng`（系统 CSPRNG）实现完美前向保密 - 使用 Horner 方法进行高度优化的多项式求值 - 支持任意长度的秘密（包括拒绝空秘密） - 阈值和份额数最高可达 255 - 内存安全，并尽可能保持常数时间复杂度 - 卓越的性能 - 显著快于最初的 Go 参考实现 ### 零拷贝核心 API - `shamir_split` 接受预分配的输出缓冲区 `&mut [&mut [u8]]` - 消除所有中间内存分配，以实现最高性能和可预测的内存使用 - 非常适合高吞吐量、嵌入式或对延迟敏感的加密工作负载 ### 高级便捷封装 (`ShamirZero`) - 将零拷贝核心与熟悉的 `Vec>` 接口连接起来 - 每次操作内部仅分配一次内存，并委托给优化后的核心处理 - 提供 `split()` 和 `combine()` 方法以及自动错误处理 ## 安装 ``` [dependencies] shamir-zero = { version = "0.1", features = ["fast-inverse"] } # default # 或显式禁用： # shamir-zero = { version = "0.1", default-features = false } ``` 默认情况下，`shamir-zero` 使用 **编译时 256 字节查找表** 进行 GF(2^8) 中的乘法逆运算。 **为什么推荐将其作为默认选项：** - 重建 (`shamir_combine`) 速度大幅提升 - 通常比纯算术版本快 2–5 倍。 - 依然完全保持常数时间复杂度和防侧信道安全。 - 表格索引仅从 **公开** 的份额 ID（即 x 坐标）派生，绝不来自秘密数据。 你可以使用以下命令禁用查找表（并使用较慢但无表的算术版本）： ``` cargo build --no-default-features ``` 或者在你的 `Cargo.toml` 中： ``` shamir-zero = { version = "0.1", default-features = false } ``` 此选项专为极度偏执的嵌入式环境或学术上的“无查找表”要求而存在，但对于几乎所有用例来说都是不必要的。 ## 快速开始 ### 高级便捷封装 ``` use shamir_zero::{ShamirZero, ShamirError}; fn main() -> Result<(), ShamirError> { let secret = b"top secret security key"; // Split into 5 shares, any 3 can reconstruct let shares = ShamirZero::split(secret, 5, 3)?; // Reconstruct from any 3 shares let recovered = ShamirZero::combine(&shares[0..3])?; assert_eq!(recovered, secret); Ok(()) } ``` ### 核心零拷贝 API（最高性能） ``` use shamir_zero::{shamir_split, shamir_combine, ShamirError}; fn main() -> Result<(), ShamirError> { let secret = b"top secret security key"; let parts = 5; let threshold = 3; // Pre-allocate exactly once let mut shares = vec![vec![0u8; secret.len() + 1]; parts]; let shares_out: Vec<&mut [u8]> = shares.iter_mut().map(|s| s.as_mut_slice()).collect(); // Zero-copy split shamir_split(secret, parts, threshold, &mut shares_out)?; // Zero-copy combine let mut recovered = vec![0u8; secret.len()]; shamir_combine(&shares[0..threshold].iter().map(|s| s.as_slice()).collect::>(), &mut recovered)?; assert_eq!(recovered, secret); Ok(()) } ``` ## API 设计与零拷贝理念 `shamir_split` 经过了重新设计，要求提供一个输出缓冲区 (`&mut [&mut [u8]]`)，而不是返回 `Vec>`。这消除了： 1. `parts` 中间的 `Vec` 内存分配 2. 由于重复分配/释放导致的内存碎片化 3. 加密环境中不可预测的内存开销 对于大多数应用程序，**`ShamirZero` 封装**提供了相同的安全性和正确性以及熟悉的 API，且内部仅分配一次内存。当你需要显式内存控制或在受限环境中运行时，请使用核心 API。 ## 使用示例 ### 1. 字符串 / `&[u8]`（最常见） ``` let secret = b"0xdeadbeef"; let shares = ShamirZero::split(secret, 10, 5)?; let recovered = ShamirZero::combine(&shares[2..7])?; // any 5 shares ``` ### 2. `String`（具有所有权） ``` let secret = "0xcafe".to_string(); let shares = ShamirZero::split(secret.as_bytes(), 7, 4)?; let recovered_bytes = ShamirZero::combine(&shares[0..4])?; let recovered = String::from_utf8(recovered_bytes).unwrap(); ``` ### 3. `Vec` ``` let secret: Vec = vec![0x01, 0x02, 0x03, 0xFF, 0xAA]; let shares = ShamirZero::split(&secret, 8, 3)?; let recovered = ShamirZero::combine(&shares[3..6])?; ``` ### 4. 固定大小数组 (`[u8; N]`) - 非常适合密钥 ``` let secret: [u8; 32] = [0x42; 32]; // 256-bit key let shares = ShamirZero::split(&secret, 6, 4)?; let recovered: Vec = ShamirZero::combine(&shares[1..5])?; let recovered_array: [u8; 32] = recovered.try_into().unwrap(); ``` ### 5. 数值型秘密（例如 `u128`、`u64` 等） ``` let number: u128 = 12345678901234567890; let secret_bytes = number.to_le_bytes(); let shares = ShamirZero::split(&secret_bytes, 5, 3)?; let recovered_bytes = ShamirZero::combine(&shares[0..3])?; let recovered_number = u128::from_le_bytes(recovered_bytes.try_into().unwrap()); ``` ### 6. 包含错误处理的完整往返过程 ``` fn split_and_recover(secret: &[u8], parts: usize, threshold: usize) -> Result, ShamirError> { let shares = ShamirZero::split(secret, parts, threshold)?; ShamirZero::combine(&shares[0..threshold]) // any `threshold` shares work } ``` ## Shamir 秘密共享算法的历史 **Shamir 秘密共享**由以色列密码学家 **Adi Shamir** 于 1979 年在他的论文中提出 _“如何共享一个秘密”_ (How to Share a Secret)（ACM 通讯，第 22 卷，第 11 期）。 该算法是一种基于有限域上 **多项式插值** 的 **阈值方案** （在实践中，对于字节级别的秘密使用 GF(256)）。它保证了： - 任何 `threshold` (k) 个或更多的份额都可以精确重建秘密。 - 少于 `threshold` 个份额对秘密提供 **零信息**（信息论级别的安全）。 - 原始秘密是一个次数为 `threshold-1` 的随机多项式的常数项。 它仍然是密码学中使用最广泛的秘密共享方案之一，为多方钱包、备份系统和分布式密钥管理等一切场景提供支持。 ## 关于 Adi Shamir **Adi Shamir**（生于 1952 年）是世界著名的以色列密码学家，也是魏茨曼科学研究所的教授。 他最著名的身份是 **RSA 中的“S”** - 这是他于 1977 年与 Ronald Rivest 和 Leonard Adleman 共同发明的公钥密码系统。RSA 彻底改变了安全通信，并且至今仍是大多数互联网安全的基石。 1979 年，Shamir 发表了他的秘密共享方案，解决了密码学中长期存在的一个问题： 如何在多方之间分配秘密，使得只有授权的子集才能恢复它。 他还做出了许多其他基础性贡献，包括差分密码分析（与 Eli Biham 合作）、Shamir–Adleman–Rivest 签名方案以及基于身份的密码学。 2002 年，Shamir、Rivest 和 Adleman 因其在公钥密码学方面的工作获得了 **图灵奖** - 这是计算机科学领域的最高荣誉。 ## 性能与针对原始 Go 实现的改进 此 Rust 实现是从流行的 Go 参考实现移植并经过深度优化的。以下是它的改进之处： | 方面 | 原始 Go | ShamirZero | 优势 | | --------------------------- | -------------------- | -------------------------------------------------- | ------------------------------------- | | 随机数 | `crypto/rand` | `rand::rngs::SysRng` (2024+) | 更快，零大小，保证 CSPRNG | | 多项式求值 | 标准循环 | 内联 Horner 方法 (`#[inline(always)]`) | 每字节快约 3–4 倍 | | 内存分配 | 多次分配 | **零拷贝核心** / 一次分配 (`ShamirZero`) | 更低的峰值内存和更少的分配次数 | | 错误处理 | `error` 接口 | 零成本 `Result` 和自定义 enum | 错误路径上无堆内存分配 | | 安全性 | GC + 运行时检查 | 编译期所有权与借用检查 | 构造上保证内存安全 | | 构建与 CI | Go modules | 现代 Rust + cargo-llvm-cov | 更快的 CI，更好的覆盖率 | | 性能（大型秘密） | 基准测试 | 在 1 KB+ 秘密上 **快约 2.8 倍** | 真实世界的性能 | 有关高级用法，请参阅 [docs.rs 上的完整 API 文档](https://docs.rs/shamir_zero)。 # 开发与测试 ### 代码质量与覆盖率报告 ``` cargo clippy --all-targets &> ./tmp/clippy.log ``` 或者使用在 `.cargo/config.toml` 中配置的 `clippy-log` 别名
``` cargo install cargo-tarpaulin ``` ``` cargo tarpaulin --follow-exec --timeout 60 --branch --out Html --output-dir ./tmp/coverage ``` 或者使用在 `.cargo/config.toml` 中配置的 `coverage-report` 别名 ``` cargo coverage-report ``` ## 基准测试 此 crate 附带了 **四个专用的 Criterion 基准测试**，可全面测量 Shamir 秘密共享操作的性能。 ### 可用的基准测试目标 | 基准测试目标 | 类型 | 秘密大小 | 配置数量 | 描述 | | ------------------------------------- | ------------------ | ----------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `shamir_zero_benchmark` | 往返 | 64 字节 | 5 | 针对常见小型配置的快速往返（`split → combine`） | | `shamir_split_benchmark` | 仅拆分 | 64 字节 | 5 | 纯 `shamir_split` 性能 | | `shamir_combine_benchmark` | 仅组合 | 64 字节 | 5 | 纯 `shamir_combine` 性能 | | `shamir_zero_comprehensive_benchmark` | **完整往返** | 8 B – 32 KB | 23 | **最全面** – 测试所有秘密大小以及大范围的 `(parts, threshold)` 对（包括高达 255-of-255 的边缘情况） | ### 如何运行基准测试 ``` # 运行所有 benchmarks cargo bench # 运行特定 benchmark cargo bench --bench shamir_zero_benchmark cargo bench --bench shamir_split_benchmark cargo bench --bench shamir_combine_benchmark # 运行完整的综合 benchmark cargo bench --bench shamir_zero_comprehensive_benchmark ``` ### 生成精美的 HTML 报告 ``` # 生成详细的交互式 HTML 报告（强烈推荐） cargo bench --bench shamir_zero_benchmark -- --save-baseline main # 与之前的 baseline 进行比较 cargo bench --bench shamir_zero_benchmark -- --baseline main ``` HTML 报告将保存在： ``` target/criterion/shamir_zero_benchmark_full/ ``` 在浏览器中打开 `target/criterion/shamir_zero_benchmark_full/report/index.html` 即可查看交互式图表、吞吐量 (MB/s)、延迟统计信息和火焰图。 ### 综合基准测试测量内容 `shamir_zero_comprehensive_benchmark` 运行 **276 次单独测量**（12 种秘密大小 × 23 种配置），并专注于 **完整往返**（`shamir_split` 后立即执行 `shamir_combine`）。 这为真实世界的用例提供了端到端性能的最真实视角。 **提示：** 本 README “性能与改进”部分中显示的数字均来自综合基准测试。
## 性能与改进 `shamir-zero` 是一个针对典型字节秘密（GF(256) 域）的快速零拷贝纯 Rust 实现的 Shamir 秘密共享算法。 ### 往返基准测试（拆分 + 恢复） **参数**：`t=5`，`n=10`（10 份中的 5 份阈值） | 秘密大小 | shamir-zero (高级) | **shamir-zero (零拷贝预分配)** | sharks | ssskit | **对比 ssskit 的胜出者** | |-------------|--------------------------|-------------------------------------------|------------|------------|----------------------| | 32 B | 7.53 µs | **7.32 µs** | 8.51 µs | 7.55 µs | **+3.1 %** | | 64 B | 14.20 µs | **13.98 µs** | 17.13 µs | 15.43 µs | **+9.4 %** | | 128 B | 27.53 µs | **27.31 µs** | 33.95 µs | 30.77 µs | **+11.2 %** | | 256 B | 54.06 µs | **53.83 µs** | 67.14 µs | 61.12 µs | **+11.9 %** | | 1024 B | 213.4 µs | **213.1 µs** | 264.9 µs | 242.4 µs | **+12.1 %** | | 2048 B | 427.2 µs | **426.2 µs** | 533.4 µs | 485.0 µs | **+12.1 %** | **所有数字均为平均往返时间（越低 = 好）。** 在同一台机器上使用 Criterion.rs 进行测量（各次运行的结果极其一致）。 **零拷贝预分配** API 是绝对最快的路径，推荐用于高性能或内存受限的环境。 **为什么 `shamir-zero` 这么快？** - 零拷贝核心路径（无隐藏分配） - 用于快速乘法逆运算的编译期查找表 - 纯安全的 Rust，依赖极少 - 经过精心调优的 GF(256) 算术 ## 验证发布完整性 所有版本均使用 **Sigstore** 进行加密认证，并记录到公开的 Rekor 透明度日志中。 ### 验证发布版本 ``` # 1. 下载 .crate gh release download -R allensarkisyan/shamir_zero --pattern "shamir-zero-*.crate" ``` ``` # 2. 验证 attestation（包含 provenance + SBOM） gh attestation verify shamir-zero-*.crate -R allensarkisyan/shamir_zero \ --predicate-type "https://cyclonedx.org/bom" ``` # 许可证 `shamir-zero` 采用 MIT 许可证和 Apache 许可证（版本 2.0）双重许可。 你可以根据自己的意愿选择使用任一许可证。 - [MIT License](LICENSE-MIT) - [Apache License, Version 2.0](LICENSE-APACHE) HashiCorp Vault 的原始 Go 实现采用 MPL-2.0 许可。 此 Rust 移植版已根据更宽松的 MIT/Apache-2.0 双重许可重新授权。 MIT License Copyright (c) 2026 Allen Sarkisyan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## 贡献 欢迎各种贡献！如果你有任何建议、错误报告，或者想要为本项目做贡献， 请开启一个 issue 或提交一个 pull request。 ## 作者 [Allen Sarkisyan](https://www.linkedin.com/in/allensarkisyan) Copyright (c) 2026 Allen Sarkisyan. XT-TX. All Rights Reserved.

标签：Rust, Shamir秘密共享, 可视化界面, 密码学, 手动系统调用, 网络流量审计, 通知系统, 零拷贝