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

密码学网络安全【免费下载链接】openHiTLS旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求让密码技术应用更简单同时探索后量子等先进算法创新实践构建密码前沿技术底座项目地址https://gitcode.com/openHiTLS/openhitls点击查看免费下载本文基于仓库中的 CONTRIBUTING-zh.md 梳理 openHiTLS 密码套件的社区贡献全流程GitCode 账号注册、贡献者许可协议CLA签署、Issue 领取与充分讨论、Pull RequestPR提交与代码检视。文章重点对原文中一笔带过的“本地构建与验证”环节进行扩充结合仓库内的构建脚本、SDV 测试框架与代码风格约定给出一套可本地自检的提 PR 前验证流程帮助新贡献者提交即符合社区评审要求。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 给出了可直接对照的约定速查贡献代码时可作为基线类别约定要点命名前缀公共密码 APICRYPT_EAL_、公共 TLS APIHITLS_、BSL 工具BSL_、PKIHITLS_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构建环境要求如下名称推荐版本说明Gcc7.3.0LinuxCMake3.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_PROFILEfull/iso19790/nonefull启用全部特性默认none从显式给定的特性开关起步-DHITLS_CRYPTO_ALGON/OFF开关具体算法如HITLS_CRYPTO_RSA、HITLS_CRYPTO_SM4-DHITLS_ASM_ARCHON为单一架构启用汇编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-teststest_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 程序注意开关要与实际改动匹配改 PAKEauth 模块适合no-tls no-pki no-demos改 RSAcrypto 模块则应使用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.cmain 框架初始化 共享桩、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输出 PASSSKIP 仅在确有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 与格式检查跑绿能显著提高进入评审的概率。6. 检视代码与和社区一起成长6.1 代码检视关注什么openHiTLS 是一个开放的社区希望所有参与者都能成为活跃的检视者当你成为工作组的 committer 或 maintainer 角色时便拥有审核代码的责任与权利。原文档引用《补丁审核的柔和艺术》The Gentle Art of Patch Review中的理念代码检视应当促进新贡献者积极参与而不是让他们一开始就被细微错误淹没。因此检视时可重点关注三件事贡献背后的想法是否合理贡献的架构是否正确贡献是否完善。从本仓库的工程约定看AGENTS.md、SECURITY.md评审密码模块 PR 时还可以对照恒定时间要求秘密派生数据的比较与控制流与错误栈纪律做专项检查。6.2 角色与成长路径社区不同角色对应不同的责任与权利每种角色都是社区不可或缺的一部分。贡献者可以通过积极贡献不断积累经验和影响力并获得角色上的成长各角色的详细定义与责权描述可查阅社区章程说明openhitls.net 社区网站。至此从注册账号、签署 CLA到 Issue 讨论、本地构建验证、提 PR 到代码检视与角色成长即构成 openHiTLS 社区贡献的完整闭环前置协议第 1 节→ 任务与方案第 2、3 节→ 本地构建与 SDV 验证第 4 节→ 流水线通过后进入评审第 5、6 节。赞分享密码学网络安全【免费下载链接】openHiTLS旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求让密码技术应用更简单同时探索后量子等先进算法创新实践构建密码前沿技术底座项目地址https://gitcode.com/openHiTLS/openhitls点击查看免费下载相关推荐FlatBuffers 贡献指南从 CLA 签署、代码评审到文档本地构建与发布FlatBuffers 贡献指南从 CLA 签署、代码评审到文档本地构建与发布 导读 本文以 FlatBuffers 官方贡献指南 docs/source/序列化代码生成Retrofit 贡献指南从 Fork 提交 PR 到构建验证与 CLA 签署的完整流程Retrofit 贡献指南从 Fork 提交 PR 到构建验证与 CLA 签署的完整流程 Retrofit 是一款面向 Android 与 JVM 的类型安全网络API设计TopDeepLearning社区建设指南如何参与讨论和贡献TopDeepLearning社区建设指南如何参与讨论和贡献 欢迎来到TopDeepLearning社区作为深度学习爱好者和开发者的聚集地我们致力于打造一人工智能深度学习教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考