openHiTLS 开源密码套件全解：五大组件架构、特性全景与 CMake 构建实战

• 密码学
• 网络安全

openHiTLS 是面向全场景的开源密码学开发套件，提供标准密码算法、(D)TLS/(D)TLCP 安全通信协议与 PKI 证书能力，其核心设计是通过 CMake 特性开关实现模块与算法的按需裁剪。本文基于仓库 README-zh.md 展开，结合 CMakeLists.txt、cmake/hitls_options.cmake 等构建源码，系统讲解 openHiTLS 的组件划分、特性清单、构建安装流程与交叉编译方法，帮助开发者在十分钟内完成环境搭建并掌握特性级裁剪能力。

一、项目定位与架构总览

openHiTLS 的目标是提供高效、敏捷的全场景开源密码学开发套件，采用轻量级、可剪裁的软件技术架构，让密码技术应用更简单，同时探索后量子等先进算法创新实践。据 README-zh.md 描述，其架构高度模块化，RAM/ROM 尺寸取决于所选特性，已支持 5 个组件，算法特性可按需配置，并已通过 ISO 19790 认证，支持 ARM、x86 架构 CPU 上的算法性能优化。

从仓库源码结构看，当前代码版本标识为openHiTLS 0.4.0（见 include/bsl/bsl_version.h 中的OPENHITLS_VERSION_S默认值）。仓库顶层目录与五大组件一一对应，另有命令行工具与测试工程：

组件间的典型搭配关系是：Crypto 既可独立与 BSL 组合提供纯算法能力，也可作为 TLS 的密码底座；TLS 还可对接第三方密码组件或 PKI 库，这种松耦合设计正是"RAM/ROM 尺寸取决于所选特性"的底层原因。

二、功能特性全景

README-zh.md 将特性分为"功能特性"与"DFX 特性"两类，完整清单如下。

2.1 协议支持

• TLS 系：TLS1.3、DTLS1.3、TLS1.3-Hybrid-Key-Exchange（混合密钥交换）、TLS-Provider、TLS-Multi-KeyShare、TLS-Custom-Extension、TLCP、DTLCP、TLS1.2、DTLS1.2；
• 认证协议：Privacy Pass token、HOTP、TOTP、SPAKE2+。

在构建系统中，这些协议能力对应独立的特性开关。以 cmake/hitls_options.cmake 为例，HITLS_TLS_PROTO_TLS13、HITLS_TLS_PROTO_DTLS13、HITLS_TLS_PROTO_TLCP11、HITLS_TLS_PROTO_DTLCP11等选项可单独裁剪，TLS 1.3 的扩展能力（如HITLS_TLS_FEATURE_KEM混合 KEM、HITLS_TLS_FEATURE_PHA握手后认证、HITLS_TLS_FEATURE_SESSION_TICKET会话票证）也都是独立选项，说明协议特性支持细粒度开关。

2.2 密码算法

源码侧可在 crypto/ 下逐目录印证：crypto/mlkem/、crypto/mldsa/、crypto/slh_dsa/（hbs 目录）、crypto/xmss（hbs 目录）、crypto/mceliece/、crypto/frodokem/对应后量子算法，crypto/sm2/、crypto/sm9/、crypto/ecc/、crypto/rsa/、crypto/dh/对应国密与传统非对称算法。后量子证书与 TLS 混合密钥交换能力由HITLS_TLS_FEATURE_KEM、HITLS_CRYPTO_HYBRIDKEM、HITLS_CRYPTO_COMPOSITE等选项支撑。

2.3 PKI 能力

• 后量子能力：XMSS、ML-DSA、ML-KEM、SLH-DSA 证书能力，ML-DSA CMS SignedData 能力；
• 传统证书能力：X.509 解析验证、CRL 解析验证、CSR 请求生成、证书链生成、部分/全部证书链验证；
• 封装格式：PKCS7、PKCS8、PKCS12。

实现位于 pki/：pki/x509_cert/（证书）、pki/x509_crl/（CRL）、pki/x509_csr/（CSR）、pki/x509_verify/（链验证）、pki/cms/（CMS）、pki/pkcs12/（PKCS#12）。配套的端到端示例可参考 testcode/demo/example_pki_certificate_generate.c、testcode/demo/example_pki_chain_verify.c、testcode/demo/example_pki_pq_certificate_generate.c 等。

2.4 命令行工具

支持基础命令、随机数、加解密、密钥和参数管理、证书等。命令行工具编译产物为hitls，其入口在 apps/src/hitls.c，apps/下按命令拆分源文件（如app_rand.c、app_enc.c、app_x509.c、app_client.c等），命令列表覆盖help/version/list、enc/mac/dgst/kdf、genpkey/pkeyutl、x509/crl/req/verify、s_client/s_server等，详见 docs/zh/4_使用指南/5_命令行指南.md。

