增量安装的 idsig 文件如何避免与发布 APK 错配

先给结论：APK 与 idsig 必须形成不可拆分的证据对

APK Signature Scheme v4 为增量安装场景生成独立 idsig。它不是可以按版本名称随意复用的通用签名文件，而是由具体 APK 内容与签名信息派生的伴随工件。发布系统必须把 apkSha256 与 idsigSha256 放进同一记录，并用候选标识锁定两者，不能只检查目录里是否存在同名后缀。

最小回执还要说明是谁、用哪个 apksigner 版本、基于哪个已签名 APK 生成，APK 内部 v2 或 v3 验证结果是什么，以及这对工件准备走哪条安装路径。idsig 单独存在只能证明流水线留下了一个文件，不能证明它属于当前候选，更不能替代 APK 的签名证书和更新身份。

门禁应以失败关闭为原则。APK 缺失、idsig 缺失、路径重复、摘要与批准清单不符、同一 idsig 被多个候选引用、生成后 APK 又被修改，任何一项都阻止进入增量安装步骤。修复动作是重新定位最终 APK、重新生成 idsig、重新验签和保存新回执，不是改文件名或覆盖摘要字段。

理解 v4 的职责：支持增量安装，不接管 APK 内部身份

AOSP 的 v4 方案说明 idsig 独立于 APK 保存，并用于支持增量安装所需的数据验证。其设计依赖配套的 v2 或 v3 签名，因此验收不能只运行一次 v4 生成命令。流水线要先确认 APK 内部签名方案和证书符合项目策略，再为该准确文件产生伴随 idsig。

v4 与 v1 的条目摘要模型、v2 或 v3 的 APK Signing Block 角色不同。idsig 的存在不意味着 APK 本体可以没有内部签名，也不意味着所有系统版本都走 v4 路径。报告应分开记录 v2、v3、v4 的 present、verified、failed 或 not-required 状态，并注明目标系统与安装方式。

把 idsig 称为发布包身份证会造成错误推论。Android 的更新身份仍建立在应用签名、applicationId、versionCode 和平台规则上；idsig 只是特定安装路径的伴随验证材料。即使 idsig 配对正确，包名、版本、证书、split 集合或用户设备状态不满足要求，安装与更新仍可能失败。

先冻结最终 APK，再生成 idsig 和成对摘要

流水线顺序必须固定为构建、必要后处理、对齐、内部签名、apksigner 验证、候选摘要冻结、v4 idsig 生成、成对摘要登记和安装验证。apksigner 文档明确签名后不能再修改 APK；任何注入、重压缩、资源改写或重新签名都会改变候选，旧 idsig 与旧验证输出同时失效。

生成任务要从内容寻址的候选位置读取 APK，而不是从 latest.apk、工作区通配符或可被覆盖的临时目录读取。输入路径在执行前解析为明确文件，记录文件大小和 SHA-256；生成完成后再次计算 APK 摘要，确认生成过程期间输入没有变化，再计算 idsig 摘要并原子写入配对清单。

原子性不是把两个文件放进同一目录就结束。配对清单应先写临时文件，包含完整摘要和工具回执，完成校验后一次重命名为正式状态；下游只能读取已完成记录。若进程中断留下 APK 或 idsig 单件，恢复逻辑应重新验证原始候选，而不是根据时间戳猜测哪两个文件属于同一轮。

文件名、时间戳和 versionName 都不能代替内容绑定

同名 APK 在重构建、重签名或渠道处理后可能拥有完全不同字节，idsig 文件名也可以被人工复制。仅比较 basename、mtime 或目录位置无法证明配对。门禁必须以加密摘要和不可变候选 ID 为权威，文件名只用于可读展示，时间戳只用于审计排序。

versionName 是面向用户的字符串，不能承担唯一性；versionCode 是平台更新判断的一部分，也不能区分同一版本码下的不同构建。配对记录应同时保存 applicationId、versionCode、artifactRole 和 APK 摘要，任何字段冲突都进入人工调查，不能因为版本号相同就复用 idsig。

重复使用检测至少覆盖两种情况：同一个 idsig 路径被多个候选记录引用，以及相同 idsig 摘要出现在不同 APK 摘要的记录中。前者往往是流水线覆盖或软链接错误，后者需要确认是否发生错误复用。门禁输出差异即可，不能直接写成攻击已发生或平台一定接受错误组合。

