QuickLogic-Corp/qlcrypt

# qlcrypt QuickLogic 独立加密库和 CLI，用于保护处于静态的 FPGA 设备数据 IP。在版本化的 `.en` 容器格式中提供经认证的 AES-256-GCM 文件加密，以及一个加固的密钥数据库和 命令行工具。作为 git submodule 被 FOEDAG 和 VTR/VPR 使用。 ## 状态 Pre-1.0 版本。API 和 `.en` 格式对于 v2 规范是稳定的，但 在标记 v1.0.0 版本之前，公共 API 可能会进行非破坏性更新。 有关发布历史，请参阅 [CHANGELOG.md](CHANGELOG.md)，有关内部设计，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 功能 - **经过认证的 AES-256-GCM 加密**，每个文件使用随机 nonce （符合 NIST SP 800-38D 标准）。 - **版本化的 `.en` 容器** — 自描述的 27 字节 header （magic、版本、加密算法、nonce、明文长度）。 - **向后兼容的 v1 解密**，适用于旧版 FOEDAG 包。 - **解密缓存**（`Processor`） — 每个独立的文件在每个进程生命周期内最多解密一次；满足 VPR 要求的“每次运行只解密一次”的 不变性。 - **密钥指纹识别**（8 字节 SHA-256 前缀），用于针对每个客户的泄露进行 归因。 - **安全的内存清理** — 为密钥使用 `SecByteBlock`，为明文缓存使用 `SecureWipeBuffer`，在受支持的平台上可选 `mlock` / `madvise(MADV_DONTDUMP)` / `VirtualLock`。 - **CLI 工具**（`qlcrypt`），带有 git 风格的子命令： `keygen`、`encrypt`、`decrypt`、`inspect`、`verify`、`fingerprint`、`rotate`。 ## 构建说明 ### 前置条件 - CMake ≥ 3.15 - C++17 编译器：GCC ≥ 9、Clang ≥ 10、MSVC ≥ 2019 - [Crypto++](https://www.cryptopp.com/) ≥ 8.7.0（系统包或自带源码） - [cereal](https://github.com/USCiLab/cereal) 1.3.x（默认通过 FetchContent 获取源码） - [CLI11](https://github.com/CLIUtils/CLI11) 2.4.x（自带单头文件） - GoogleTest 1.14.x（通过 FetchContent 获取，仅用于构建测试） 在 Ubuntu / Debian 上： ``` sudo apt install cmake g++ libcrypto++-dev libcrypto++-utils pkg-config ``` 在 macOS 上： ``` brew install cmake cryptopp pkg-config ``` ### 快速构建 ``` git clone https://github.com/QuickLogic-Corp/qlcrypt.git cd qlcrypt cmake -B build -DCMAKE_BUILD_TYPE=Release cmake --build build -j$(nproc 2>/dev/null || sysctl -n hw.ncpu) ctest --test-dir build --output-on-failure ``` ### CMake 选项 | 选项 | 默认值 | 用途 | |---|---|---| | `QLCRYPT_BUILD_TESTS` | 独立运行 `ON`，通过 `add_subdirectory` 时 `OFF` | 构建单元和集成测试 | | `QLCRYPT_BUILD_TOOL` | 独立运行 `ON`，通过 `add_subdirectory` 时 `OFF` | 构建 `qlcrypt` CLI 可执行文件 | | `QLCRYPT_BUILD_BENCH` | `OFF` | 构建 Google Benchmark 套件 | | `QLCRYPT_BUILD_FUZZ` | `OFF` | 构建 libFuzzer harness（需要 Clang） | | `QLCRYPT_ENABLE_ASAN` | `OFF` | Address sanitizer | | `QLCRYPT_ENABLE_UBSAN` | `OFF` | UB sanitizer | | `QLCRYPT_ENABLE_MSAN` | `OFF` | Memory sanitizer（仅限 Clang） | | `QLCRYPT_ENABLE_COVERAGE` | `OFF` | lcov / gcov 插桩 | | `QLCRYPT_WARNINGS_AS_ERRORS` | `OFF`（CI 环境下：`ON`） | 将警告视为错误 | ## 用法 ### 作为 CMake submodule 使用 ``` add_subdirectory(third_party/qlcrypt) target_link_libraries(my_target PRIVATE qlcrypt::qlcrypt) ``` ### 作为系统安装的包使用 ``` find_package(qlcrypt 0.1 REQUIRED) target_link_libraries(my_target PRIVATE qlcrypt::qlcrypt) ``` ### 库 API ``` #include #include int main() { qlcrypt::KeyDB key_db; if (auto s = qlcrypt::KeyDB::load("device/_Supp.db", key_db); !qlcrypt::ok(s)) { std::cerr << "Load failed: " << qlcrypt::toString(s) << '\n'; return 1; } qlcrypt::Processor processor(std::move(key_db)); std::string_view yaml_view; if (auto s = processor.decryptFile("device/SB_MAPS.yml.en", yaml_view); !qlcrypt::ok(s)) { std::cerr << "Decrypt failed: " << qlcrypt::toString(s) << '\n'; return 1; } // yaml_view is valid for the lifetime of `processor`. // The same call again will hit the cache (no re-decrypt). } ``` ### CLI ``` # 创建 key database（带可选 customer tag） qlcrypt keygen --out device/_Supp.db --customer-id ACME-001 # 加密文件 qlcrypt encrypt --key-db device/_Supp.db \ --in device/SB_MAPS.yml --out device/SB_MAPS.yml.en # 就地加密目录（匹配 pattern） qlcrypt encrypt --key-db device/_Supp.db \ --in device/CSV --in-place --include '*.csv' # 解密至 stdout qlcrypt decrypt --key-db device/_Supp.db --in device/SB_MAPS.yml.en # 检查 header（无需 key） qlcrypt inspect device/SB_MAPS.yml.en --format json # 验证完整性（auth tag 检查，不写入 plaintext） qlcrypt verify --key-db device/_Supp.db --in device/SB_MAPS.yml.en # 打印 key fingerprint qlcrypt fingerprint device/_Supp.db # 在整个目录中 rotate keys qlcrypt rotate --old-key-db old/_Supp.db --new-key-db new/_Supp.db --dir device ``` 有关完整的参考说明，请参阅 `docs/CLI.md` 和 `man qlcrypt`。 ## 文档 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 内部设计 - [docs/FILE_FORMAT.md](docs/FILE_FORMAT.md) — `.en` v2 规范（权威标准） - [docs/API.md](docs/API.md) — 公共 API 参考 - [docs/CLI.md](docs/CLI.md) — CLI 参考 - [docs/SECURITY.md](docs/SECURITY.md) — 威胁模型和披露政策 - [docs/CONSUMER_GUIDE.md](docs/CONSUMER_GUIDE.md) — FOEDAG / VTR 集成指南 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。

标签：AES-256-GCM, Bash脚本, C++, FPGA, 密码学, 手动系统调用, 数据擦除, 文件加密