openHiTLS 源码工程实践指南：构建、测试、编码规范与常量时间安全准则

• 密码学
• 网络安全

openHiTLS 是遵循 Mulan PSL v2 协议的 C 语言密码库与 TLS 库，提供对称/非对称算法、哈希、KDF、TLS 1.2/1.3、X.509 PKI，以及 ML-KEM、ML-DSA、SLH-DSA、McEliece、FrodoKEM 等后量子算法。仓库根目录的 AGENTS.md 是面向修改 openHiTLS 源码的开发者（或 AI 编码代理）的工程规范文件，它定义了项目结构、完成标准（Definition of Done）、构建与 SDV 测试命令、错误处理、内存管理、命名与代码风格、常量时间准则以及 SDV 测试数据的编写方法。本文以该文档为骨架，结合仓库中的真实源码与脚本逐节展开：读完后你将能够独立完成一次「干净构建 → 精准测试 → 格式检查 → 密钥路径审计」的完整变更闭环。

一、项目结构速览

AGENTS.md 首先给出了一张目录职责表，它是理解 openHiTLS 分层架构的最快入口：

几个要点值得注意：

• 公开头文件与实现代码严格分离：调用方只依赖include/下的接口，例如 TLS 公共入口在 hitls.h，密码公共接口位于 include/crypto/ 目录（如 crypt_eal_pkey.h）。
• EAL（Engine Abstraction Layer）是密码模块的统一调度层，crypto/eal/中的 API 再分派到crypto/rsa/、crypto/ecc/、crypto/sm2/等具体算法目录——这解释了后文命名规范中CRYPT_EAL_前缀的含义。
• 构建预设（full、iso19790）放在 cmake/presets/，而 config/macro_config/hitls_build.h 只是面向 provider 配置的静态重定向头，不要与 CMake 生成的运行时构建头混淆。

二、安全红线与漏洞报告

文档在正文开头就划定两条不可触碰的安全底线：

1. 漏洞必须走私密的报告通道：疑似密码缺陷、内存安全 bug、时序侧信道等问题，一律按 SECURITY.md 的流程上报，严禁以公开 issue 形式提出，也严禁在 issue、PR 或测试描述中粘贴 PoC 与漏洞利用细节。
2. 测试全绿不等于没有侧信道：任何触碰密钥、MAC 或解密数据的路径，都必须遵守后文的常量时间准则——回归测试通过只能证明功能正确，无法证明控制流与内存访问独立于秘密数据。

三、完成标准（Definition of Done）

一个变更任务只有同时满足以下全部条件才算完成。这一节是整份规范的核心，逐条拆解如下。

1. 库构建干净

(cd build && make -j)

要求构建成功且不产生新告警：需将构建日志与变更前的基线对比。文档特别强调，绝不允许用-Wno...或#pragma压掉告警来"达标"。另外，如果源码在编辑之外发生过变动（典型场景是git stash/git stash pop之后），在跑任何测试之前都必须重新构建。

2. 受影响的 SDV 套件通过

相关execute_sdv.sh调用中，你触碰过的每个用例必须报告 PASS。SKIP 仅在SKIP_TEST()保护下且该用例确实因无关功能被禁用时才允许；FAIL 永远不可接受。

3. 格式稳定

clang-format --dry-run --Werror <changed files>

--dry-run是不修改文件的检查模式（非变更操作）；文档提醒，只要编辑未暂存，git diff就无法替你验证格式，因此要显式跑这条命令。项目根目录存在 .clang-format 配置，所有代码应遵循该配置。

4. 敏感数据卫生

凡是触碰 crypto / key / MAC / password 路径的变更，必须做到：不对秘密派生数据使用memcmp、不存在依赖秘密值的提前退出（early exit）、不存在依赖秘密值的数组下标（详见第八节常量时间准则）。

5. 错误栈纪律

错误在第一生产点只压栈一次；如果被调用的下游函数已经压栈，调用侧必须用GOTO_ERR_IF_EX包裹，而不是GOTO_ERR_IF（二者区别见第五节）。

6. 禁止未授权的提交

除非用户明确要求，不得执行git add/git commit/git push或发起 PR。被要求时，提交信息需遵循 CONTRIBUTING-zh.md 中链接的约定，PR 只在 CI 流水线通过后才进入评审。

最后一条兜底原则：任何一步被阻塞（例如测试基础设施不可用），都要把阻塞点明确告知用户，而不是静默跳过。

四、构建命令全解

