Open Quantum Safe liboqs 项目配置指南

前言

Open Quantum Safe (OQS) 的 liboqs 是一个开源的密码学库，专注于后量子密码学算法的实现。本文将深入解析 liboqs 的配置选项，帮助开发者根据自身需求定制化构建这个重要的密码学工具。

基础构建配置

构建类型选择

liboqs 支持两种主要的构建类型：

1. Debug 模式 (-DCMAKE_BUILD_TYPE=Debug)

   • 关闭所有编译器优化
   • 生成调试信息
   • 仅对 GCC 或 Clang 编译器有效
   • 可配合代码覆盖率测试 (-DUSE_COVERAGE=ON)
   • 使用 Clang 时可启用各种检测器 (-DUSE_SANITIZER=...)

2. Release 模式 (-DCMAKE_BUILD_TYPE=Release) [默认]

   • 启用 O3 优化级别
   • 设置减小二进制大小的编译器标志

库类型选择

• -DBUILD_SHARED_LIBS=ON：构建动态链接库
• -DBUILD_SHARED_LIBS=OFF：构建静态链接库 [默认]

算法选择配置

算法集预设

-DOQS_ALGS_ENABLED 提供几种预设算法集合：

• STD：仅包含 NIST 标准化的算法
• NIST_R4：包含 NIST PQC 竞赛第四轮评估的所有算法
• NIST_SIG_ONRAMP：包含 NIST PQC "onramp" 标准化评估的额外签名方案
• All [默认]：包含 liboqs 集成的所有算法

单个算法控制

通过以下模式可精细控制每个算法：

• -DOQS_ENABLE_KEM_ALG=ON/OFF
• -DOQS_ENABLE_SIG_ALG=ON/OFF
• -DOQS_ENABLE_SIG_STFL_ALG=ON/OFF

其中 ALG 需替换为具体算法名称，如：

-DOQS_ENABLE_KEM_BIKE=ON
-DOQS_ENABLE_SIG_DILITHIUM=OFF

最小化构建

-DOQS_MINIMAL_BUILD 允许指定分号分隔的算法列表，构建仅包含这些算法的最小化库：

-DOQS_MINIMAL_BUILD="KEM_kyber_768;SIG_dilithium_3"

性能优化配置

目标架构优化

-DOQS_DIST_BUILD 控制构建目标：

• ON [默认]：构建适用于目标架构所有变体的分发版本
• OFF：为当前机器的特定微架构优化

CPU 特性指令

当 OQS_DIST_BUILD=OFF 时，可手动控制特定 CPU 指令集的使用：

x86-64 平台支持：

-DOQS_USE_ADX_INSTRUCTIONS=ON
-DOQS_USE_AVX2_INSTRUCTIONS=OFF
...

ARM64v8 平台支持：

-DOQS_USE_ARM_AES_INSTRUCTIONS=ON
-DOQS_USE_ARM_NEON_INSTRUCTIONS=OFF
...

优化目标指定

-DOQS_OPT_TARGET 可设置为：

• auto [默认]：自动检测并使用本地 CPU 特性
• generic：使用通用优化
• 特定架构标识：如 -DOQS_OPT_TARGET=skylake

外部依赖配置

OpenSSL 集成

-DOQS_USE_OPENSSL=ON [默认] 允许使用 OpenSSL 的加密原语实现，可进一步控制：

• -DOQS_USE_AES_OPENSSL=ON [x86-64 平台有条件默认]
• -DOQS_USE_SHA2_OPENSSL=ON [默认]
• -DOQS_USE_SHA3_OPENSSL=OFF [默认]

动态加载选项：

-DOQS_DLOPEN_OPENSSL=ON

cuPQC 集成

-DOQS_USE_CUPQC=ON 启用 NVIDIA cuPQC 库支持（当前仅支持 ML-KEM）

特殊功能配置

状态式哈希签名

控制 XMSS 和 LMS 签名方案：

-DOQS_ENABLE_SIG_STFL_XMSS=ON
-DOQS_ENABLE_SIG_STFL_LMS=ON

安全警告：密钥生成功能需谨慎启用：

-DOQS_HAZARDOUS_EXPERIMENTAL_ENABLE_SIG_STFL_KEY_SIG_GEN=ON

ARM 性能监控

-DOQS_SPEED_USE_ARM_PMU=ON 启用 ARMv8 性能监控单元，需内核支持

安全检测

1. 恒定时间测试：

-DOQS_ENABLE_TEST_CONSTANT_TIME=ON

2. 严格警告：

-DOQS_STRICT_WARNINGS=ON

3. 检测器选项（Clang Debug 模式下）：

-DUSE_SANITIZER=Address
-DUSE_SANITIZER=Undefined
...

特殊构建场景

嵌入式构建

-DOQS_EMBEDDED_BUILD=ON 适用于裸机嵌入式环境，需自定义随机数生成回调

Libjade 集成

-DOQS_LIBJADE_BUILD=ON 使用形式验证的算法实现，当前支持：

• Kyber512
• Kyber768

模糊测试

-DOQS_BUILD_FUZZ_TESTS=ON 启用模糊测试套件（需 Clang 编译器）

结语

liboqs 提供了丰富的配置选项，使开发者能够根据具体应用场景（如嵌入式系统、高性能服务器等）和安全性需求定制构建。理解这些选项对于优化性能、减小代码体积和确保安全性至关重要。建议开发者在发布前充分测试所选配置，特别是涉及安全性关键选项时。