moss-piglet/metamorphic_crypto

# MetamorphicCrypto [](https://hex.pm/packages/metamorphic_crypto) [](https://hexdocs.pm/metamorphic_crypto) 用于 Elixir 的 NaCl 兼容加密 —— 服务端。 支持对称和公钥加密、Argon2id 密钥派生， **ML-KEM-768/1024 + X25519 混合后量子加密**，以及人类可读的 恢复密钥 —— 由带有预编译二进制文件的 Rust NIF 提供支持。 ``` key = MetamorphicCrypto.generate_key() {:ok, ciphertext} = MetamorphicCrypto.encrypt("hello", key) {:ok, "hello"} = MetamorphicCrypto.decrypt(ciphertext, key) ``` ## 安装 将 `metamorphic_crypto` 添加到你的 `mix.exs` 中： ``` def deps do [ {:metamorphic_crypto, "~> 0.2"} ] end ``` 然后： ``` mix deps.get ``` 就是这样。预编译的 NIF 二进制文件会自动为你的平台下载。 无需 Rust 工具链，无需 C 编译器，无需系统包。 ### 为什么不使用 enacl？ `enacl` 通过 C NIF 封装了 libsodium。它需要系统全局安装 libsodium 头文件、C 编译器工具链，并且经常在 OTP 升级或 macOS 更新时出错。CI 流水线需要额外的设置。Docker 构建需要 `libsodium-dev`。 MetamorphicCrypto 生成**相同的密文**（相同的 NaCl 线缆格式），但 以预编译二进制文件的形式提供 —— `mix deps.get` 即可工作。无需系统依赖， 没有编译烦恼，无需解决跨平台的构建失败问题。 ## 快速入门 ### 对称加密 (SecretBox) XSalsa20-Poly1305 认证加密。与 libsodium 格式相同。 ``` key = MetamorphicCrypto.generate_key() {:ok, ciphertext} = MetamorphicCrypto.encrypt("sensitive data", key) {:ok, "sensitive data"} = MetamorphicCrypto.decrypt(ciphertext, key) ``` ### 公钥加密 (Sealed Box) 对收件人的公钥进行匿名加密。只有他们才能解密。 ``` {public_key, private_key} = MetamorphicCrypto.generate_keypair() {:ok, sealed} = MetamorphicCrypto.seal("for your eyes only", public_key) {:ok, "for your eyes only"} = MetamorphicCrypto.unseal(sealed, public_key, private_key) ``` ### 后量子混合加密 提供两种安全级别。Cat-3 (ML-KEM-768, ~AES-192) 是默认选项。 Cat-5 (ML-KEM-1024, ~AES-256) 适用于最高安全级别的用例。 ``` # Cat-3 (默认) — ML-KEM-768 + X25519 {pq_pk, pq_sk} = MetamorphicCrypto.Hybrid.generate_keypair() {:ok, ciphertext} = MetamorphicCrypto.Hybrid.seal("quantum-safe", pq_pk) {:ok, "quantum-safe"} = MetamorphicCrypto.Hybrid.open(ciphertext, pq_sk) # Cat-5 (opt-in) — ML-KEM-1024 + X25519，最高安全性 {pq_pk_1024, pq_sk_1024} = MetamorphicCrypto.Hybrid.generate_keypair_1024() {:ok, ciphertext} = MetamorphicCrypto.Hybrid.seal_1024("top secret", pq_pk_1024) {:ok, "top secret"} = MetamorphicCrypto.Hybrid.open(ciphertext, pq_sk_1024) ``` `open/2` 会根据版本标签字节自动检测密文格式： | 版本 | 格式 | 安全性 | |---------|--------|----------| | (无) | Legacy X25519 sealed box | 经典 | | `0x02` | ML-KEM-768 + X25519 (Cat-3) | ~AES-192, NIST Category 3 | | `0x03` | ML-KEM-1024 + X25519 (Cat-5) | ~AES-256, NIST Category 5 | 这意味着你可以逐步升级安全级别 —— 现有的 密文无论使用何种级别加密，都能始终正确解密。 ### 统一 Seal/Unseal (自动检测) 在可用时自动使用 PQ，否则回退到经典方式。在解密时检测格式 —— 新旧密文可以无缝共存。 ``` {pk, sk} = MetamorphicCrypto.Keys.generate_keypair() {pq_pk, pq_sk} = MetamorphicCrypto.Hybrid.generate_keypair() # 使用混合 PQ 加密 {:ok, ct} = MetamorphicCrypto.Seal.seal_for_user("secret", pk, pq_public_key: pq_pk) # 解密（自动检测格式） {:ok, "secret"} = MetamorphicCrypto.Seal.unseal_from_user(ct, pk, sk, pq_secret_key: pq_sk) ``` ### 密钥派生 (Argon2id) 从密码派生会话密钥。使用 libsodium 的交互式参数 （64 MiB，2 次迭代）。 ``` salt = MetamorphicCrypto.Keys.generate_salt() {:ok, session_key} = MetamorphicCrypto.KDF.derive_session_key("user password", salt) ``` ### 恢复密钥 人类可读的备份密钥（类似于 Matrix 或 Signal 的恢复码）。 ``` {:ok, recovery_key, secret} = MetamorphicCrypto.Recovery.generate() # recovery_key => "ABCDE-FGHJK-LMNPQ-RSTUV-..." # 备份私钥 {:ok, backup} = MetamorphicCrypto.Recovery.encrypt_private_key(private_key, secret) # 稍后恢复 {:ok, restored_secret} = MetamorphicCrypto.Recovery.key_to_secret(recovery_key) {:ok, private_key} = MetamorphicCrypto.Recovery.decrypt_private_key(backup, restored_secret) ``` ### 密钥生成 (Mix 任务) ``` mix metamorphic_crypto.gen.key ``` ## 架构模式 ### 何时使用此库 MetamorphicCrypto 在 BEAM VM 中以**服务端**方式运行。在以下情况使用： - **你正在替换 `enacl`** —— 直接替换为预编译二进制文件 （无需 libsodium C 编译），相同的线缆格式，外加后量子支持 - **你的服务器合法持有加密密钥** —— 服务端 NaCl 加密 比纯 Elixir 更快，且与 libsodium 客户端线缆兼容 - **你需要在服务端进行后量子加密** —— ML-KEM-768 + X25519，Hex 上的首创 - **你正在逐步过渡到 ZK** —— 现有的服务端操作 保留在 MetamorphicCrypto，而新功能转移到客户端的 WASM - **测试和固定数据** —— 在 ExUnit 测试中生成 NaCl 兼容的密文 ### 此库不做什么 此库**不**提供客户端的零知识加密。对于 服务器永远看不到明文的完全 ZK，加密必须在 浏览器中进行 —— 这需要通过 LiveView JS hook 加载 相同 Rust 核心的 WASM 构建版本。 在完全的 ZK 架构中（如 [Metamorphic](https://metamorphic.app)）， 服务器是一个简单的存储层。客户端负责所有的加密操作。 服务器为此不需要这个库 —— 它只是存储和检索不透明的二进制数据。 ### 完整零知识架构 如果你想构建一个 ZK 应用，请参阅 [零知识指南](docs/zero-knowledge-guide.md)。简短版本如下： - **客户端 (WASM)：** 执行所有的加密/解密操作 - **服务器：** 存储不透明的密文，编排密钥分发事件， 使用 Cloak 包装二进制数据以实现纵深防御 - **此库的角色：** 可选 —— 在迁移期间很有用，用于生成 测试固定数据，或者如果你有需要 NaCl 兼容加密的 特定服务端操作 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Client (browser) │ │ │ │ password ──► Argon2id KDF ──► session_key │ │ │ │ │ decrypt private_key │ │ │ │ │ plaintext ──► metamorphic-crypto (WASM) ──► ciphertext ──────┐ │ │ │ │ └───────────────────────────────────────────────────────────────┼─┘ │ ───────┼────── │ ┌───────────────────────────────────────────────────────────────┼─┐ │ Server (Phoenix/LiveView) ▼ │ │ │ │ Receives opaque ciphertext (cannot decrypt) │ │ Cloak wraps it in AES-256-GCM before writing to DB │ │ (defense-in-depth against DB-level compromise) │ │ │ │ MetamorphicCrypto (optional): test fixtures, migration helper │ └─────────────────────────────────────────────────────────────────┘ ``` ### 模式：替换 enacl 如果你目前使用 `enacl` 进行服务端 NaCl 加密，MetamorphicCrypto 是一个直接替代方案，提供更好的 DX： ``` # 之前（enacl — 需要编译 libsodium） :enacl.crypto_secretbox(plaintext, nonce, key) # 之后（MetamorphicCrypto — 预编译，无需 C toolchain） MetamorphicCrypto.SecretBox.encrypt(plaintext, key) ``` 密文格式相同。无需进行数据迁移。 ### 模式：向零知识过渡 如果你的应用目前正在进行服务端加密（使用 enacl 或 Cloak）： 1. 用 MetamorphicCrypto **替换 enacl**（相同的线缆格式，无需迁移） 2. 将 WASM 客户端**添加**到你的 Phoenix 应用（LiveView JS hooks） 3. 将操作**逐个转移到客户端** —— 新功能使用客户端加密， 旧功能暂时保留在服务端 4. **最终**，服务器只存储不透明的二进制数据，你可能根本不需要 这个库来进行用户数据加密 MetamorphicCrypto 使第 1 步变得简单，并确保在过渡期间服务器和 客户端之间的线缆兼容性（两者都从相同的 Rust 核心生成相同的密文）。 ## 与 Cloak 一起使用 MetamorphicCrypto 和 Cloak 解决不同的问题： | | Cloak | MetamorphicCrypto | |--|-------|-------------------| | **目的** | 服务端静态加密 | NaCl 兼容的加密原语 | | **谁持有密钥** | 服务器 (环境变量) | 取决于你的架构 | | **加密算法** | AES-256-GCM | XSalsa20-Poly1305, ML-KEM-768/1024 | | **密钥轮换** | 内置 | — | | **Ecto 类型** | Binary, Map, Integer, HMAC | — | | **用途** | 静态 PII，盲索引 | NaCl 操作，enacl 替代，PQ | 对于加密的 Ecto 字段和盲索引，请使用 Cloak。对于 NaCl 兼容的 加密操作和后量子加密，请使用 MetamorphicCrypto。 ## 模块 | 模块 | 用途 | |--------|---------| | `MetamorphicCrypto` | 顶级便捷 API | | `MetamorphicCrypto.SecretBox` | XSalsa20-Poly1305 对称加密 | | `MetamorphicCrypto.BoxSeal` | X25519 匿名密封盒 | | `MetamorphicCrypto.Hybrid` | ML-KEM-768/1024 + X25519 后量子混合加密 | | `MetamorphicCrypto.Seal` | 带有自动检测的统一 seal/unseal | | `MetamorphicCrypto.KDF` | Argon2id 密钥派生 | | `MetamorphicCrypto.Keys` | 密钥生成和私钥管理 | | `MetamorphicCrypto.Recovery` | 人类可读的恢复密钥 | ## 线缆格式兼容性 此库生成的所有密文与以下库在**字节级别完全兼容**： - [libsodium](https://doc.libsodium.org/) / NaCl (对称 + sealed box) - [TweetNaCl.js](https://tweetnacl.js.org/) (对称 + sealed box) - [enacl](https://github.com/aeternity/enacl) (Erlang libsodium 绑定) - [`metamorphic-crypto`](https://crates.io/crates/metamorphic-crypto) WASM 模块 (浏览器客户端) 这意味着你可以： - 在现有项目中**替换 `enacl`** 而无需进行数据迁移 - 在服务器上**解密**在浏览器中加密的内容（反之亦然） - **逐步采用**后量子加密而不破坏现有数据 ## 部署 **无需特殊的部署步骤。** 预编译二进制文件覆盖： | 平台 | 架构 | |----------|--------------| | Linux (glibc) | x86_64, aarch64 | | macOS | x86_64, aarch64 (Apple Silicon) | | Windows | x86_64 | 如果你部署到上面未列出的平台，请设置 `METAMORPHIC_CRYPTO_BUILD=true` 并确保你的构建环境中包含 Rust： ``` # 在你的 Dockerfile 中（仅当你的平台未预编译时） RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y ENV PATH="/root/.cargo/bin:${PATH}" ENV METAMORPHIC_CRYPTO_BUILD=true ``` 对于标准部署（Fly.io、Gigalixir、Heroku、Linux/amd64 或 arm64 上的 Docker）， 预编译二进制文件即可直接使用 —— 无需任何配置。 ## 从源码构建 如果你想自己编译 NIF（例如，用于本库的开发）： ``` export METAMORPHIC_CRYPTO_BUILD=true mix deps.get mix compile ``` 需要 Rust 1.85+（`rustup update`）。 ## 贡献 欢迎贡献！如有重大更改，请先提交 issue。 ``` git clone https://github.com/moss-piglet/metamorphic_crypto.git cd metamorphic_crypto export METAMORPHIC_CRYPTO_BUILD=true mix deps.get mix test ``` ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。 由 [Moss Piglet](https://github.com/moss-piglet) 构建。由 [@f0rest8](https://github.com/f0rest8) 维护。

标签：Argon2id, Elixir, Hex包, libsodium, meg, ML-KEM, NaCl, ProjectDiscovery, Rust NIF, Sealed Box, X25519, XSalsa20-Poly1305, 信息安全, 公钥加密, 加密库, 可视化界面, 后量子密码学, 密码学, 密钥派生, 对称加密, 手动系统调用, 抗量子加密, 数据保护, 数据加密, 本体建模, 混合加密, 自动化审计, 蓝队防御, 零依赖, 预编译二进制文件