Windows 下构建 liboqs-java，实现PQC算法的调用

本文目标

本文将完整演示如何在 Windows 环境下构建并使用liboqs-java，主要包括以下内容：

  1. 在 Windows 上编译liboqs
  2. 构建可用的liboqs-java.jar
  3. 运行官方示例验证构建结果
  4. 在 Spring Boot 项目中引入该 JAR
  5. 通过 Java 代码调用 ML-KEM 等后量子密码算法

二、环境与工具

本文使用的环境如下：

Windows 10 / Windows 11 MinGW-w64 CMake JDK Maven Git

建议使用较新的 JDK 版本，例如 JDK 17 或 JDK 21。本文示例以JDK 21为例。

三、先理解 liboqs 与 liboqs-java 的关系

在正式构建之前，需要先理解几个组件之间的关系。

Spring Boot / Java 业务代码 | | 调用 Java API v liboqs-java.jar | | JNI 调用 v oqs-jni.dll | | 链接 v liboqs.a / liboqs | | 实际执行算法 v ML-KEM、ML-DSA 等 PQC 算法

可以简单理解为：

组件作用
liboqsC 语言实现的后量子密码学算法库
liboqs-java对liboqs的 Java 封装
oqs-jni.dllJava 与 native 层之间的 JNI 桥接库
liboqs-java.jarJava / Spring Boot 项目最终要引入的 JAR 包

因此，正确的构建顺序是：

先构建 liboqs 再构建 liboqs-java 最后在 Java / Spring Boot 项目中引用生成的 JAR

注意：
如果跳过liboqs的构建，直接构建liboqs-java，通常会遇到找不到oqs.h、找不到liboqs.a等问题。

四、推荐项目目录结构

由于需要从 GitHub 获取liboqs-java和liboqs两个项目源码，建议将目录结构整理为如下形式：

D:\workspace\liboqs-java-main ├── pom.xml ├── README.md ├── examples │ ├── KEMExample.java │ ├── SigExample.java │ └── RandExample.java ├── src ├── liboqs │ ├── CMakeLists.txt │ ├── src │ └── build │ ├── include │ │ └── oqs │ │ └── oqs.h │ └── lib │ └── liboqs.a └── target └── liboqs-java.jar

如下图所示：

其中最关键的是以下几个文件：

liboqs\build\include\oqs\oqs.h liboqs\build\lib\liboqs.a target\liboqs-java.jar

只要这些文件都成功生成，说明主构建流程基本已经走通。

五、准备构建工具

需要提前安装以下工具：

工具作用
MinGW-w64提供gcc、g++，用于编译 C 代码和 JNI 代码
CMake生成并驱动liboqs构建
JDK编译 Java 代码，并提供 JNI 头文件
Maven构建liboqs-java并打包 JAR
Git拉取源码，非必需，也可以手动下载 ZIP

建议将所有工具都安装到纯英文路径下，不要放在包含中文或空格的目录中。例如：

D:\c_tools\mingw64 D:\java\jdk-21 D:\javaTools\apache-maven-3.9.x D:\workspace

建议：
native 构建工具对路径比较敏感，中文路径、空格路径有时会导致一些较难排查的问题。为了减少环境问题，建议统一使用英文路径。

六、安装 MinGW-w64

可以使用 MinGW-w64 官方推荐的发行版。下载入口如下：

https://www.mingw-w64.org/

进入官网后，找到Downloads，再找到MinGW-W64-builds。

点击后会跳转到 GitHub：

选择需要的版本下载即可：

下载完成后解压，后续需要将mingw64\bin添加到环境变量中。

安装完成后，可以在终端中执行：

gcc -v

测试是否安装成功：

能看到 GCC 的版本信息，就说明 MinGW-w64 已经可以正常使用。

同时确认以下文件存在：

D:\c_tools\mingw64\bin\gcc.exe D:\c_tools\mingw64\bin\g++.exe D:\c_tools\mingw64\bin\mingw32-make.exe

后续 CMake 会通过这些工具来编译liboqs和 JNI 代码。

七、安装 CMake

可以使用winget安装：

winget install Kitware.CMake

也可以从 CMake 官网下载 Windows x64 Installer：

https://cmake.org/download/

下载后直接运行安装程序即可。

安装时建议勾选：

Add CMake to the system PATH for current user

如下图所示：

安装完成后，重新打开终端，执行：

cmake --version

如果能够正常输出版本信息，说明 CMake 已经安装成功。

八、安装 JDK

JDK 可以选择 Eclipse Temurin 或 Oracle JDK。

下载地址：

https://adoptium.net/ https://www.oracle.com/java/technologies/downloads/

JDK 的安装教程较多，本文不再展开。本文示例使用JDK 21，假设安装路径为：

D:\java\jdk-21

需要确认以下文件存在：

D:\java\jdk-21\bin\java.exe D:\java\jdk-21\bin\javac.exe D:\java\jdk-21\include\jni.h

其中jni.h非常重要。

注意：
构建liboqs-java时会编译 JNI 代码。如果安装的是 JRE 而不是 JDK，就会缺少jni.h，从而导致构建失败。

九、安装 Maven

从 Maven 官网下载 binary zip 包：

https://maven.apache.org/download.cgi

下载后解压到任意英文路径，例如：

D:\javaTools\apache-maven-3.9.x