base、split 与安装会话需要逐项配对和整体约束

一个版本可能包含 base APK 与多个 split APK。PackageInstaller 对一次 split 安装会话要求包名、versionCode 和签名证书等保持一致。发布清单不能用 base 的 idsig 代表所有 split，也不能把测试设备只安装 base 的成功回执外推到完整配置集合。每个实际参与增量安装的 APK 都要有独立配对记录。

会话级门禁先逐项验证 apkSha256、idsigSha256 和内部签名，再验证集合约束，包括唯一 base、没有重复 split name、applicationId 一致、versionCode 一致、签名者符合策略以及所需配置完整。逐项都通过但集合混入另一个版本的 split，仍然必须失败。

如果商店服务在服务器端生成设备定向 split，本地上传工件与最终交付对象的角色不同。没有平台侧导出与抽样证据时，不能声称本地 idsig 覆盖了商店产生的所有对象。报告应明确 artifactRole 是本地测试、直接分发还是平台交付，并只对实际观察到的工件下结论。

更新验收还要核对包名、版本和签名身份

Android 更新要求新旧版本保持 applicationId，并满足兼容签名或轮换证明以及可接受的 versionCode。idsig 成对摘要不能替代这些条件。更新测试应先保存已安装基线的包名、版本与证书，再核对新候选内部签名，最后在目标系统上执行真实更新路径并记录结果。

apksigner 可以报告方案覆盖与证书信息，流水线应保存完整原始输出、工具版本、退出状态和 APK 摘要。只截取 verified 一行会丢失签名方案、警告和 signer 细节。v4 配对清单应引用这份内部签名回执的摘要，确保 idsig 没有被绑定到未经批准的测试证书候选。

证书轮换场景更不能靠文件名推断。项目要记录允许的当前证书、轮换历史、目标系统范围和旧版本升级路径。若更新失败，需要区分 idsig 错配、内部签名不兼容、版本条件、split 会话或设备策略，不能把所有错误都归因于加固或增量安装机制。

归档和缓存要使用内容地址，避免可变别名串包

发布存储应以 APK SHA-256 或不可变 release ID 组织对象，再在该对象下保存 idsig、验签回执和配对清单。latest、stable 或渠道名只作为指针，切换时必须指向完整不可变集合。下游任务拿到指针后立即解析为具体对象，不能在长任务中反复读取可能变化的别名。

缓存键至少包含 APK 摘要、apksigner 版本、v4 生成参数和签名身份策略版本。只按 versionCode 缓存 idsig 会在重复构建时返回旧工件；只按文件路径缓存会在原位覆盖后失效。缓存命中后仍应重算当前 APK 和 idsig 摘要，并与缓存记录比较。

回滚必须切换整个配对集合，而不是只恢复 APK。若历史 release 缺少 idsig 或内部签名回执，回滚到非增量安装路径并明确记录限制，不能临时拼接其他版本的伴随文件。生产事故中保持证据完整比追求复用速度更重要，否则后续无法判断设备实际收到哪一对工件。

用只读脚本生成 APK 与 idsig 的成对摘要清单

下面的 Python 示例读取一份公开安全的 pairs.json，逐条解析 APK 和 idsig 路径，拒绝缺失文件、重复路径、重复候选 ID、摘要预期不符和同一 idsig 摘要绑定不同 APK。它只读取文件并输出 JSON，不执行安装、签名、密钥访问或包内容提取，适合放在生成与发布之间。

输入清单中的 approved_apk_sha256 可以来自前一阶段冻结候选的不可变回执。脚本重新计算实际摘要，若不一致立即失败；输出包含路径名称、大小和双摘要，供后续工具版本、证书摘要与安装路径回执引用。真实流水线还应限制文件大小、固定根目录并验证清单签名或存储权限。

脚本通过只表示本次输入集合内没有发现所列配对差异，不代表 idsig 的内部语义、APK 签名、split 集合或设备安装已经通过。后续仍要运行 apksigner 验证，使用批准的增量安装工具链，并把真实命令输出绑定到相同 APK 摘要。