AGENTS.md 给出的总策略是：常规源码变更优先使用辅助脚本的 debug 构建；只有当用户明确要求特定 CMake 选项、或任务需要精细的功能选择时，才直接使用 CMake。

1. 辅助脚本构建（默认路径）

cd testcode/script && bash build_hitls.sh debug

阅读 build_hitls.sh 源码可以看到debug参数的实际效果：置debug_mode=true，追加-O0 -g3 -gdwarf-2编译选项，并移除-O2 -O3 -D_FORTIFY_SOURCE=2（见脚本parse_option函数中debug分支）。脚本的完整用法可以通过bash build_hitls.sh help查看，覆盖的模式还包括：

脚本内部对 x86_64 平台会额外打开HITLS_CRYPTO_SP800_STRICT_CHECK（SP800 严格检查）、HITLS_ASM_X8664=ON等选项；对 RISC-V 64 会自动加载cmake/toolchain/riscv64-linux-gnu-gcc.cmake工具链文件。

2. 直接 CMake 构建（精细控制）

完整用法见 构建与安装指南 的 "3.1 CMake Build" 一节，基本形态为：

mkdir -p build && cd build cmake .. [options] make -j

关键 CMake 选项：

完整选项清单见 cmake/hitls_options.cmake（其中HITLS_BUILD_PROFILE定义于该文件 第 46 行）。新增功能宏时应当编辑该文件；CMake 随后会基于模板 cmake/config.h.in 生成运行时构建头${CMAKE_BINARY_DIR}/config/hitls_build_config.h。再次强调：config/macro_config/hitls_build.h 仅用于 provider 配置的静态重定向，不是这个生成产物。

3. 交叉编译与增量构建

# 交叉编译（以 armv8_le 为例） cd testcode/script && bash build_hitls.sh armv8_le # 源码变更后的增量构建 cd build && make -j

build_hitls.sh会先执行clean()删除并重建build/目录，因此首次配置一定走 CMake；而增量构建只需在已有build/目录里make -j，这也是 Definition of Done 第 1 条要求重建的原因。

五、SDV 测试：从全量到单用例的四级粒度

openHiTLS 的回归测试体系称为 SDV 测试，测试用例位于testcode/sdv/testcase/下的.data数据文件，测试框架总览可参考 测试指南。

1. 全量 SDV 套件

cd testcode/script && bash build_hitls.sh debug && bash build_sdv.sh && bash execute_sdv.sh

三步分别是：构建主库 → 构建 SDV 测试程序 → 执行全部套件。阅读 execute_sdv.sh 可以看到它的运行机制：无参数时run_all()会用命名管道把testcode/output/下所有测试二进制并发拉起（并发度等于 CPU 核数，可用threads=N调整）；每个二进制默认以NO_DETAIL参数运行；结束时gen_test_report()调用./gen_testcase GenReport汇总 result.log 中的 PASS/SKIP/FAIL 计数，只要存在 FAIL 就以非零码退出。此外脚本还内置了 ASan 日志检查（generate_asan_log）：一旦在testcode/output或testcode/demo/build下发现asan.log*且内容不只是 ucontext 兼容告警，整个执行立即失败退出。

2. 测试范围的选择策略

• 窄范围变更：重建库，先跑最相关的单个 SDV 套件；
• 公开 API、共享的 crypto/TLS 逻辑、跨模块行为变更：跑所有受影响套件，并考虑跑全量 SDV；
• 构建系统、功能宏或平台相关变更：验证对应的构建 profile 或交叉编译目标。

3. 单个 SDV 套件

run-tests接收.data文件的文件名主干（不带路径、不带扩展名），用|分隔可指定多个套件：

# 步骤 1：源码变更过就先重建库 (cd build && make -j) # 步骤 2：构建并运行一个套件（run-tests 用 | 追加；按需去掉不需要的 no-<comp> 标志） (cd testcode/script && bash build_sdv.sh no-demos no-tls no-pki run-tests="test_suite_sdv_pake" && bash execute_sdv.sh test_suite_sdv_pake)

no-<component>标志会跳过对应组件的测试构建以节省时间——选择原则是排除你没触碰的组件：

这些标志在 build_sdv.sh 的parse_option中实现（no-crypto/no-bsl/no-tls/no-pki/no-auth/no-demos分支）。AGENTS.md 特别警告一个高发错误：照抄示例里的标志而不检查自己改的是哪个组件，会静默跳过你本需要验证的套件。例如修 PAKE（auth）问题时no-tls no-pki no-demos是合适的；修 RSA（crypto）问题则应使用no-tls no-pki no-auth no-demos——若错用了 PAKE 示例那组标志，crypto 测试照跑，但一旦漏掉no-auth/no-crypto的组合判断，就可能白跑或漏跑。

