软件加固交付前构建与签名材料说明：可提交清单与私钥隔离边界

交付材料的核心定义与责任边界划分

加固包交到下游时，接收方需要回答三个问题：文件有没有被替换、由谁签名、来自哪次构建。产物摘要、公钥证书和构建记录分别提供这些线索。清单同时写明禁止提交的材料，让私钥、口令和可导出凭据始终留在签名环境。

根据 Android 开源项目文档，应用签名主要用于建立更新身份，不同的签名方案覆盖不同的文件区域和平台版本，但这仅保证了文件的完整性。Apple 平台则通过代码签名、证书与运行时验证来建立 App 身份，其签名链机制与 Android 完全不同。因此，材料清单必须严格区分平台，分别提供对应的证书链与签名方案证据。接收方需按各自平台的本地验证方式核验，混用判断逻辑可能导致严重的误信风险。

安全开发框架建议保留来源、构建、验证和变更记录，交付清单可以承载其中与当前产物相关的部分。但文件齐全并不自动可信：接收方仍要使用预先认可的公钥和候选包摘要做核对，并把缺失或不匹配项留作明确异常。

• 是否已依据目标平台要求导出了完整的签名块信息与证书列表？
• 清单是否明确注明只包含公钥部分，且无任何私钥衍生数据或口令？
• 是否附上了独立于签名机制之外的产物摘要供接收方交叉比对？

可提交材料详解：证书、签名元数据与数字化摘要

可提交材料的首要组成部分是 APK 签名信息，这通常需要使用 apksigner 或类似工具导出的签名方案明细。这些明细涵盖了 V1、V2、V3 等不同版本的覆盖区块以及具体的签名算法标识。同时，必须附带签名证书的 SHA-256 指纹及其公钥部分，以便接收方能与渠道预期的发布者信息进行精确比对。签名证书本身不含私钥，只提供签发者身份和公钥要素，因此作为公开证据提交在密码学上是安全的。

数字化摘要必须使用标准的密码学哈希函数，如 SHA-256，对加固后的 APK 文件进行计算，并随包提供。该摘要独立于签名机制存在，主要用于防止重放攻击和产物错配。SLSA Provenance v1.1 明确要求构建证明必须绑定产物主体及其摘要，因此交付清单中绝不能省略产物摘要。接收方可单独校验该摘要，无需依赖复杂的签名工具即可确认文件在传输过程中是否被意外修改。

构建来源证明由构建系统在构建结束时自动生成，详细描述了构建者身份、构建类型、入口参数、依赖材料以及外部输入等关键信息。接收方可根据该证明追溯具体的构建环境，但这并不能直接证明运行时的安全性。提交方必须确保 provenance 中的 subject 字段指向与交付产物完全一致的摘要，否则该证明即刻失效，无法作为信任依据。任何参数不匹配都意味着构建记录与实物脱节。

• 证书公钥与指纹是否与预期发布者的记录完全匹配？
• 提供的摘要是否与交付包在本地计算的值严格一致？
• provenance 中的 subject 字段是否准确指向同一产物摘要？

不可提交的私钥：身份根的保护与绝对分离

私钥是签名身份的根源，一旦提交私钥，接收方就能任意以提交方身份签发更新，这将彻底破坏信任链条。因此，在交付材料中绝不允许包含私钥、keystore 文件或任何可推导私钥的口令、助记词。传递私钥的行为将使之前所有基于签名的身份校验失去意义，这是一个不可逆的安全失败。任何要求提供私钥的请求都应被视为高危信号并立即拒绝。

签名责任应在独立的、受保护的环境中执行，例如离线 HSM 或临时的专用构建机。提交的只是签名后的产物和证书，而非签名能力本身。这样可以审计每一次签名事件，但签名权仍限定于构建者。即使出于应急恢复的理由，也不应在交付中附加私钥，而应采用预先协商的证书替换、共同签名或门禁恢复流程来解决问题。

将私钥纳入交付是高风险反模式，多数安全评审直接拒绝此类做法。私钥泄露常常源于错误的传输习惯，许多事故证明将私钥通过邮件、即时消息或随源码打包传送会导致攻击者永久接管身份。加固交付流程中必须将私钥完全排除在材料清单之外，由签名实体单独管理，确保物理和逻辑上的双重隔离。

