cabelo/libzupt

# libzupt - 后量子混合加密库 [](LICENSE) []() [](#build) [](https://github.com/cabelo/libzupt/actions/workflows/cmake-multi-platform.yml) **libzupt** 是一个库，提供使用后量子混合加密 **ML-KEM-768 + X25519** 对多种语言中的文件和内存中的二进制数据进行加密和解密的功能。 **libzupt** 是一个 SDK，旨在简化使用基于混合后量子加密 **ML-KEM-768 + X25519** 的现代方法对文件和内存二进制数据进行加密和解密的实现。该库最初使用 **C++ 和 Python** 开发，旨在高效、便携，并易于集成到需要高级安全性的应用程序中。还计划扩展对 **Java 和 Node.js** 的支持，以进一步增加其在不同开发生态系统中的采用。 libzupt 的主要目标是使当前的应用程序能够抵御来自量子计算的新兴威胁，即使是在经典计算机上运行也是如此。通过将传统加密技术与抗量子机制相结合，该库提供了一层额外的安全性，以预见经典算法可能被破解的未来场景。这允许开发人员构建更具弹性的系统，确保长期的数据机密性和完整性。 名称 **zupt** 是对 **Cristian Cezar Moisés** 创建的原始项目的致敬，以感谢他对该解决方案的概念和技术基础做出的根本性贡献。这种灵感加强了该库对创新、安全性以及推动现代应用密码学发展的思想演进的承诺。 ## 概述 该库提供： - **后量子混合加密**：结合了 ML-KEM-768 (FIPS 203) 和 X25519 (RFC 7748) - **故障安全**：只要至少有一种算法（ML-KEM-768 或 X25519）保持安全，就是安全的 - **现代 C++ API**：带有异常处理的面向对象接口 - **文件和内存支持**：用于文件和内存缓冲区的加密 - **安全内存清理**：敏感数据在使用后会被擦除 ### 要求 - CMake 3.10 或更高版本 - C++17 编译器 (GCC 7+, Clang 5+, MSVC 2017+) - 系统库：`libm` ### 构建 ``` # Clone libzupt git clone https://github.com/cabelo/libzupt.git # Build cd libzupt mkdir build && cd build cmake .. make -j$(nproc) # Install (optional) sudo make install ``` ### 通过 vcpkg 安装 (Windows/Linux) ``` vcpkg install libzupt:x64-linux # ou vcpkg install libzupt:x64-windows ``` ## 基本用法 ### 生成密钥对 ``` #include "zupt.hpp" zupt::KeyGenerator keygen; zupt::KeyPair keypair = keygen.generateKeyPair(); // Salvar chaves em arquivos keygen.saveKeyPair(keypair, "private.key"); keygen.exportPublicKey("private.key", "public.key"); ``` ### 加密内存中的数据 ``` #include "zupt.hpp" // Carregar chave pública zupt::KeyGenerator keygen; std::vector publicKey = keygen.loadPublicKey("public.key"); // Criptografar zupt::Encryptor encryptor(publicKey); const std::string plaintext = "Mensagem secreta"; auto [ciphertext, encHeader] = encryptor.encryptMemory( reinterpret_cast(plaintext.data()), plaintext.size() ); ``` ### 解密内存中的数据 ``` #include "zupt.hpp" // Carregar chave privada zupt::KeyGenerator keygen; zupt::KeyPair keypair = keygen.loadKeyPair("private.key"); // Descriptografar zupt::Decryptor decryptor(keypair.secret_key); std::vector decrypted = decryptor.decryptMemory(ciphertext, encHeader); std::string result(decrypted.begin(), decrypted.end()); ``` ### 加密文件 ``` #include "zupt.hpp" zupt::KeyGenerator keygen; std::vector publicKey = keygen.loadPublicKey("public.key"); zupt::Encryptor encryptor(publicKey); auto [ciphertext, encHeader] = encryptor.encryptFile("input.txt"); // Salvar ciphertext e header std::ofstream("output.zupt", std::ios::binary).write( reinterpret_cast(ciphertext.data()), ciphertext.size()); std::ofstream("output.zupt.header", std::ios::binary).write( reinterpret_cast(encHeader.data()), encHeader.size()); ``` ## API ### 主要类 #### `zupt::KeyGenerator` 生成并管理混合密钥对。 ``` class KeyGenerator { public: KeyPair generateKeyPair(); // Gera novo par de chaves void saveKeyPair(const KeyPair&, const string&); // Salva chaves em arquivo KeyPair loadKeyPair(const string&); // Carrega chaves de arquivo void exportPublicKey(const string&, const string&); // Exporta chave pública vector loadPublicKey(const string&); // Carrega chave pública }; ``` #### `zupt::Encryptor` 使用公钥执行加密。 ``` class Encryptor { public: explicit Encryptor(const vector& publicKey); pair, vector> encryptMemory(const uint8_t*, size_t); pair, vector> encryptFile(const string&); }; ``` #### `zupt::Decryptor` 使用私钥执行解密。 ``` class Decryptor { public: explicit Decryptor(const vector& privateKey); vector decryptMemory(const uint8_t*, size_t, const vector&); vector decryptFile(const string&, const vector&); SecureBuffer decryptMemorySecure(const SecureBuffer&, const vector&); }; ``` #### `zupt::SecureBuffer` 在销毁时自动擦除其内存的缓冲区。 ``` class SecureBuffer { public: explicit SecureBuffer(size_t size); SecureBuffer(const uint8_t* data, size_t size); void zeroize() noexcept; // Limpa buffer manualmente uint8_t* data() noexcept; size_t size() const noexcept; }; ``` ### 辅助函数 ``` std::vector randomBytes(size_t size); // Generates safe random bytes. std::vector sha256(const uint8_t* data, size_t size); // SHA-256 std::vector sha3_512(const uint8_t* data, size_t size); // SHA3-512 void secureWipe(void* ptr, size_t size); // Safely clears memory. const char* getVersion(); // Library version const char* getLibraryName(); // Library name ``` ## 示例 请参阅 `examples/` 中的完整示例： ``` # Generate keys ./zupt_example_file genkey private.key public.key # Encrypt file ./zupt_example_file encrypt public.key input.txt output.zupt # Decrypt file ./zupt_example_file decrypt private.key output.zupt output.txt output.zupt.header # Run basic example ./zupt_example_basic ``` ## 密钥格式规范 密钥以 `.zupt-key` 格式存储： ``` [4B] "ZKEY" - Magic number [1B] Version (0x01) [1B] Flags (bit 0 = 1 if there is a private key) [2B] Reserved [1184B] ML-KEM-768 Public Key [32B] X25519 Public Key [2400B] ML-KEM-768 Secret Key (private key) [32B] X25519 Secret Key (private key) [8B] XXH64 Checksum ``` 总大小： - 公钥：1224 字节 - 私钥：2504 字节 ### 组合算法 1. **ML-KEM-768** (FIPS 203)：后量子密钥封装算法 2. **X25519** (RFC 7748)： (RFC 7748)：椭圆曲线 25519 Diffie-Hellman ### 密钥派生过程 ``` 1. ML-KEM-768 Encaps: generates ciphertext (1088 bytes) and shared secret (32 bytes) 2. X25519 ECDH: generates shared secret (32 bytes) with recipient's public key 3. Hybrid IKM = ML-KEM-SS XOR X25519-SS (32 bytes) 4. Archive Key = SHA3-512(hybrid_ikm || ml_ct || eph_pk || "ZUPT-HYBRID-v1") - enc_key = archive_key[0:32] - mac_key = archive_key[32:64] 5. AES-256-CTR + HMAC-SHA256 for data encryption ``` ### 数据大小 | 组件 | 大小 | |------------|---------| | ML-KEM Public Key | 1184 字节 | | ML-KEM Secret Key | 2400 字节 | | X25519 Key | 32 字节 | | ML-KEM Ciphertext | 1088 字节 | | Encryption Header | 1137 字节 | ## 安全性 ### 安全模型 该库遵循 **Signal PQXDH** 和 **iMessage PQ3** 的安全模型： ### 实现的保护措施 - **安全内存擦除**：密钥和敏感数据在使用后被清零 - **隐式封装**：ML-KEM-768 实现隐式拒绝以防止时序攻击 - **恒定比较**：HMAC 验证使用恒定比较以防止时序攻击 - **加密随机性**：使用系统 CSPRNG (getrandom, /dev/urandom, RtlGenRandom) ### 安全警告 - **请勿使用密码模式 (`-p`)** 进行后量子保护 - 仅将 `--pq` 与密钥一起使用 - 私钥必须存储在安全的位置 - 请勿使用不同的密钥重复使用加密头 ### 许可证 MIT License - 详见 [LICENSE](LICENSE) 文件。 ### 作者 Alessandro de Oliveira Faria (A.K.A.CABELO) - MultiCortex 创始人 - Intel Innovator - openSUSE 大使和成员 - OWSP SP Chapter Leader - Soberania 项目高级 AI 研究员 - Foton 研究所成员 - FIA 教授 - i2Ai 和 ABRIA 成员 联系方式: cabelo@opensuse.org ### 参考资料 - [ML-KEM-768 - FIPS 203](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf) - [X25519 - RFC 7748](https://tools.ietf.org/html/rfc7748) - [Signal PQXDH](https://signal.org/docs/specifications/pqx/) - [Libsodium](https://github.com/jedisct1/libsodium) [](https://www.paypal.com/donate/?hosted_button_id=7X8GVQG2J78LW)

标签：Bash脚本, C++, CMake, meg, MIT协议, ML-KEM-768, Python, X25519, 云配置检测, 信息安全, 内存数据加密, 加密库, 后量子密码学, 客户端加密, 密码学, 对称加密, 手动系统调用, 抗量子计算, 数据擦除, 文件加密, 无后门, 混合加密, 算法库, 自动化审计, 蓝队防御, 跨语言, 逆向工具, 非对称加密