注意：hitls命令行工具默认不参与编译，需在 CMake 配置时显式开启-DHITLS_BUILD_EXE=ON。

2.5 DFX（可设计、可维护、可测试）特性

• 弹性架构：特性高度模块化，支持按需裁剪特性；
• 性能优化：基于 ARMv8、ARMv7、x86_64 CPU 的算法性能优化（构建选项含HITLS_ASM_X8664、HITLS_ASM_ARMV8、HITLS_ASM_ARMV7等，且支持 AVX512 变体HITLS_ASM_X8664_AVX512）；
• 可维可测：支持基于日志和错误堆栈的功能维测，日志模块位于 bsl/log/，错误堆栈模块位于 bsl/err/。

三、快速开始：克隆与默认构建

按 README-zh.md「开发 → 快速开始」，最小构建路径如下：

git clone https://gitcode.com/openhitls/openhitls.git cd openhitls mkdir -p build && cd build cmake .. && make && make install

其中：

• cmake ..为默认构建，启用所有特性，同时生成静态库和共享库。从 cmake/hitls_options.cmake 可见HITLS_BUILD_PROFILE默认值为full，而 cmake/presets/full.cmake 会强制打开HITLS_BSL、HITLS_CRYPTO、HITLS_PKI、HITLS_TLS、HITLS_AUTH五个组件开关；
• 默认安装前缀为/usr/local：头文件安装至/usr/local/include/hitls/下按模块划分的子目录（对应 CMakeLists.txt 末尾的install(DIRECTORY ...)规则），库文件安装至/usr/local/lib；
• 非 root 用户执行make install需加sudo，或在配置时通过-DCMAKE_INSTALL_PREFIX=<目录>指定自定义前缀。

构建完成后，仓库中还提供了一整套算法级 demo（见 testcode/demo/，含 TLS1.2/1.3 基础握手、DTLS1.3 UDP、SM2 签名验签、SM3 摘要、ML-KEM 封装解封装等数十个示例），以及 benchmark 工程（testcode/benchmark/），可作为集成后的验证与压测素材。

四、CMake 构建选项详解

openHiTLS 使用纯 CMake 构建系统，通过-D参数控制所有构建选项。在 README-zh.md 给出的常用配置之上，结合 docs/zh/4_使用指南/1_构建及安装指导.md 的完整参数表，常用命令与参数如下。

4.1 常用配置命令

# 准备构建目录 cd openhitls && mkdir -p ./build && cd ./build # 默认构建（启用所有特性，同时生成静态库和共享库） cmake .. # 全量构建（使用预设） cmake .. -DHITLS_BUILD_PROFILE=full # 手动选择特性（不加载内置预设，只启用 SHA256） cmake .. -DHITLS_BUILD_PROFILE=none -DHITLS_CRYPTO_SHA256=ON # 启用汇编优化（自动检测平台类型：x86_64 / ARMv8 / ARMv7） cmake .. -DHITLS_ASM=ON # x86_64 汇编优化全量构建 cmake .. -DHITLS_BUILD_PROFILE=full -DHITLS_ASM_X8664=ON # 构建命令行工具 hitls cmake .. -DHITLS_BUILD_EXE=ON # 打包为单个库 cmake .. -DHITLS_BUNDLE_LIB=ON # 仅静态库 / 仅动态库 cmake .. -DHITLS_BUILD_SHARED=OFF cmake .. -DHITLS_BUILD_STATIC=OFF # 覆盖编译选项 / 链接选项 cmake .. -DHITLS_COMPILE_OPTIONS="-O0;-g" cmake .. -DHITLS_SHARED_LINK_FLAGS="-shared;-Wl,-z,now" # 修改构建类型 cmake .. -DCMAKE_BUILD_TYPE=Debug # 执行构建和安装 make -j && make install

4.2 核心参数说明

4.3 特性开关的层级与依赖推导

从 cmake/hitls_options.cmake 的选项组织方式可以看出，特性开关采用父-子层级：例如HITLS_CRYPTO_MD代表所有哈希算法，开启它会连带启用HITLS_CRYPTO_MD5、HITLS_CRYPTO_SHA256等子项；反向亦然——只开启子项时构建系统会自动补全父项。文件头注释明确说明："when a user enables HITLS_CRYPTO_MD5, HITLS_CRYPTO_MD is automatically enabled"。

这一机制由根 CMakeLists.txt 中的三段式流程实现：

# Derive all children for each enabled option hitls_feature_children_derive() # Derive TLS suite options based on cipher, key exchange and authentication method selections hitls_tls_suites_derive() # Derive all dependencies for each enabled option hitls_feature_dependencies_derive()