4. 单个测试用例（更快的迭代）

把用例名（@test标注的 ID，如SDV_CRYPT_EAL_SPAKE2PLUS_TC001）传给execute_sdv.sh，它会自动定位归属套件；也可以直接运行套件二进制并把用例名作为参数：

(cd testcode/script && bash execute_sdv.sh SDV_CRYPT_EAL_SPAKE2PLUS_TC001) # 或者 (cd testcode/output && ./test_suite_sdv_pake SDV_CRYPT_EAL_SPAKE2PLUS_TC001)

从execute_sdv.sh的parse_testsuite_testcase()可以看到定位逻辑：如果参数包含test_suite前缀且对应文件存在，按套件处理；否则在testcode/output下用grep -l搜索哪个套件的.c文件包含该用例名，自动把「套件 + 用例」配对后交给run_test()执行。

5. 发现可用套件

套件从testcode/sdv/testcase/下的.data文件自动发现。跨平台（Linux 与 macOS 均可）列出所有套件名：

find testcode/sdv/testcase -name "*.data" | sed 's|.*/||; s|\.data$||'

6. 性能基准测试

构建并运行 benchmark（选择器语法完整说明见 benchmark README）：

cmake -B build-benchmark -DHITLS_BUILD_BENCHMARK=ON && make -C build-benchmark -j openhitls_benchmark ./build-benchmark/testcode/benchmark/openhitls_benchmark -a 'sm2*' # -a <glob>, -t N iters, -s N secs

按 README，-a支持 glob 匹配（如sm2*匹配全部 SM2 用例、*-KeyGen匹配所有密钥生成用例），-t 10000指定每个用例迭代次数，-s 5指定按秒计时。

六、错误处理规范

1. 返回值约定

• 操作类 API 大多返回int32_t：成功为CRYPT_SUCCESS（0）或HITLS_SUCCESS（0），失败返回具体错误码；
• 构造/新建类 API 通常返回指针，用NULL表示失败；
• free/deinit 回调通常返回void；
• 错误码定义在 include/crypto/crypt_errno.h（crypto 模块）与 include/tls/hitls_error.h（TLS 模块）。

2. 错误栈与 goto ERR 清理模式

错误应在首次产生处压入 BSL 错误栈；若下游调用已经压栈，上层要避免重复压栈。对分配了资源的函数，统一采用goto ERR清理模式：

int32_t ret; Foo *a = NULL; Bar *b = NULL; a = Create(...); GOTO_ERR_IF(SomeOp(a), ret); // 压栈错误 + goto ERR GOTO_ERR_IF_EX(OtherOp(a), ret); // 仅 goto ERR（被调方已压栈） // ... 成功路径 ... ERR: Destroy(a); Destroy(b); return ret;

这些辅助宏定义在 crypto/include/crypt_utils.h：GOTO_ERR_IF（第 120 行）与GOTO_ERR_IF_EX（第 128 行）即上例所用；另有RETURN_RET_IF(cond, ret)与RETURN_RET_IF_ERR(func, ret)两个"压栈后直接 return"的变体，以及GOTO_ERR_IF_TRUE、GOTO_ERR_IF_SRC_NOT_NULL、GOTO_ERR_IF_DST_NULL等边界场景宏。

七、内存管理规范

• 库代码（crypto/、tls/、bsl/、pki/、auth/、codecs/、apps/）：一律使用BSL_SAL_Malloc(size)/BSL_SAL_Calloc(num, size)，禁止裸malloc/calloc；testcode/下的 SDV 测试代码则允许普通malloc/free；
• 释放使用BSL_SAL_FREE(ptr)宏（内部调用BSL_SAL_Free并把指针置NULL，防悬垂）；
• 敏感数据释放前先调用BSL_SAL_CleanseData(ptr, size)清零，或使用一步到位的BSL_SAL_ClearFree(ptr, size)（先擦除后释放）；
• 以上接口声明在 include/bsl/bsl_sal.h（System Abstraction Layer 公共头）。

这一约定把分配/释放/擦除都收敛到 SAL 抽象层，为测试桩（STUB）拦截、平台适配与审计提供了统一切面——从bsl/sal/下的sal_mem.c、sal_memimpl.h的实现结构可以看出，库内所有内存流量都从这里过账。

八、命名规范与代码风格

1. 命名前缀总表

