siriuslee69/Tyr-Crypto

# Tyr-Crypto 此工作区中同级仓库的实验性 Nim 加密工具包。 ## 警告 本仓库**不保证已达到生产就绪状态**。 - 它包含自定义加密结构和纯 Nim 实现，在获得更深入的审查和外部验证之前，应将其视为实验性的。 - 本仓库明确是 **vibecoded** 的实验性加密代码。请预期存在粗糙的边缘、API 变更以及仍需深入审查的地方。 - 提供**不附带任何种类的担保或保证**。 - 如果您需要加固的生产级加密，请优先选择经过充分审查的上游库和经过审计的协议设计。 ## 本仓库负责的内容 - 可选加密后端周围的可复用 Nim 封装器 - 工作区使用的纯 Nim 辅助原语 - 基于 password/PIN 的密钥派生和封装辅助工具 - 分块文件加密和哈希辅助工具 - 后端元数据和算法注册辅助工具 - 可选本地依赖项的构建辅助工具 ## 本仓库不负责的内容 - 应用程序的协议定义 - 证书生命周期或信任策略 - 网络传输/会话编排 - 用户/账户存储 - 本仓库本地封装器之外的密钥管理基础设施 ## 主要状态类型 - `EncryptionState` - 位于 `src/tyr_crypto/wrapper/crypto.nim` 的封装器级对称加密状态 - `CipherText` - 封装器密文及认证材料 - `Key` - 位于 `src/tyr_crypto/wrapper/pin_key.nim` 的 password/PIN 派生封装状态 - `DerivedEncryptionKeys` - 派生的对称状态及 KDF 元数据 - `ChunkyOptions` 和 `ChunkyManifest` - 分块文件处理配置和输出清单 - `SignatureKeypair` - 用于经典、PQ 和混合签名模式的封装器级签名密钥对 ## 主要编排器 - `encrypt` / `decrypt` - 对称消息加密的高级封装器入口点 - `deriveSymmetricKeysFromBytesWithSalt` / `deriveSymmetricKeysFromString` - password 到封装器状态的派生 - `deriveMasterKey`, `wrapMasterKeyWithPin`, `unwrapMasterKeyWithPin` - password/PIN 密钥生命周期 - `encryptFileChunks`, `decryptFileChunks`, `hashFileChunks` - 大文件分块处理 - `createHybridKexOffer`, `respondHybridKexOffer`, `finalizeHybridKex` - 混合 PQ/经典 KEX 辅助工具 - `createKyberX25519KexOffer`, `createMcElieceX25519KexOffer` - 具有枚举选择 PQ 变体的双重混合 KEX 辅助工具 - `signatureKeypair`, `signMessage`, `verifyMessage` - Ed25519、PQ 签名和混合签名的统一签名 API ## 循环入口点 - `updateBlake3` / `finalBlake3` - 流式哈希更新 - `runEncryptTasks` / `runDecryptTasks` - 分块工作线程循环 - `encryptChunkTask`, `decryptChunkTask`, `hashChunkTask` - 每分块文件处理循环 ## 布局 - `src/tyr_crypto/common.nim` - 共享错误类型和辅助模板 - `src/tyr_crypto/random.nim` - 操作系统随机性及可选的额外熵混合 - `src/tyr_crypto/registry.nim` - 支持的算法和提供者的元数据 - `src/tyr_crypto/wrapper/` - 高级加密、PIN/KDF、签名和混合 KEX API - `src/tyr_crypto/custom_crypto/` - 纯 Nim 和面向 SIMD 的加密辅助工具 - `src/tyr_crypto/chunkyCrypto/` - 分块文件加密和哈希 - `src/tyr_crypto/bindings/` - 可选的本地绑定 - `tools/` - 本地依赖项构建辅助工具 - `tests/` - 向量、回归和封装器测试 - `iron/` - 仓库协调元数据 ## 快速开始 ### 基础构建和测试 ``` nimble test nim check src/tyr_crypto/registry.nim ``` ### 启用可选后端 ``` nimble build -d:hasLibsodium -d:hasLibOqs -d:hasOpenSSL3 -d:hasNimcrypto -d:hasBlake3 ``` 如果后端在编译时被排除或运行时缺失，封装器将引发 `LibraryUnavailableError` 而不是静默失败。 ### 本地构建器任务 ``` nimble build_libsodium nimble build_liboqs nimble build_openssl ``` 这些任务需要相关的子模块和可工作的本地构建工具链。在 Windows 上，这通常意味着 MSYS2 风格的环境以及标准的 C/C++ 构建工具。 ### 完整的本地后端测试运行 ``` nimble build_libsodium nimble build_liboqs nimble build_openssl nimble test_all ``` `nimble test_all` 是本地后端套件的路径，预期在启用 `libsodium`、`liboqs` 和 OpenSSL 的情况下运行。 如果您使用的是子模块本地构建而不是系统安装的库，可能需要使用环境变量（如 `LIBSODIUM_SOURCE`、`LIBSODIUM_LIB_DIRS`、`LIBOQS_SOURCE`、`LIBOQS_LIB_DIRS`、`OPENSSL_SOURCE` 和 `OPENSSL_LIB_DIRS`）将加载器指向它们。 ## 示例 ### 1. 对称封装器 API ``` import tyr_crypto/wrapper/crypto let state = EncryptionState( algoType: chacha20, keys: @[Key(key: newSeqWith(32, 0x11'u8), keyType: isSym)], nonce: newSeqWith(24, 0x22'u8) ) let msg = @[byte 1, 2, 3, 4] let cipher = encrypt(msg, state) let plain = decrypt(cipher, state) doAssert plain == msg ``` ### 2. 密码派生状态 ``` import tyr_crypto/wrapper/pin_key import tyr_crypto/wrapper/crypto when defined(hasLibsodium): let derived = deriveSymmetricKeysFromString(xchacha20Gimli, "correct horse", @[], 0'u16) let cipher = encrypt(@[byte 7, 8, 9], derived.state) doAssert decrypt(cipher, derived.state) == @[byte 7, 8, 9] ``` ### 3. 分块文件加密 ``` import tyr_crypto/chunkyCrypto import tyr_crypto/wrapper/pin_key import tyr_crypto/wrapper/crypto when defined(hasLibsodium): let derived = deriveSymmetricKeysFromString(xchacha20AesGimli, "file-passphrase", @[], 64'u16) var opt = initChunkyOptions() opt.chunkBytes = 64 * 1024 opt.bufferBytes = 4096 let manifest = encryptFileChunks("input.bin", "chunks", derived.state, opt) decryptFileChunks(manifest, "chunks", "output.bin", derived.state, opt) ``` ### 4. 枚举驱动的混合 KEX ``` import tyr_crypto when defined(hasLibsodium) and defined(hasLibOqs): let duo = createMcElieceX25519KexOffer(mvClassicMcEliece6960119) let (duoResp, duoSharedB) = respondMcElieceX25519KexOffer(duo.offer) let duoSharedA = finalizeMcElieceX25519Kex(duo, duoResp) doAssert duoSharedA == duoSharedB let triple = createHybridKexOffer(kvKyber1024, mvClassicMcEliece8192128) let (tripleResp, tripleSharedB) = respondHybridKexOffer(triple.offer) let tripleSharedA = finalizeHybridKex(triple, tripleResp) doAssert tripleSharedA == tripleSharedB ``` ### 5. 具有调用者提供熵的混合 KEX ``` import tyr_crypto when defined(hasLibsodium) and defined(hasLibOqs): let userEntropy = "mouse-jitter|keypress-latency|request=42" let state = createKyberX25519KexOfferWithEntropy( kvKyber768, userEntropy ) let (resp, sharedB) = respondKyberX25519KexOfferWithEntropy( state.offer, "server-timing|request=42" ) let sharedA = finalizeKyberX25519Kex(state, resp) doAssert sharedA == sharedB ``` 这些辅助工具通过作用域内的混合 RNG 路径为 liboqs KEM 操作提供输入，该路径混合了： - 普通的支持 OS 的安全随机源 - 调用者提供的字节，例如用户交互或本地事件计时 - 用作额外多样化的本地进程/计时上下文 ### 6. 混合签名 ``` import tyr_crypto when defined(hasLibsodium) and defined(hasLibOqs): let kp = signatureKeypair(saEd25519Falcon512Hybrid) let msg = @[byte 1, 2, 3, 4] let sig = signMessage(saEd25519Falcon512Hybrid, msg, kp.secretKey) doAssert verifyMessage(saEd25519Falcon512Hybrid, msg, sig, kp.publicKey) ``` ## 自定义封装器组合 - `chacha20` - 封装器流模式，目前实现为 `xchacha20Xor(...)` 加上带密钥的 BLAKE3 标签 - `xchacha20Gimli` - `XChaCha20 -> Gimli stream -> Gimli tag` - `aesGimli` - `AES-CTR -> Gimli stream -> Gimli tag` - `xchacha20AesGimli` - `XChaCha20 -> AES-CTR -> Gimli stream -> Gimli tag` - `xchacha20AesGimliPoly1305` - `XChaCha20 -> AES-CTR -> Gimli stream -> (Gimli tag || Poly1305 tag)` - `aes256` - 通过 Nimcrypto 后端的 AES-256-GCM 这些封装器名称是特定于仓库的结构，不是标准化的 AEAD 名称。请将密文和标签布局视为特定于实现且对版本敏感的。 ## 混合封装器表面 - `createKyberX25519KexOffer*` / `respondKyberX25519KexOffer*` - `Kyber + X25519` - `createMcElieceX25519KexOffer*` / `respondMcElieceX25519KexOffer*` - `Classic McEliece + X25519` - `createHybridKexOffer*` / `respondHybridKexOffer*` - `Kyber + Classic McEliece + X25519` - `*WithEntropy` KEX 辅助工具 - 通过作用域 liboqs RNG 回调混合 OS 随机性、调用者提供的熵字节和本地计时/进程上下文 - `saEd25519Falcon512Hybrid` / `saEd25519Falcon1024Hybrid` - 生成并验证 Ed25519 和 Falcon 两部分 ## 当前加密表面 - 对称封装器模式 - `chacha20` - `xchacha20Gimli` - `aesGimli` - `xchacha20AesGimli` - `xchacha20AesGimliPoly1305` - `aes256` - 混合 KEX 模式 - `Kyber + X25519`，使用 `kvKyber768` 或 `kvKyber1024` - `Classic McEliece + X25519`，使用 `mvClassicMcEliece6688128`、`mvClassicMcEliece6960119` 或 `mvClassicMcEliece8192128` - `Kyber + Classic McEliece + X25519`，使用枚举选择的 Kyber 和 McEliece 变体 - 混合签名模式 - `saEd25519Falcon512Hybrid` - `saEd25519Falcon1024Hybrid` - 混合签名需要经典和 PQ 两部分都通过验证 ## 本地和磁盘边界 - 本地运行时边界 - `libsodium`、`liboqs` 和 OpenSSL 是可选的动态/本地依赖项 - 磁盘边界 - `blake3HashFile` - `encryptFileChunks` - `decryptFileChunks` - `hashFileChunks` - 仓库本地构建边界 - `tools/build_libsodium.nim` - `tools/build_liboqs.nim` - `tools/build_openssl.nim` ## 安全说明 - 封装器 `chacha20` 模式现在使用带密钥的 BLAKE3 标签，而不是直接哈希 `key || nonce || ciphertext`。 - AES-256-GCM 封装器现在使用认证解密，而不是解密后比较。 - PIN 封装现在默认对新密钥使用基于 Argon2id 的派生。 - 早于存储 PIN KDF 参数的旧封装密钥仍保留旧版解封回退路径。 - 混合 liboqs KEM 调用不再仅依赖 liboqs 默认 RNG 路径；封装器现在安装作用域混合熵回调，并公开用于调用者提供材料的 `*WithEntropy` 辅助工具。 - liboqs RNG 钩子是进程全局的，因此那些混合熵 KEM 部分在密钥生成/封装运行时使用锁进行序列化。 - `otp.nim` 公开自定义确定性 OTP 风格辅助工具。它**不是** RFC HOTP/TOTP 互操作性层，不应假设与验证器应用程序兼容。 - `custom_crypto/` 中的几个模块首先是实现实验，其次是兼容性表面。 ## 许可 - 本仓库中的原始 Tyr-Crypto 代码根据 `Unlicense` 发布。 - 完整文本请参见 `LICENSE`，依赖摘要请参见 `THIRD_PARTY_LICENSES.md`。 - 检出的子模块保留其上游许可，**不会**被 Tyr-Crypto 重新许可。 - 当前观察到的顶层子模块许可： - `libsodium`: ISC - `liboqs`: MIT，源码树内有针对每个文件夹的第三方例外 - `OpenSSL`: Apache-2.0 - 检出的 `submodules/openssl/` 树还包含具有额外许可的嵌套辅助和测试仓库，包括 GPL/LGPL 组件，如 `tlsfuzzer` 和 `tlslite-ng`。 - 本摘要仅用于仓库维护和署名。这不构成法律建议。 ## 常用命令 ``` nimble test nimble test_all nimble test_all_threads_on nimble test_all_threads_off nimble test_gimli nimble test_blake3_simd nimble perf_sigma ``` ## 问题排查手册 - `LibraryUnavailableError` - 您在编译时未使用匹配的 `-d:has*` 标志，或者运行时本地库不可用。 - `nimble test` 通过但本地后端仍未验证 - 默认套件也测试回退路径。当您需要特定后端验证时，请使用相关标志和已安装的库进行编译。 - 分块哈希目前是串行的，即使加密/解密使用工作线程 - 目前这是有意为之。之前的 ORC/ARC 线程哈希路径在 seq 负载上遇到了所有权损坏，因此正确性优先于并行性。 - 构建器任务在 Windows 上失败 - 检查子模块是否存在，以及是否安装了上游项目预期的本地工具链。 - OTP 输出与外部 TOTP 应用不匹配 - 预期行为。`otp` 模块是自定义的，不是直接可替换的 RFC 4226/6238 实现。 ## 开发说明 在更改行为之前，请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。安全报告指南位于 [SECURITY.md](./SECURITY.md)。依赖项的许可说明位于 [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md)。 ## 约定摘要 - 保持函数简短并组合辅助工具，而不是深度嵌套。 - 在 proc 的顶部附近声明 `var`/`let` 块。 - 保留 `src/tyr_crypto/` 下基于级别的模块布局。 - 优先选择显式运行时错误，而不是静默回退行为。 - 每当加密行为、文件格式或后端接线发生变化时，添加或更新测试。 - 当公共行为或仓库结构发生变化时更新文档。

标签：CVE, DNS 反向解析, KDF, Nim 语言, PBKDF, StruQ, 分块加密, 加密包装器, 加密工具包, 后量子密码, 哈希算法, 安全测试工具, 实验性代码, 密码学, 密钥派生, 对称加密, 开发库, 手动系统调用, 数字签名, 文件加密, 本地密钥管理, 混合签名, 纯 Nim 实现, 自动化审计, 防御绕过, 零依赖