2026 年 ML-DSA 代码签名怎么接入 CI/CD？

先在隔离流水线验证 ML-DSA 的密钥管理、签名与验签链路，以及制品消费者的兼容性，再决定是否分阶段启用；算法已标准化，不等于你的构建、发布和客户端生态都已支持。适用前提是你已明确签什么、谁来验签，以及失败时如何停止发布或回退。

负责软件制品签名的 DevSecOps 工程师，可以用本文梳理流水线验证步骤。
维护发布基础设施的工程师，可以据此盘点签名端与验签端的依赖。
制定代码签名迁移计划的安全负责人，可以据此划定试点范围和回退边界。

先划清签名对象和信任边界

动手前，先把“要保护的对象”说具体：是构建产物本身、更新包、容器镜像，还是描述构建过程的证明文件。签名对象不同，签名覆盖的字节、摘要计算时机和消费者验签位置也可能不同；如果构建后还有压缩、重打包或镜像改写，验签必须针对消费者最终拿到的对象，不能把“签过某个文件”当成链路闭环。

接着画出信任边界，至少标出构建执行环境、签名服务或密钥所在位置、制品仓库、发布端和最终消费者。对每一段写清谁能改制品、谁能请求签名、谁能更新信任公钥，以及审计记录由谁保管。

FIPS 204 是 ML-DSA 的正式标准，规定了数字签名的生成与验证算法；它不规定你的制品容器、密钥托管系统或每个客户端如何集成。NIST 页面也列出待处理的勘误信息，因此实现核对时应同时查正式标准与更新记录，而不能把候选算法或项目自定义方案直接称作 ML-DSA 标准实现。(csrc.nist.gov)

⚠️ 签名算法、密钥格式、制品封装和客户端支持是不同层次。任意一层不兼容，都可能出现“流水线签名成功，部署端却无法验证”的情况。

准备阶段：把密钥权限设计清楚

签名私钥是发布信任链的关键资产。先由团队决定密钥在哪里生成、是否允许导出、如何授权流水线调用、如何轮换，以及发生泄露时怎样吊销并分发新公钥。不要为了快速试跑，把私钥粘贴进仓库文件、流水线文本或普通日志；也不要假设 CI 平台的秘密变量会自动解决最小权限、轮换和吊销问题。

实现细节必须依赖你选定的密码库和密钥管理产品官方文档。核对产品实际支持的 ML-DSA 参数集、密钥导入导出限制、签名接口、错误处理和版本要求；文档没有明确支持的功能，先标成待验证，不要靠相似算法接口推断。

如果流水线使用秘密变量，仍要检查变量在哪些工作流可见、谁有权修改工作流，以及调试日志是否可能输出敏感内容。以 GitHub Actions 为例，官方文档提示秘密的自动脱敏并非对所有变形后的值都可靠，并建议限制凭据权限、审查工作流和处理日志泄露；这类平台机制不能替代密钥边界设计。(docs.github.com)

你可以先用这份清单过一遍准备情况：

• ✅ 私钥生成位置、托管方式和可否导出已由负责人确认。
• ✅ 只有受信任的发布任务能请求签名，普通构建与外部贡献任务不能直接调用。
• ✅ 轮换、吊销、公钥更新和事件响应都有明确责任人。
• ✅ 已记录密码库、密钥管理组件与客户端的版本和官方支持说明。
• ❌ 尚未确认私钥是否会进入日志、缓存、构建产物或调试附件时，不接入正式发布任务。

接入阶段：让签名和构建身份、制品摘要绑定

将签名放在构建完成之后、制品发布之前，并把签名请求与构建身份、提交或源代码版本、制品摘要、流水线运行记录关联。签名本身只能证明“某个密钥对某段数据签过名”；如果没有可信的构建来源记录，消费者仍难判断制品从何而来、由哪个流程生成。

为签名对象和签名封装设定固定约定：消费端究竟验证制品原始字节、摘要，还是包含制品摘要的证明文件；算法标识、上下文和公钥标识如何传递；发布系统如何拒绝缺少必要字段或算法标识不匹配的对象。若你采用证明文件，还需确认验证策略覆盖其中的制品名称与摘要，而不是只检查签名数学上成立。

SLSA 的来源证明模型把制品作为 subject，并将构建者、构建过程及输入材料等信息纳入来源描述；这能帮助你设计审计关联，但不能替你证明构建者可信或自动建立验证策略。(slsa.dev)

密码库能力也要落实到具体版本。例如，OpenSSL 文档说明其 ML-DSA 签名实现从 3.5 起提供，并列出 ML-DSA-44、ML-DSA-65 和 ML-DSA-87 的生成、签名与验签能力；这只说明该库的实现状态，不代表你的流水线封装或客户端已经支持。该文档还给出签名大小约为 2.5 KB 至 4.5 KB 的范围，参数集不同会影响签名数据体积，因而需要检查制品格式和传输环节的限制。(docs.openssl.org)

验证阶段：用负向用例证明客户端会拒绝

先让签名端对一份合法制品签名，再让实际消费端验签。然后逐项测试制品内容被修改、签名文件被替换、使用错误公钥、算法标识不匹配、签名缺失，以及证明内容指向其他制品等情况。每个失败场景都要确认客户端确实拒绝，而不只是流水线显示一个错误。