• 交付包中是否彻底排除了任何扩展名为.jks、.p12 或.keystore 的文件？
• 配置文件或脚本中是否硬编码了任何可能用于还原私钥的密码字符串？
• 是否有明确的书面声明指出私钥未包含在此次交付的任何介质中？

签名责任与最终身份：声明约束而非文件堆砌

Android 和 Apple 平台均通过签名建立安装和更新时的身份连续性，但应用签名仅证明文件来源与完整性，不保证其行为无害。因此，在加固交付中接收方需明确：签名合法只满足平台准入条件，不代表应用通过安全审查。从签名验证成功推导应用安全是错误的逻辑，必须结合额外的行为分析和动态测试才能得出更全面的结论。

构建证明可以把产物摘要、构建者和参数放进同一份声明。in-toto 的声明格式便于机器读取这些字段，但格式正确不代表内容真实。接收方仍要核对声明签名者是否在信任列表中，以及摘要是否与手上的候选包一致。

提交材料时应明确声明签名责任主体，例如具体的组织单元，并限定该密钥用途，如仅用于该产品线。接收方需按策略比对声明和实际签名者，发现不一致则应阻断。签名者身份的判定不能仅凭证书通用名称，还要比对 provenance 中的 builder 标识，以排除代理签名造成的身份错配，确保责任归属清晰无误。

• 声明中的签名责任主体是否与组织架构中的实际拥有者一致？
• 密钥用途限制是否在证书扩展字段或附属文档中明确标注？
• 接收方是否有能力比对 provenance 中的 builder 标识与证书主体？

构建证明与材料清单的装配逻辑

构建完成时就生成对应记录，至少包含 APK 或 AAB 摘要、构建者、构建类型、加固工具版本和关键依赖摘要。记录与产物一起归档，避免事后补交时无法确认它们是否来自同一次构建。

如果项目对构建证明签名，交付时只提供签名后的声明和公钥验证信息。接收方先验声明签名，再比对其中的产物摘要；任一结果不一致，就把构建记录与实物标为不匹配并回到流水线排查。SLSA 描述证明内容与等级，不应被误写成所有项目都必须采用同一种签名实现。

需要机器可读格式时，可用 in-toto statement：subject 绑定产物摘要，predicateType 标明声明类型，predicate 保存构建字段。是否再使用 DSSE 取决于现有证明系统；无论采用哪种封装，交付材料都不包含用于签名的私钥。

• 证明文件本身是否已被组织级根密钥正确签名？
• subject 中的摘要是否与文件系统上的产物哈希完全一致？
• externalParameters 中是否包含了加固工具的具体版本号？

材料清单自检脚本：安全诊断与零私钥接触

以下脚本接收加固后的 APK 路径和可选的期望证书指纹，使用 apksigner 和系统哈希工具完成验证。脚本运行过程中绝不请求或加载任何私钥、keystore 或口令文件。如果提供了期望指纹，脚本会实施严格比对；否则仅输出包含摘要与指纹的 JSON 清单。任何失败状态均返回非零值，适合嵌入 CI 或门禁流水线自动调用，确保流程自动化且安全。

脚本首先计算 APK 的 SHA-256 摘要，随即调用 apksigner verify 提取证书指纹。若签名验证失败，脚本直接报错并将具体原因输出到 stderr，阻止后续步骤。成功执行后，将摘要与指纹包装为 JSON 材料清单输出，不携带多余信息，不泄露密钥材料。这种设计确保了验证逻辑完全基于公钥信息和公开的工具接口，符合私钥隔离原则。

包含此脚本的交付套件可向接收方证明材料清单的生成过程本身也未触碰秘密材料。验证逻辑完全基于公钥信息和公开的工具接口，与组织安全策略中的私钥隔离原则一致。接收方可单独运行脚本复验，确认产物未被传输过程篡改，签名者身份与预期一致，从而建立对交付物的初步信任基础。

• 脚本是否在无网络环境下也能独立完成所有校验步骤？
• 错误退出码是否区分了文件缺失、签名失败和指纹不匹配？
• 输出 JSON 是否严格遵循标准格式且无多余调试信息？

#!/bin/bash
set -euo pipefail