import hashlib
import json
import sys
from pathlib import Path

if len(sys.argv) != 2:
    raise SystemExit("usage: bind_idsig_pairs.py pairs.json")
manifest_path = Path(sys.argv[1]).resolve()
if not manifest_path.is_file():
    raise SystemExit(f"pair manifest missing: {manifest_path.name}")
with manifest_path.open("r", encoding="utf-8") as stream:
    requested_pairs = json.load(stream)
if not isinstance(requested_pairs, list) or not requested_pairs:
    raise SystemExit("pair manifest must be a non-empty JSON array")

def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as stream:
        for block in iter(lambda: stream.read(1024 * 1024), b""):
            digest.update(block)
    return digest.hexdigest()

seen_ids = set()
seen_paths = set()
idsig_bindings = {}
results = []
for index, item in enumerate(requested_pairs):
    if not isinstance(item, dict):
        raise SystemExit(f"pair {index} must be an object")
    candidate_id = str(item.get("candidate_id", "")).strip()
    apk_path = Path(str(item.get("apk", ""))).resolve()
    idsig_path = Path(str(item.get("idsig", ""))).resolve()
    if not candidate_id or candidate_id in seen_ids:
        raise SystemExit(f"missing or duplicate candidate_id at pair {index}")
    if apk_path == idsig_path or apk_path in seen_paths or idsig_path in seen_paths:
        raise SystemExit(f"reused artifact path at pair {index}")
    if not apk_path.is_file() or not idsig_path.is_file():
        raise SystemExit(f"missing APK or idsig at pair {index}")
    apk_sha256 = sha256_file(apk_path)
    idsig_sha256 = sha256_file(idsig_path)
    approved = str(item.get("approved_apk_sha256", "")).lower()
    if approved and approved != apk_sha256:
        raise SystemExit(f"APK digest differs from approval at pair {index}")
    previous_apk = idsig_bindings.get(idsig_sha256)
    if previous_apk is not None and previous_apk != apk_sha256:
        raise SystemExit(f"idsig digest is bound to different APKs at pair {index}")
    seen_ids.add(candidate_id)
    seen_paths.update((apk_path, idsig_path))
    idsig_bindings[idsig_sha256] = apk_sha256
    results.append({
        "candidate_id": candidate_id,
        "apk_name": apk_path.name,
        "apk_bytes": apk_path.stat().st_size,
        "apk_sha256": apk_sha256,
        "idsig_name": idsig_path.name,
        "idsig_bytes": idsig_path.stat().st_size,
        "idsig_sha256": idsig_sha256,
    })
print(json.dumps({"status": "paired", "pairs": results}, indent=2))

证据包和行动入口必须指向同一最终候选

NIST SP 800-218 SSDF 强调保留来源、构建、验证和变更证据。对应 v4 idsig，证据包应包含 APK 与 idsig 双摘要、apksigner 版本、生成命令参数、内部签名原始回执、证书摘要、构建来源、安装路径、目标设备和异常记录。所有材料通过同一候选 ID 关联。

公开报告必须区分事实、工程判断和限制。可以写某一 APK 与 idsig 的实际摘要、文件大小、生成工具与真实安装回执；不能从文件存在推导增量安装已成功，也不能把一次设备通过写成全平台兼容。没有项目证据时不提供客户、排名、流量、性能或攻击阻断数字。

整理候选前可先查看[APK 敏感调试资产清单](/zh-cn/articles/apk-sensitive-debug-asset-inventory/)，确认归档目录没有混入非发布工件。需要提交 APK 与配套安装材料，可从[御盾中央平台申请加固服务](https://www.leonadev.com/console/)。登录、注册、价格、购买和控制台操作统一由中央平台承接，提交前移除私钥、令牌和客户数据。

• 最终 APK 已冻结并记录 SHA-256 与字节数
• idsig 在 APK 内部签名验证后生成并记录 SHA-256
• 生成前后 APK 摘要一致，不存在并发后处理
• apksigner 版本、方案结果和证书摘要已保存
• 同一路径或 idsig 摘要没有绑定不同 APK 候选
• base 与每个实际 split 分别建立配对记录
• 包名、versionCode、签名身份和 artifactRole 一致
• 真实安装回执只覆盖已测试设备、系统和路径