同时检查格式边界：签名对象是否发生换行或编码变化，摘要是对原始字节还是规范化后的内容计算，仓库下载和部署期间是否会重写对象。对于封装格式，签名者与验签者必须对 payload 类型和字节解释达成一致；DSSE 规范将 payload 类型纳入签名，并允许对任意类型的数据封装签名，但使用该格式不自动意味着你的客户端支持 ML-DSA。(github.com)

建议把以下结果保存在测试记录里，而不是只留一句“测试通过”：

• 合法制品的摘要、签名算法标识、验签工具与验证结果。
• 被修改制品及错误公钥的拒绝结果。
• 发布端和消费端各自读取的制品标识、格式与公钥来源。
• 客户端无法识别算法或格式时的具体错误，以及发布系统采取的动作。

NIST 的后量子迁移项目把密码资产发现与互操作测试列为迁移工作的一部分，并强调在受控环境识别兼容性问题；因此，后量子密码迁移不应只检查密码库能否生成签名，还要核查软件、服务和消费端之间的实际互操作。(nccoe.nist.gov)

试点阶段：用条件决定推广还是回退

先选非关键制品做试点，例如测试环境使用的发布包或内部工具产物，并按实际消费路径走完签名、存储、拉取、验签和部署。不要同时改算法、封装格式、客户端和发布权限，否则失败时难以定位是哪个环节造成的。

按检查结果选择下一步

• 若签名密钥隔离、构建身份可追溯、合法与篡改制品的验签结果符合预期，且目标客户端都通过测试，则扩大到下一类非关键制品，并保留分阶段放量。
• 若流水线能签名，但旧版客户端、镜像仓库或部署工具无法识别格式或算法，则不切换该消费链路；保留旧签名验证能力，改用双轨验证或等客户端升级后再试。
• 若密钥可能暴露、审计记录不能关联制品摘要，或篡改制品仍能通过，则停止发布并回到既定流程；先修复权限、绑定关系或验签策略，再重新进入试点。
• 若失败只是测试环境缺少实现或依赖，且尚未影响生产信任链，则隔离测试记录与发布通道，明确需要补齐的版本和责任人，不把待支持状态写成已兼容。

切换前还要检查仓库保留旧签名的能力、客户端升级节奏、公钥分发方式和回退后如何避免新旧策略混淆。回退不是简单地“重新打开旧签名”：必须明确哪些制品可以沿旧路径发布、旧公钥如何继续验证，以及发生密钥吊销时怎样阻止不再可信的版本被接受。

在实际开发环境里划定复现范围

如果你要用临时开发环境复现流水线，先确认环境操作系统、交付方式、网络与存储限制，以及能否安装所选密码库和验签工具。ZavCloud 的帮助中心可用于核对环境使用相关信息；但环境可用不等于其中的密码库、CI/CD 组件或消费端已经支持 ML-DSA。

复现记录只写实际验证过的内容：环境类型、工具版本、操作步骤、输入制品摘要、签名与验签结果、失败用例和限制。没有真实运行记录，就不要推导签名性能、密码学安全性或生产适用性；这些结论必须来自相应实现的官方资料和你自己的测试证据。

常见问题：兼容、验签与回退

能否把 ML-DSA 直接用于所有软件制品签名？
不要一次性套用到所有制品。先确认签名对象、封装格式和每个消费端的验签能力，再选择一类低风险制品试点；任何关键客户端未通过验证，都应暂缓该发布路径的切换。

怎样确认流水线的签名不是只在构建端“自我验证”？
让真正部署或安装制品的消费端执行验签，并加入篡改制品、错误公钥和格式不匹配等负向用例。对照签名端和消费端记录的制品摘要与身份，避免两端验证的其实是不同文件。

旧客户端暂时不支持时，试点怎样继续？
将新签名限制在已验证的消费端和非关键制品范围内，保留旧签名验证路径，并明确哪些客户端仍走旧流程。不要让未识别新算法的客户端静默跳过验签；需升级客户端或建立经审查的双轨策略后，再扩大范围。

推广前，把现有流程和 Mac 测试环境分开评估

如果你目前依赖通用构建节点或共享 CI 执行环境，常见限制是目标操作系统覆盖不足、工具版本难以固定，以及消费端环境不在同一条验证链路中；改为 Mac 环境也不会自动解决 ML-DSA 实现和客户端兼容问题。只有当你的发布链路确实需要复现 Mac 开发或测试环境、且密码库与工具已确认兼容时，临时租用 ZavCloud Mac 才可能比长期维护一台专用测试机更适合短期验证；若负载长期稳定、需要持续持有硬件接口或必须自主管理密钥设备，自购设备或现有专用环境可能更合适。你可以先核对Mac 云租用环境的交付与使用条件，再按本地密码库文档复核，不要把环境租用理解为 ML-DSA 支持承诺。

准备开始后，先把开发环境和密码库兼容性列入验收条件，再阅读后量子迁移测试指南，从隔离试点开始；确认签名、验签与回退记录完整之后，再决定哪些发布流程进入推广阶段。