• 文件名：module_purpose.c风格（如rsa_encdec.c、rsa_keygen.c、sm2_crypt.c——可在 crypto/rsa/src/ 目录直接对照验证）；
• 新文件结构：以项目 license 头开头（从目标模块任一现有.c文件复制），随后#include "hitls_build.h"，再跟上匹配本模块/功能的功能保护宏（HITLS_CRYPTO_XXX、HITLS_TLS_FEATURE_XXX、HITLS_PKI_XXX或HITLS_AUTH_XXX之一）。

2. 代码风格细则

• 避免新增注释，除非解释不显而易见的逻辑或被明确要求；
• 遵循每个文件内既有惯例；
• 栈上分配的字段元素数组使用ALIGN32/ALIGN64对齐，且尺寸按算法最坏情况取定，而非按输入长度；
• 文件末尾的#if/#ifdef必须有#endif收尾，且文件以换行符结束；
• docs/en/下的文档改动必须镜像到docs/zh/（本地化文件名），反之亦然；
• 根目录 .clang-format 是全库格式基准，新文件提交前必须clang-format -i格式化。

3. 常见反模式

• 公开 ABI 泄漏：不得向公开结构体（如CRYPT_EAL_LibCtx、HITLS_Ctx）添加字段，也不得修改HITLS_*/CRYPT_EAL_*函数的签名——公开 API 面是稳定的。
• 静默跳过测试：写if (disabled) return;的测试会被报告为 PASS。功能被禁用时必须调用SKIP_TEST()（定义于 testcode/framework/include/test.h），让报告能区分 pass / skip / fail 三种状态。

九、常量时间编程准则

这一节是整个规范中最具密码库特色的部分，适用于任何取值可能依赖私钥、明文、MAC、口令、共享密钥、解封装结果或其他秘密派生数据的代码路径。

1. 比较：用 ConstTimeMemcmp 替代 memcmp

对任何涉及秘密派生数据的比较（MAC 标签、解密后明文、口令派生密钥），使用ConstTimeMemcmp（来自 bsl/include/bsl_bytes.h）而非memcmp。注意它的语义与memcmp相反：

• 匹配返回0xffffffff；
• 不匹配返回0。

2. 秘密相关的条件分支

对秘密相关的条件选择，使用Uint32ConstTimeIsZero、Uint32ConstTimeEqual、Uint32ConstTimeSelect、Uint8ConstTimeSelect（均在bsl_bytes.h，第 213–231 行）。例如Uint32ConstTimeSelect(mask, a, b)按掩码在两个值之间选择，使选择逻辑不产生数据依赖的分支。

3. 循环与内存访问

• 循环上界：触碰秘密数据的循环必须使用公开的循环上界（例如params->t），配合掩码累加（masked accumulation），禁止依赖秘密值的提前退出；
• 内存访问地址：地址必须与秘密值无关——把"以秘密为键的表查找"替换为库内已有的常量时间选择/收集（gather）模式。仓库中可直接对标的三个实现：
  • crypto/rsa/src/rsa_padding.c：PKCS#1 填充解析用Uint32ConstTimeSelect做常量时间定位；
  • crypto/ecc/src/asm_ecp_nistp256.c：NIST P-256 窗口化标量乘法用ECP256_Gatherw5做常量时间点收集；
  • crypto/curve25519/src/curve25519_op.c：用MASK_LOW32位掩码避免依赖秘密值的移位/截断分支。

与之一条龙的工程机制是ctvalgrind构建模式：build_hitls.sh ctvalgrind会打开HITLS_CT_VALIDATION，使HITLS_CT_SECRET_MARK/HITLS_CT_SECRET_UNMARK标记生效；execute_sdv.sh ctvalgrind再把每个测试二进制放在valgrind --tool=memcheck --track-origins=yes --error-exitcode=1下运行，任何依赖被标记秘密字节的分支或内存索引都会把整条套件判为失败（见 execute_sdv.sh 中valgrind_prefix函数）。

十、架构细节备忘

AGENTS.md 用一小节沉淀了四个容易踩坑的架构事实：