# 检查输入参数
APK="$1"
EXPECTED_FINGERPRINT="${2:-}"

if [ ! -f "$APK" ]; then
  echo "ERROR: APK 文件不存在，请检查路径" >&2
  exit 1
fi

echo "==> 开始计算 APK 文件摘要"
APK_DIGEST=$(shasum -a 256 "$APK" | awk '{print $1}')
echo "SHA-256: $APK_DIGEST"

echo "==> 验证 APK 签名并提取证书信息"
SIG_INFO=$(apksigner verify --print-certs "$APK" 2>&1) || {
  echo "ERROR: 签名验证失败，APK 可能未签名或被破坏" >&2
  exit 1
}

CERT_FINGERPRINT=$(echo "$SIG_INFO" | awk '/Signer .* certificate SHA-256 digest/{getline; print $2}')

if [ -z "$CERT_FINGERPRINT" ]; then
  echo "ERROR: 无法从签名信息中提取证书指纹" >&2
  exit 2
fi
echo "签名者证书指纹：$CERT_FINGERPRINT"

if [ -n "$EXPECTED_FINGERPRINT" ]; then
  if [ "$CERT_FINGERPRINT" != "$EXPECTED_FINGERPRINT" ]; then
    echo "ERROR: 证书指纹不匹配期望值" >&2
    echo "期望：$EXPECTED_FINGERPRINT" >&2
    echo "实际：$CERT_FINGERPRINT" >&2
    exit 3
  fi
  echo "证书指纹匹配成功"
else
  echo "未提供期望指纹，跳过比对步骤"
fi

echo "==> 生成材料清单摘要 JSON"
cat <<EOF
{
  "apk_digest": "$APK_DIGEST",
  "signer_fingerprint": "$CERT_FINGERPRINT"
}
EOF

常见交付误区与证据边界澄清

apksigner verify 通过后，能确认的是 APK 签名结构和证书信息；构建节点、密钥保管和分发渠道并不在它的检查范围内。报告里应把这个结果写成签名检查通过，而不是扩展为整条流程可信。

代理签名场景还要区分签名者与构建者。证书主体、构建证明中的 builder 标识和委托记录分别核对；不一致时先确认是否为已授权代理，不直接把格式差异解释成攻击，并把核对结果关联到当前候选包。

Android 与 Apple 的签名工具、校验单元和错误语义不同。清单可以共用字段名称，但实际命令、证书链和结果要分平台保存，避免一份脚本把两类证据压成同一个结论。

材料提交完成后，接收方仍保留自己的验收责任。清单提供可核对的输入，不能代替接收方对签名身份、产物摘要和运行结果的独立判断。没有被实际核对的字段继续标为待验证，不随文件齐全自动通过。

• 是否已清楚告知接收方验证工具的局限性？
• 是否明确了构建代理与证书主体的潜在差异？
• 是否强调了清单提交不等于责任转移的原则？

加固交付材料提交清单与后续行动指南

最终提交材料应打包为可归档的压缩文件，包含加固后的 APK 或 AAB、单独导出的签名证书公钥部分、数字摘要文件以及构建证明文件。每个部分均需提供可单独验证的指纹，确保在解包后能立即进行独立校验，无需依赖外部查询。这种自包含的设计减少了对外部服务的依赖，提高了验证的可靠性和效率。

交付说明文档应明确签名责任主体、签名环境简述及证书有效期，但不包含任何私钥或授权凭据。接收方按说明在隔离环境中使用自检脚本或等效流程重新校验，用公钥验证一切。任何信息残缺都将导致接收方中断接受流程，直到补充完整且通过验证为止。完整性是信任建立的前提条件。

管理层应期望此清单在自动化管道中自动生成，并通过独立通道如已建立的公钥基础设施确认完整性，减少人为错误。长期维护中，证书轮换或签名环境变更都应反映在后续清单中，不可继续沿用旧证据，否则会造成信任链断裂。持续的更新和维护是保持供应链安全的关键环节。

• 所有材料均已包含且无缺漏，特别是构建证明和摘要？
• 证书不是自签名但符合组织 PKI 策略，且未过期？
• provenance 签名可信任链到根，且未被篡改？
• 交付说明文档是否清晰界定了责任边界和联系方式？