即：先由显式开启的选项向上推导父特性，再根据密码算法、密钥交换与认证方式的选择推导 TLS 套件（cipher suite）组合，最后向下推导依赖。随后hitls_generate_config_h_file生成构建目录下的config/hitls_build_config.h（模板见 cmake/config.h.in），hitls_collect_feature_macros收集全部特性宏并通过add_compile_definitions注入编译，hitls_config_check则打印未满足依赖的警告。这意味着开发者只关心业务语义开关（如HITLS_CRYPTO_MLKEM=ON），编译宏、父特性、TLS 套件组合都由构建系统自动推导，这也是"按需裁剪"能落地的关键。

4.4 构建预设（Profile）

仓库在 cmake/presets/ 下提供了两套预设文件：

1. full预设（cmake/presets/full.cmake）：一键打开全部五个组件（BSL/Crypto/PKI/TLS/Auth），即默认构建行为；
2. iso19790预设（cmake/presets/iso19790.cmake）：面向 ISO 19790 合规模式的最小集，只启用 EAL/Provider/CMVP-ISO19790 模块与合规算法组合（AES、Chacha20、SHA1/SHA2/SHA3/SM3、HMAC/CMAC/GMAC、HKDF/PBKDF2、DRBG CTR/HASH/HMAC、RSA/DSA/DH/ECDSA/ECDH/SM2/Ed25519/X25519、SLH-DSA/ML-KEM/ML-DSA 等），并通过-Wl,--version-script链接 cmake/presets/libhitls_cmvp.ld 版本脚本，约束导出符号——这与 README 中"已支持 5 个组件、通过 ISO 19790 认证"的描述相互印证。

4.5 交叉编译

交叉编译推荐使用仓库自带的工具链文件（cmake/toolchain/ 下提供 aarch64、arm32、riscv64、macOS 等常见平台模板）：

cd openHiTLS && mkdir -p ./build && cd ./build cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchain/aarch64-linux-gnu-gcc.cmake make -j

也可以不用工具链文件，直接在配置阶段指定交叉编译器（如 aarch64-linux-gnu-gcc）：

cmake .. \ -DCMAKE_SYSTEM_NAME=Linux \ -DCMAKE_SYSTEM_PROCESSOR=aarch64 \ -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \ -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \ -DCMAKE_ASM_COMPILER=aarch64-linux-gnu-gcc

工具链文件的实质是设置CMAKE_SYSTEM_NAME/CMAKE_SYSTEM_PROCESSOR并通过find_program定位前缀编译器，如 cmake/toolchain/aarch64-linux-gnu-gcc.cmake 所示。

依赖提示：DTLS 特性依赖 sctp，默认未启用，如需开启需提前在系统中预装 sctp 依赖。

此外，testcode/script/build_hitls.sh 提供了开发态的一键构建脚本，支持debug、asan、ctvalgrind、pure_c（纯 C 无汇编）、x86_64、armv8_le、riscv64等模式，适合开发调试场景快速验证。

4.6 集成到 C/C++ 工程

安装后头文件按模块分层安装于/usr/local/include/hitls/<模块>/，代码引用哪些模块就需要为哪些模块加-I，例如仅引用 crypto 与 bsl：

gcc application.c -o app \ -lhitls_crypto -lhitls_bsl \ -I /usr/local/include/hitls/crypto -I /usr/local/include/hitls/bsl \ -L /usr/local/lib

链接动态库的程序首次运行前需保证动态库可被加载：Linux 执行sudo ldconfig刷新缓存；macOS 设置export DYLD_LIBRARY_PATH=/usr/local/lib或编译时追加-Wl,-rpath,/usr/local/lib。否则会出现libhitls_crypto.so: cannot open shared object file报错。最小验证用例（SM3 摘要）与完整接口用法可参考 docs/zh/3_快速入门.md。

五、文档体系与深入路径

README-zh.md 的「文档」一节指向 docs/index/index.md，其中组织了完整的中文/英文文档索引：

六、贡献与许可

• 项目采用 Mulan PSL v2 许可证（见 LICENSE）；
• 有意贡献代码者需先在 CLA 签署平台完成 CLA 签署，再 fork 官方 Git 库并克隆自己的公共副本进行开发；
• 漏洞类问题（密码缺陷、内存安全、时序侧信道）应通过 SECURITY.md 所述渠道上报；
• 贡献流程与提交规范见 CONTRIBUTING-zh.md。

七、小结

openHiTLS 以"BSL 基础层 + Crypto 算法层 + TLS 协议层 + PKI 证书层 + Auth 认证层"的模块化组织，配合 CMake 特性开关的父子推导与依赖自动补全机制，实现了从"全量构建"到"仅保留某几个算法"的连续裁剪粒度。对于使用者，cmake .. && make && make install即可完成默认全量集成；对于裁剪场景，掌握HITLS_BUILD_PROFILE三值（full/iso19790/none）与HITLS_CRYPTO_*、HITLS_TLS_*、HITLS_BUNDLE_LIB等核心开关即可覆盖绝大多数工程需求。算法示例、测试用例与 benchmark 均随仓库提供（testcode/），可作为裁剪正确性与性能评估的验证手段。

• 密码学
• 网络安全