1. HITLS_CRYPTO_RSA_BLINDING是 CMake 编译期选项（默认 OFF，定义于 cmake/hitls_options.cmake）；SDV 测试从库构建继承它是否开启。
2. CRYPT_RSA_BLINDING是CRYPT_RSA_Ctx->flags上的运行期标志。blinding 需要公钥指数e：crypto/rsa/src/rsa_encdec.c 中RSA_InitBlind会在prvKey->e未设置时，通过RSA_GetPublicExp（第 232 行）从d、p、q反推e；只有当推导失败时才需要通过SetRsaPrvKeyEx预先设置e。
3. 开启 blinding 的 RSA SDV 测试必须在操作前完成确定性的测试 RNG 配置，否则每次运行的掩码随机数不同会导致结果不可复现。
4. MontMulBin/MontMulBinCore内部使用mont->t作为暂存缓冲：绝不能把mont->t再作为输出参数传进去，否则会发生自我踩踏。

十一、SDV 测试数据格式与新增测试流程

1..data文件格式

测试用例位于testcode/sdv/testcase/下的.data文件，每个用例占两行：

自由文本描述行 TEST_FUNCTION_NAME:param1:param2:"hex_string":integer

字符串以双引号包裹的十六进制编码，整数/枚举直接裸写，用例之间空一行分隔。TEST_FUNCTION_NAME必须与套件.c文件中/* BEGIN_CASE */包裹的函数名完全一致。以 testcode/sdv/testcase/crypto/hkdf/test_suite_sdv_eal_kdf_hkdf.data 为例，真实数据长这样：

SDV_CRYPT_EAL_KDF_HKDF_API_TC001 api CRYPT_MAC_HMAC_SHA1 test SDV_CRYPT_EAL_KDF_HKDF_API_TC001:CRYPT_MAC_HMAC_SHA1

2. 套件三元组结构

每个 SDV 套件是testcode/sdv/testcase/<component>/<module>/下的三元组：

组.c文件在 license 头之后紧跟/* INCLUDE_BASE <suite> */声明其 base（例如 test_suite_sdv_eal_rsa_encrypt_decrypt.c 的第 15 行）。

3. 新增用例四步走

1. 写测试函数：放在组.c中，用/* BEGIN_CASE */ ... /* END_CASE */包裹。函数名必须等于.data行的第一个字段（拼错只会导致运行期"function not found"的静默失败）。头注释风格：@brief用 1–3 句描述主要测试流程与测试点（不是罗列每个 ASSERT，也不是流水账）；@expect一行写预期结果；@precon无特殊前置条件时写nan。形态参考 test_suite_sdv_eal_kdf_hkdf.c 中SDV_CRYPT_EAL_KDF_HKDF_FUN_TC001的完整可工作示例：

/* BEGIN_CASE */ void SDV_CRYPT_EAL_KDF_HKDF_FUN_TC001(int algId, Hex *key, Hex *salt, Hex *info, Hex *result) { if (IsHmacAlgDisabled(algId)) { SKIP_TEST(); } CRYPT_EAL_KdfCtx *ctx = CRYPT_EAL_KdfNewCtx(CRYPT_KDF_HKDF); ASSERT_TRUE(ctx != NULL); /* 通过 BSL_PARAM_InitValue + CRYPT_EAL_KdfSetParam 设置参数， 执行派生，然后 ASSERT_COMPARE 比对期望向量——参见参考文件 */ EXIT: CRYPT_EAL_KdfFreeCtx(ctx); } /* END_CASE */

2. 向对应.data文件追加一行或多行（格式见上节）。第一个字段必须与第 1 步的函数名一致。
3. ASSERT 宏（定义在 testcode/framework/include/test.h）：ASSERT_TRUE/ASSERT_EQ/ASSERT_NE/ASSERT_LT用于取值检查（失败时goto EXIT）；ASSERT_COMPARE用于字节缓冲差异比较；SKIP_TEST()标记跳过——功能被禁用时必须用它替换裸return，否则会被误报为 PASS。
4. 构建并运行：重建库，然后执行(cd testcode/script && bash build_sdv.sh run-tests="<suite_stem>" && bash execute_sdv.sh <suite_stem>)，在testcode/output/result.log中确认 PASS（或有守卫的 SKIP）。新建整套套件时，直接复制一个现成三元组起步（例如 testcode/sdv/testcase/crypto/rsa/）。

结语

AGENTS.md 的价值在于把"一个合格的 openHiTLS 变更应该长什么样"固化成了可执行的清单：用build_hitls.sh debug保证零新告警的干净构建，用no-<component>标志与单用例执行把测试粒度压到最小，用clang-format --dry-run --Werror保证格式不漂移，用错误栈纪律与 SAL 内存接口约束每一次资源流转，用常量时间准则和ctvalgrind工具链守住侧信道防线。把这套流程当作变更的默认工作路径，既能保证功能正确性，也能保证密码库最敏感的非功能属性不被无意破坏。

• 密码学
• 网络安全