📚 课程目录第4章 OpenSSL后量子分支编译与安装

4. OpenSSL后量子分支编译与安装

要在本机真正跑通后量子 TLS 握手，第一步不是写客户端代码，而是准备一套“认识后量子算法”的 OpenSSL。标准发行版自带的 OpenSSL 3.x 虽然提供了 Provider 机制，但默认并不包含 ML-KEM（Kyber）、ML-DSA（Dilithium）、Falcon、SPHINCS+ 等算法的完整实现，因此我们需要获取 OpenSSL 的后量子分支——最典型的是 Open Quantum Safe 项目维护的 oqs-provider 配合 OpenSSL 3.x，或者直接使用 OQS 社区维护的 OpenSSL 分支源码。本节以“源码获取 → 编译选项配置 → 安装路径隔离 → 版本与算法能力验证”为主线，讲清楚每一步的实际操作与判断依据。

一、源码获取：选对分支，避免污染系统

推荐采用“OpenSSL 3.x 主干 + oqs-provider 插件”的组合方式，因为它与上游 OpenSSL 的兼容性最好，后续升级也最平滑。获取源码时，先确认本机已有的 OpenSSL 版本，再决定是否需要自行编译 OpenSSL 本体。若系统 OpenSSL 已是 3.0 以上，可以只编译 oqs-provider；若系统版本过旧（如 1.1.1），则必须连同 OpenSSL 一起编译。

# 查看系统 OpenSSL 版本
openssl version -a

# 获取 OpenSSL 3.x 源码（示例使用 3.2.x 分支）
git clone --branch openssl-3.2 https://github.com/openssl/openssl.git openssl-pq
cd openssl-pq

# 获取 oqs-provider 源码
git clone https://github.com/open-quantum-safe/oqs-provider.git

oqs-provider 依赖 liboqs 提供底层算法实现，因此还需要先编译安装 liboqs。三者关系是：liboqs 提供算法原语，oqs-provider 把算法封装成 OpenSSL Provider，OpenSSL 通过 Provider 加载这些算法。理解这条依赖链，才能明白为什么编译顺序不能颠倒。

二、编译选项配置：隔离路径是关键

编译时最容易踩的坑是“装到了系统默认路径”，导致后续实验环境与系统 OpenSSL 混用，出现版本冲突或算法加载失败。正确做法是为本次实验指定独立的安装前缀，例如 /opt/pq-tls，并让 liboqs、OpenSSL、oqs-provider 全部安装到该前缀下。

# 1. 编译安装 liboqs
cd liboqs
mkdir build && cd build
cmake -GNinja -DCMAKE_INSTALL_PREFIX=/opt/pq-tls ..
ninja && sudo ninja install

# 2. 编译安装 OpenSSL（指定独立前缀）
cd openssl-pq
./Configure --prefix=/opt/pq-tls --openssldir=/opt/pq-tls/ssl \
            shared no-tests
make -j$(nproc) && sudo make install_sw

# 3. 编译安装 oqs-provider
cd oqs-provider
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/pq-tls \
      -DOPENSSL_ROOT_DIR=/opt/pq-tls
cmake --build build && sudo cmake --install build

几个选项值得说明：--prefix 决定安装根目录，--openssldir 决定配置文件与证书目录，shared 生成动态库以便 Provider 动态加载，no-tests 可缩短编译时间（实验环境可接受）。oqs-provider 编译时必须通过 OPENSSL_ROOT_DIR 指向刚编译的 OpenSSL，否则会链接到系统库，导致运行时找不到符号。

三、安装路径隔离与环境变量

安装完成后，系统里同时存在两套 OpenSSL：系统自带的 /usr/bin/openssl 和实验用的 /opt/pq-tls/bin/openssl。为避免混淆，建议在实验终端中显式设置环境变量，而不是修改全局 PATH：

export PATH=/opt/pq-tls/bin:$PATH
export LD_LIBRARY_PATH=/opt/pq-tls/lib:$LD_LIBRARY_PATH
export OPENSSL_CONF=/opt/pq-tls/ssl/openssl.cnf

其中 OPENSSL_CONF 最为关键。oqs-provider 需要在配置文件中被显式激活，否则即使库文件存在，OpenSSL 也不会加载它。可以在 openssl.cnf 的 [provider_sect] 中加入 oqsprovider = oqsprovider_sect，并在 [oqsprovider_sect] 中写 activate = 1。这样每次启动 OpenSSL 都会自动加载后量子算法。

四、版本与算法能力验证

验证分三层：先确认版本，再确认 Provider 已加载，最后确认算法可用。三层都通过，才说明环境真正就绪。

# 第一层：版本与安装路径
/opt/pq-tls/bin/openssl version -a

# 第二层：Provider 列表
/opt/pq-tls/bin/openssl list -providers

# 第三层：算法能力
/opt/pq-tls/bin/openssl list -kem-algorithms | grep -i mlkem
/opt/pq-tls/bin/openssl list -signature-algorithms | grep -i mldsa

预期观察到的现象是：version -a 输出的 OPENSSLDIR 应为 /opt/pq-tls/ssl；list -providers 中应出现 oqsprovider 且状态为 active；算法列表中应能看到 ML-KEM-768、ML-DSA-65 等条目。若 Provider 未出现，优先检查 OPENSSL_CONF 是否生效、ossl-modules 目录下是否存在 oqsprovider.so。若算法列表为空但 Provider 已激活，则多半是 liboqs 版本与 oqs-provider 不匹配，需要回退到兼容的版本组合。

建议在实验记录中固定记录三个版本号：liboqs、OpenSSL、oqs-provider。后量子生态迭代很快，不同版本组合的算法命名和默认参数可能不同，固定版本是实验可复现的前提。

完成上述步骤后，你就拥有了一套与系统隔离、可随时启停的后量子 OpenSSL 环境。后续的证书生成、TLS 握手测试都将基于 /opt/pq-tls 这套工具链展开，而不会影响系统其他依赖 OpenSSL 的服务。