CryptoHives/Foundation
GitHub: CryptoHives/Foundation
面向 .NET 生态的社区驱动密码学与高性能基础库集合，提供独立于操作系统的加密算法实现、零分配异步原语和池化内存管理工具。
Stars: 5 | Forks: 2
## 🛡️ CryptoHives 开源倡议 🐝
一个面向 .NET 生态系统的开放、社区驱动的密码学与高性能库集合。
尽管 .NET 已成为在各种平台上为各类用例构建安全、高性能应用程序的强大平台，但我们仍需将高性能模式封装为易于使用的库，并重新审视密码学为何严重依赖特性与性能各异的不同操作系统底层实现。
CryptoHives 开源倡议的目标正是为了解决这一问题，提供一系列相关的包。
## 🏗️ 架构概述
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CryptoHives .NET Foundation │
│ CryptoHives Open Source Initiative │
└─────────────────────────────────────────────────────────────────────────────────┘
│
┌───────────────────────────┼────────────────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────────┐ ┌───────────────────────┐ ┌────────────────────────────┐
│ Memory │ │ Threading │ │ Security.Cryptography │
├────────────────────┤ ├───────────────────────┤ ├────────────────────────────┤
│ ArrayPool- │ │ AsyncLock │ │ Hash │
│ MemoryStream │ │ AsyncSemaphore │ │ SHA-2 · SHA-3 │
│ ArrayPool- │ │ AsyncAutoResetEvent │ │ SHAKE · cSHAKE │
│ BufferWriter │ │ AsyncManualResetEvent │ │ TurboSHAKE · KT128/256 │
│ ReadOnlySequence- │ │ AsyncReaderWriterLock │ │ ParallelHash (SP 800-185) │
│ MemoryStream │ │ AsyncBarrier │ │ KMAC128 · KMAC256 │
│ Ownership │ │ AsyncCountdownEvent │ │ Keccak · BLAKE2 · BLAKE3 │
│ Primitives │ │ │ │ Ascon · Regional · Legacy │
│ │ │ IValueTaskSource │ │ │
│ │ │ backed by │ │ MAC │
│ │ │ ObjectPool │ │ HMAC · KMAC │
│ │ │ │ │ AES-CMAC · AES-GMAC │
│ │ │ │ │ Poly1305 · BLAKE2/3 │
│ │ │ │ │ │
│ │ │ │ │ Cipher │
│ │ ├───────────────────────┤ │ AES-GCM/CCM (AEAD) │
│ │ │ Threading.Analyzers │ │ ChaCha20-Poly1305 │
│ │ │ ValueTask Roslyn │ │ XChaCha20-Poly1305 │
│ │ │ analyzers │ │ Ascon-AEAD128 │
└────────────────────┘ └───────────────────────┘ │ AES-128/192/256 │
│ ChaCha20 (stream) │
│ SM4 · ARIA · Camellia │
│ Kuznyechik · Kalyna │
│ SEED │
│ │
│ Key Derivation │
│ HKDF · KBKDF │
│ ConcatKDF · PBKDF2 │
└────────────────────────────┘
Keccak class hierarchy (Security.Cryptography):
HashAlgorithm
└── KeccakCore (Keccak-p[1600] sponge, AVX2/SSSE3/scalar dispatch)
├── KeccakHashCore (fixed-length)
│ ├── SHA3_{224,256,384,512}
│ └── Keccak{256,384,512} (Ethereum-compatible, domain sep 0x01)
├── KeccakXofCore : IExtendableOutput (variable-length)
│ ├── Shake{128,256} (domain sep 0x1F, rate 168/136 bytes)
│ ├── TurboShake{128,256} (12-round Keccak, domain sep 0x7F/0x7E)
│ └── KT{128,256} (KangarooTwelve tree-hashing XOF)
└── CShake{128,256} : IExtendableOutput (bytepad prefix, domain sep 0x04)
ParallelHash (static, NIST SP 800-185)
per-block inner hash ─── Shake{128,256}
finalization ─── CShake{128,256} (N="ParallelHash", S=user)
IncrementalParallelHash (streaming wrapper, buffers input until Squeeze)
```
**CryptoHives 开源倡议**是由 **The Keepers of the CryptoHives** 开发和维护的一组面向 .NET 的现代化、高保障性库。
每个包都注重安全性、互操作性和清晰度——让您既能轻松构建适用于高性能转换管道和密码学工作负载的安全系统，又不会牺牲开发体验。
每个库都针对特定的用例：
- **Threading** — 高性能异步同步原语，使用基于 ValueTask 的等待器和基于 ObjectPool 的资源管理，针对零/低内存分配和高吞吐量场景进行了优化
- **Memory** — 利用 ArrayPool 和现代 .NET 内存 API 的池化缓冲区管理工具，最大程度地减轻使用 ReadOnlySpan 或 IBufferWriter 的转换管道和密码学工作负载的 GC 压力
- **Cryptography** — 所有 .NET 密码学算法的独立于操作系统的实现，可作为即插即用的替代方案
## 📚 文档
- 📖 **[完整文档](https://cryptohives.github.io/Foundation/)** - 详尽的指南、API 参考和示例
- 🚀 [入门指南](https://cryptohives.github.io/Foundation/getting-started.html)
- 📦 [包文档](https://cryptohives.github.io/Foundation/packages/index.html)
- 📚 [API 参考](https://cryptohives.github.io/Foundation/api/index.html)
## 🧬 功能与设计原则
### 🧱 正交设计
- 所有开发均使用免费的开源工具完成，例如 .NET SDK、Visual Studio Community Edition、Visual Studio Code、GitHub、Azure DevOps 等。
- 每个包的设计都遵循正交与可组合原则，可与其他 CryptoHives 包配合使用，以避免深层的交叉依赖。
- 对其他包的依赖保持在最低限度，且仅应包含被广泛采用、维护良好的库，例如 Microsoft.Extensions。
- 尽可能避免对操作系统和硬件的依赖，以确保在所有平台和 runtime 上行为的一致性（尤其是对于安全性实现）。
- 我们无意取代或掩盖现有的 .NET 类库；相反，CryptoHives 包旨在补充和拓展现有功能。
### ⚡ 高性能原语
- 所有 CryptoHives 包均专为高性能且无运行时内存分配而设计，以优化高性能转换管道和密码学工作负载。
- 算法可能会使用托管 SIMD 指令，并带有标量回退机制。
- 包的性能和内存使用情况均已通过基准测试与参考实现进行了对比。
### 🔐 安全开发策略
- 基于标准的密码学 – 实现均基于官方公开规范和标准（NIST、RFC、ISO）编写。
- 所有算法均已根据规范文档中的官方测试向量进行验证。
- 审查过程包括对照参考实现进行算法验证。
- 威胁建模驱动设计 – 所有公开 API 和网络接口均假设输入是恶意的。
- 默认安全与校验 – 最小攻击面、显式配置、严格的输入检查以及资源边界限制。
- 依赖与供应链安全 – 最小化且经过审查的依赖；可重现的签名（计划中）发布。
- 自动化验证 – Fuzzing（计划中）、静态分析以及安全的错误处理，以防止误用和信息泄露。
- 开发过程可能会使用 AI 辅助工具；不保证代码的纯净来源（clean-room provenance）。
## 🐝 可用的 CryptoHives
### 🛠️ 缓冲池 (Memory)
面向转换管道和高频 I/O 的池化缓冲区管理：
- `ArrayPoolMemoryStream` — 基于 `ArrayPool` 的 `MemoryStream` 直接替代品，支持 `ReadOnlySequence` 移交
- `ReadOnlySequenceMemoryStream` — 将 `ReadOnlySequence` 作为 `MemoryStream` 读取，无需拷贝
- `ArrayPoolBufferWriter` — 基于池化数组的 `IBufferWriter`，适用于如 `Utf8JsonWriter` 等场景
- 用于零拷贝移交池化缓冲区的所有权原语
### 🚀 并发工具
基于 `ObjectPool` 和 `ValueTask` 构建的异步兼容同步原语。
旨在消除热路径上的 `Task` / `TaskCompletionSource` 内存分配。
- `AsyncLock` — 互斥锁
- `AsyncSemaphore` — 计数信号量
- `AsyncAutoResetEvent` / `AsyncManualResetEvent`
- `AsyncReaderWriterLock`
- `AsyncBarrier` / `AsyncCountdownEvent`
所有原语均支持 `CancellationToken` 和 `ConfigureAwait(false)`，且无需额外的内存分配。
NuGet 包包含一个 C# 分析器，用于避免常见的 ValueTask 使用错误。（也可作为独立包提供）
⏱️ [异步原语基准测试](https://cryptohives.github.io/Foundation/packages/threading/benchmarks.html) — 包含高竞争和无竞争场景，对比了池化 `ValueTask` 与现有的基于 `Task` 的替代方案。
### 🔐 托管代码密码学
完全托管的密码学哈希算法、MAC 和加密算法实现，基于 NIST/RFC/ISO 规范编写，并已通过官方测试向量验证。
不依赖操作系统的加密实现——在任何平台上都能获得确定性的结果。在支持的硬件上会自动启用基于 AES-NI、PCLMULQDQ、VPCLMULQDQ、SSE2、SSSE3 和 AVX2 指令的硬件加速，在某些情况下甚至超越操作系统的实现。
**算法：**
| 家族 | 算法 |
|--------|-----------|
| SHA-2 | SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256 |
| SHA-3 | SHA3-224, SHA3-256, SHA3-384, SHA3-512 |
| Keccak | Keccak-256, Keccak-384, Keccak-512 (兼容 Ethereum) |
| SHAKE / cSHAKE | SHAKE128, SHAKE256, cSHAKE128, cSHAKE256 |
| ParallelHash (SP 800-185) | ParallelHash128, ParallelHash256 |
| TurboSHAKE / KT | TurboSHAKE128, TurboSHAKE256, KT128, KT256 |
| BLAKE | BLAKE2b, BLAKE2s (SIMD 加速), BLAKE3 |
| Ascon | Ascon-Hash256, Ascon-XOF128 (NIST SP 800-232 轻量级) |
| MAC | HMAC-SHA-256/384/512, HMAC-SHA3-256, AES-CMAC, AES-GMAC, Poly1305, KMAC128, KMAC256, BLAKE2 keyed, BLAKE3 keyed |
| Cipher (AEAD) | AES-GCM (128/192/256), AES-CCM (128/192/256), ChaCha20-Poly1305, XChaCha20-Poly1305, Ascon-AEAD128 |
| Cipher (Block) | AES-128, AES-192, AES-256 (ECB/CBC/CTR), ChaCha20 |
| Cipher (Regional) | SM4, ARIA (128/192/256), Camellia (128/192/256), Kuznyechik, Kalyna (128/256), SEED |
| Regional | SM3, Streebog, Kupyna, LSH, Whirlpool, RIPEMD-160 |
| Legacy | SHA-1, MD5 (仅用于向后兼容) |
所有 XOF 算法均实现了 `IExtendableOutput`，可通过 `Absorb` / `Squeeze` / `Reset` 流式传输可变长度输出。
**⏱️ 密码学基准测试**
使用 BenchmarkDotNet 对各种 payload 进行测量，对比托管实现、参考实现与操作系统实现。
- [哈希算法](https://cryptohives.github.io/Foundation/packages/security/cryptography/benchmarks-hash.html)
- [加密算法](https://cryptohives.github.io/Foundation/packages/security/cryptography/benchmarks-cipher.html)
### 📦 NuGet 包
| 包 | 描述 | NuGet | 文档 |
|----------|--------------|--------|---------------|
| `Memory` | 池化缓冲区与流 | [](https://www.nuget.org/packages/CryptoHives.Foundation.Memory) | [文档](https://cryptohives.github.io/Foundation/packages/memory/index.html) |
| `Threading` | 池化异步同步机制 | [](https://www.nuget.org/packages/CryptoHives.Foundation.Threading) | [文档](https://cryptohives.github.io/Foundation/packages/threading/index.html) |
| `Security.Cryptography` | 哈希、MAC 与加密算法 | [](https://www.nuget.org/packages/CryptoHives.Foundation.Security.Cryptography) | [文档](https://cryptohives.github.io/Foundation/packages/security/cryptography/index.html) |
所有包均在 `CryptoHives.Foundation` 前缀和命名空间下发布——详情请参见 NuGet 上的 [CryptoHives](https://www.nuget.org/packages?q=CryptoHives)。
### 🩺 CryptoHives 健康状态
[](https://dev.azure.com/cryptohives/Foundation/_build/latest?definitionId=6&branchName=main)
[](https://github.com/CryptoHives/Foundation/actions/workflows/buildandtest.yml)
[](https://codecov.io/github/CryptoHives/Foundation)
[](https://app.fossa.com/projects/git%2Bgithub.com%2FCryptoHives%2FFoundation?ref=badge_shield)
## 🧩 安装
通过 NuGet CLI 安装：
```
dotnet add package CryptoHives.Foundation.Threading
```
或使用 Visual Studio 的 Package Manager：
```
Install-Package CryptoHives.Foundation.Threading
```
## 🧠 使用示例
```
using CryptoHives.Foundation.Security.Cryptography.Hash;
// Allocation-free hash
using var blake3 = Blake3.Create();
Span hash = stackalloc byte[32];
blake3.TryComputeHash(data, hash, out _);
// XOF streaming (variable-length output)
using var shake = Shake256.Create(64);
shake.Absorb(data1);
shake.Absorb(data2);
Span output = stackalloc byte[128];
shake.Squeeze(output);
```
```
using CryptoHives.Foundation.Threading.Async.Pooled;
// Allocation-free async lock, even with cancellation token
private readonly AsyncLock _lock = new();
public async Task DoWorkAsync(CancellationToken ct)
{
using await _lock.LockAsync(ct).ConfigureAwait(false);
// critical section
}
```
## 🔐 安全策略
安全性是我们的首要任务。
如果您发现漏洞，**请不要公开提交 Issue。**
相反，请遵循 [CryptoHives 开源倡议安全页面](https://github.com/CryptoHives/.github/blob/main/SECURITY.md) 上的指南。
## 🔏 NuGet 包程序集代码签名
目前，我们 NuGet 包中的程序集未进行代码签名。一旦有足够的需求和资金支持，Keepers 计划为所有发布的包实现代码签名。
## 📝 严肃声明
本项目基于 MIT 许可证发布，因为开放协作至关重要。
然而，Keepers 非常清楚，基于 MIT 许可证的代码经常在不署名的情况下被复制、重新打包或商业化。
如果您使用了本代码，请负责任地使用：
- 明确提及对 **CryptoHives 开源倡议** 或 **The Keepers of the CryptoHives** 的致谢，并指明原始来源。
- 欢迎回馈改进并报告问题。
开源的繁荣依赖于尊重，而不仅仅是宽松的许可证。
## ⚖️ 许可证
CryptoHives 开源倡议的每个组件均使用与 SPDX 兼容的 MIT 许可证授权。
默认情况下，各包使用以下许可证标签：
```
// SPDX-FileCopyrightText: The Keepers of the CryptoHives
// SPDX-License-Identifier: MIT
```
某些继承的组件可能会根据其来源和特定要求，使用替代的 MIT 许可证头，我们将保留这些头部信息。
## 🐝 关于 The Keepers of the CryptoHives
**CryptoHives 开源倡议**项目由 **The Keepers of the CryptoHives** 维护——
这是一个由致力于推进 .NET 中开放、可验证且高性能密码学的开发者组成的集体。
## 🧩 贡献
欢迎贡献代码、报告 Issue 和提交 Pull Request！
在提交代码之前，请参阅[贡献指南](https://github.com/CryptoHives/.github/blob/main/CONTRIBUTING.md)。
© 2026 The Keepers of the CryptoHives
标签：多人体追踪, 密码学, 开发库, 性能优化, 手动系统调用, 检测绕过, 系统编程