openHiTLS 社区贡献指南：CLA 签署、Issue 讨论与本地构建验证实战-育师

密码学
网络安全

【免费下载链接】openHiTLS

旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件，通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求，让密码技术应用更简单，同时探索后量子等先进算法创新实践，构建密码前沿技术底座！

项目地址：https://gitcode.com/openHiTLS/openhitls

本文基于仓库中的 CONTRIBUTING-zh.md 梳理 openHiTLS 密码套件的社区贡献全流程：GitCode 账号注册、贡献者许可协议（CLA）签署、Issue 领取与充分讨论、Pull Request（PR）提交与代码检视。文章重点对原文中一笔带过的“本地构建与验证”环节进行扩充，结合仓库内的构建脚本、SDV 测试框架与代码风格约定，给出一套可本地自检的提 PR 前验证流程，帮助新贡献者提交即符合社区评审要求。

![SDV 测试执行流程：先编译源码（build_hitls.sh），再编译测试代码（build_sdv.sh），最后调度运行测试用例（execute_sdv.sh）](https://raw.gitcode.com/openHiTLS/openhitls/raw/70b3808ffd622e0af775cf08b380beaa62a638fd/docs/zh/images/User Guide/Test Guide_figures/TestCaseExecutionProcess.png?utm_source=gitcode_repo_files)

![SDV 测试框架的 Function 文件与 Data 文件对应关系：测试函数由 .data 文件中的用例参数行驱动](https://raw.gitcode.com/openHiTLS/openhitls/raw/70b3808ffd622e0af775cf08b380beaa62a638fd/docs/zh/images/User Guide/Test Guide_figures/TestFrameworkDescription.png?utm_source=gitcode_repo_files)

1. 贡献前置条件：账号注册与 CLA 签署

1.1 注册 GitCode 账号并设置主邮箱

openHiTLS 社区项目源代码托管在 GitCode 平台。按照原文档的要求，贡献者需要参考 GitCode 官方文档完成账号注册，并在账号设置页面配置自己的主邮箱（主邮箱是后续提交作者身份与 CLA 绑定的关键信息）。

1.2 签署 openHiTLS 贡献者许可协议（CLA）

在参与社区贡献前，需要根据自身参与身份提前签署 openHiTLS 社区贡献者许可协议（CLA）。原文档将签署身份分为三类：

参与身份	应签署的 CLA	说明
个人	个人 CLA	以个人身份参与社区
企业管理员	法人 CLA（企业 CLA）	以企业管理员身份参与社区
企业员工	法人贡献者 CLA（员工 CLA）	以企业员工身份参与社区，需先完成法人 CLA 签署

原文档同时给出了参考资料：官方网站上提供《企业及其员工签署 openHiTLS 贡献者许可协议（CLA）指导》，可按步骤完成签署。

1.3 签署后还需阅读的两份社区规范

原文档第 3 节明确要求：为维护社区的友好开发和协作环境，参与贡献之前请先阅读并遵守 openHiTLS 社区的行为守则以及社区仓库中的**《开发行为规范》**。这两份规范与 CLA 一样，是贡献的前置条件而非可选项。

1.4 了解项目许可与源码文件头

从仓库内容看，openHiTLS 采用 Mulan PSL v2 许可证（见 LICENSE）。所有 C 源文件均以项目许可头开头，例如 testcode/sdv/testcase/crypto/hkdf/test_suite_sdv_eal_kdf_hkdf.c 的前 15 行即 Mulan PSL v2 许可声明。AGENTS.md 也指出：新增源码文件应先从目标模块中任一现有.c文件复制项目许可头，再写业务代码。贡献新文件时请保持这一约定。

2. 提交 Issue：认领任务、新建 Issue 与提 PR 前的充分讨论

2.1 找到愿意处理的 Issue

按照原文档 3.1.1 节的流程：

进入感兴趣的 openHiTLS 工作组项目在 GitCode 上的主页，单击“Issues”，查看 Issue 列表；
如果愿意处理其中某个 Issue，在该 Issue 的评论区积极评论表达意向，管理员会将 Issue 分配给你；
请及时处理已分配的 Issue——若处理不及时，管理员可能将其重新分配给其他人；
也可以直接在对应团队或项目仓库的 Issue 面板中“新建 Issue”。

2.2 新建 Issue

如果你准备向社区上报 Bug、提交需求，或贡献自己的意见建议，请在对应仓库提交 Issue。原文档给出的新建步骤是：

进入 Issue 面板，单击“新建 Issue”；
在类型下拉框中选择“需求”，系统会自动调出需求模板；
标题栏简要描述需求要点；
在详细说明框内说明需求的场景和价值。

安全类问题的重要边界：上报 Issue 前请先判断问题性质。按照 SECURITY.md 与 AGENTS.md，涉及内存安全、密码学正确性缺陷、TLS 协议层缺陷、PKI 解析缺陷、侧信道等问题必须通过官方漏洞报告渠道提交，绝不能作为公开 Issue 提出；PoC 与利用细节也不得粘贴进 Issue、PR 或测试描述中。普通功能缺陷、需求与建议才走公开 Issue 流程。

2.3 提交 PR 前在 Issue 内充分讨论

原文档 3.1.3 节建议：对于领取到的 Issue 任务或想发起的大型贡献，在开始代码工作之前，先发起一个 Issue 讨论，在每个 Issue 下面与社区 Maintainer、Committer 等核心开发者充分讨论方案思路，并提供相应的设计思路文档。响应时效上，社区轮值 Maintainer 将在2 个工作日内对最新讨论做出回复，或分配给相关领域专家答复。

3. 代码贡献准备：开发注意事项与分支工作流

3.1 了解目标模块内的开发注意事项

原文档 3.2.1 节指出：每个工作组内的项目使用的编码语言、开发环境、编码约定等都可能存在差异。参与编码类贡献应遵守社区仓库（openHiTLS/community 的contributors/目录）中的**《编码安全规范》和《代码风格规范》**。

针对本仓库，AGENTS.md 给出了可直接对照的约定速查，贡献代码时可作为基线：

类别	约定要点
命名前缀	公共密码 API`CRYPT_EAL_`、公共 TLS API`HITLS_`、BSL 工具`BSL_`、PKI`HITLS_X509_`/`HITLS_CMS_`、认证`HITLS_AUTH_`、特性宏`HITLS_CRYPTO_`/`HITLS_TLS_`等（见 AGENTS.md）
内存管理	库代码统一使用`BSL_SAL_Malloc`/`BSL_SAL_Calloc`与`BSL_SAL_FREE`（声明于 include/bsl/bsl_sal.h），敏感数据释放前调用`BSL_SAL_CleanseData`
错误处理	错误在首个产生点推入 BSL 错误栈且只推一次；调用方若需在其后跳转清理，使用`GOTO_ERR_IF_EX`而非`GOTO_ERR_IF`（宏定义于 crypto/include/crypt_utils.h）
公共 ABI	不向公共结构体（如`HITLS_Ctx`）添加字段，不修改`HITLS_`/`CRYPT_EAL_`函数签名
文档镜像	`docs/en/`与`docs/zh/`的文档变更需双向镜像同步

3.2 下载代码和拉分支

按照原文档 3.2.2 节，参与代码贡献需要了解如何在 GitCode 下载代码并通过 PR 合入代码；该托管平台的使用方法类似 GitHub，具体操作可参考 GitCode 官方文档中的《Fork 工作流》。克隆本仓库的命令为：

git clone https://gitcode.com/openHiTLS/openhitls

仓库顶层目录结构与各模块职责可参考 docs/zh/4_使用指南/1_构建及安装指导.md 和 AGENTS.md 中的结构表：crypto/（对称/非对称、哈希、KDF、后量子算法）、tls/（TLS 协议栈）、pki/（X.509/CMS）、bsl/（基础支撑库）、auth/（PAKE/OTP 等认证协议）、apps/（命令行工具）、testcode/（测试与构建脚本）、cmake/（构建系统）。Fork 后建议在本地拉出功能分支完成修改，避免直接在主干分支上操作。

4. 本地修改、构建与验证

原文档 3.2.3 节对此只有一句话：“在本地分支上完成修改后，进行构建和本地验证。”由于这是 PR 能否进入评审的硬性前提（见第 5 节），下面结合仓库实际构建与测试设施，把“本地验证”展开为可执行、可自检的流程。

4.1 构建环境与两种构建方式

根据 docs/zh/4_使用指南/1_构建及安装指导.md，构建环境要求如下：

名称	推荐版本	说明
Gcc	>=7.3.0	Linux
CMake	>=3.16	仓库 CMakeLists.txt 中`cmake_minimum_required(VERSION 3.16)`
Sctp	无版本限制	DTLS 特性依赖，默认关闭，开启前需预装

方式一：辅助脚本（日常修改推荐）

cd testcode/script && bash build_hitls.sh debug

该脚本（testcode/script/build_hitls.sh）会完成配置与编译；交叉编译场景可改用对应目标，例如bash build_hitls.sh armv8_le。

方式二：直接调用 CMake（需要细粒度选项控制时）

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

常用选项（摘自 AGENTS.md）：

选项	说明
`-DHITLS_BUILD_PROFILE=full/iso19790/none`	`full`启用全部特性（默认）；`none`从显式给定的特性开关起步
`-DHITLS_CRYPTO_<ALG>=ON/OFF`	开关具体算法，如`HITLS_CRYPTO_RSA`、`HITLS_CRYPTO_SM4`
`-DHITLS_ASM_<ARCH>=ON`	为单一架构启用汇编：`HITLS_ASM_ARMV8`/`HITLS_ASM_ARMV7`/`HITLS_ASM_X8664`/`HITLS_ASM_X8664_AVX512`/`HITLS_ASM_RISCV64`。注意：不存在自动探测开关，由`build_hitls.sh`按目标设置

完整选项清单见 cmake/hitls_options.cmake。源码变更后做增量构建：cd build && make -j。

4.2 运行 SDV 测试套件

SDV 测试用例位于 testcode/sdv/testcase/ 目录（apps、auth、bsl、cmvp、codecs、crypto、pki、tls八个组件子目录，当前包含 230 余个.data用例文件）。

全量运行：

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

单套件运行（run-tests参数传.data文件名主干，用|分隔可指定多个）：

(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>开关用于跳过未改动组件的测试构建以节省时间（testcode/script/build_sdv.sh）：

开关	作用
`no-crypto`	跳过 crypto 测试
`no-tls`	跳过 TLS 测试
`no-pki`	跳过 PKI 测试
`no-auth`	跳过 auth 测试
`no-bsl`	跳过 BSL 测试
`no-demos`	不构建 demo 程序

注意开关要与实际改动匹配：改 PAKE（auth 模块）适合no-tls no-pki no-demos，改 RSA（crypto 模块）则应使用no-tls no-pki no-auth no-demos；盲目照抄示例开关可能静默跳过你真正需要验证的套件。该脚本还支持asan、ctvalgrind（恒定时间验证构建）、gcov、tls-debug、verbose等辅助开关。

单用例运行（更快迭代）：将@test用例名传给 testcode/script/execute_sdv.sh，脚本会自动定位所属套件：

(cd testcode/script && bash execute_sdv.sh SDV_CRYPT_EAL_SPAKE2PLUS_TC001)

列出全部可用套件：

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

测试范围选择原则（参考 AGENTS.md）：窄改动先重建库并跑最相关的单个套件；公共 API、共享密码/TLS 逻辑或跨模块行为变更应跑受影响套件并考虑全量；构建系统、特性宏或平台相关变更则验证对应构建 profile 或交叉编译目标。

4.3 同步提交测试 case 代码

原文档在 PR 提交要求中明确提出：“在提交开发代码，特别是特性开发代码的同时，提倡同步提交测试 case 代码，保证开发和测试的同步”。仓库内 SDV 框架的加测约定如下：

套件文件结构：每个 SDV 套件是 testcode/sdv/testcase/ 下<component>/<module>/目录中的“三件套”：<suite>.base.c（main + 框架初始化 + 共享桩）、<suite>_<group>.c（一个功能组的测试函数）、<suite>_<group>.data（驱动对应.c的用例行）。组.c文件在许可头后紧接/* INCLUDE_BASE <suite> */声明所属 base；新建套件可直接复制现有三件套（如testcode/sdv/testcase/crypto/rsa/）。
测试函数：写在组.c中，用/* BEGIN_CASE */ ... /* END_CASE */包裹；函数名必须等于.data行的第一个字段，拼写错误会导致运行时静默报“function not found”。
.data格式：每个用例两行——自由描述行，加上TEST_FUNCTION_NAME:param1:param2:"hex_string":integer；字符串用双引号包裹并做十六进制编码，整数/枚举裸写，用例之间空一行。
断言与跳过：ASSERT_TRUE/ASSERT_EQ/ASSERT_NE/ASSERT_LT/ASSERT_COMPARE等宏定义于 testcode/framework/include/test.h。特性禁用时务必调用SKIP_TEST()而不是裸return——裸 return 会被误报为 PASS，跳过与通过必须可区分。
新增源文件结构：许可头 →#include "hitls_build.h"→ 对应模块/特性宏保护（如HITLS_CRYPTO_XXX）。

一个可完整照抄的参考用例是 testcode/sdv/testcase/crypto/hkdf/test_suite_sdv_eal_kdf_hkdf.c 中的SDV_CRYPT_EAL_KDF_HKDF_FUN_TC001。框架整体说明可参考 docs/zh/4_使用指南/2_测试指南.md。

4.4 提交 PR 前的本地自检清单

以下清单整理自 AGENTS.md 的 “Definition of Done”，建议每次提 PR 前逐项执行：

库构建干净：(cd build && make -j)成功且无新增警告；与改动前基线对比构建日志，且不要用-Wno...或#pragma压警告；
受影响 SDV 套件 PASS：对应execute_sdv.sh输出 PASS；SKIP 仅在确有SKIP_TEST()保护时才允许，FAIL 不可接受；
格式稳定：clang-format --dry-run --Werror <改动文件>无报错；新文件提交前用clang-format -i格式化。仓库根目录 .clang-format 规定缩进 4 空格、列宽上限 120、指针靠右（PointerAlignment: Right）；
秘密数据卫生（凡触碰密钥/MAC/口令路径）：不使用memcmp比较秘密派生数据（应使用bsl_bytes.h的ConstTimeMemcmp），不出现秘密依赖的提前退出或数组下标；
错误栈纪律：错误只在首个产生点推入一次；被调方已推入的场景用GOTO_ERR_IF_EX包装；
公共 ABI 不变：不向公共结构体加字段、不改公共函数签名。

5. 提交一个 Pull Request

当你在 GitCode 上为项目发起 PR 时，即意味着正式开始向社区贡献代码。按照原文档 3.2.4 节，为使提交更容易被接受，需要满足四点：

准备完善的提交信息，遵守社区仓库中的《commit 信息书写规范》；
拆分大提交：如果一次提交的代码量较大，建议将大型内容分解成一系列逻辑上较小的提交，分别提交更便于检视者理解你的想法；
同步提交测试 case 代码：与第 4.3 节的加测约定配合，保证开发和测试同步；
确保 PR 代码流水线检查通过——原文档对此加粗强调：未通过流水线检查的 PR不会进入代码审核环节。AGENTS.md 同样写明 “PRs enter review only after the CI pipeline passes”。因此在推送前，先按 4.4 清单在本地把构建、SDV 与格式检查跑绿，能显著提高进入评审的概率。