IPVIO Stream 应用内更新机制:GitHub Releases + SHA-256 校验与签名验证如何防篡改
IPVIO Stream 应用内更新机制:GitHub Releases + SHA-256 校验与签名验证如何防篡改
IPVIO Stream 是一款免费、开源的 Android TV / Fire TV IPTV 播放器,自带从 GitHub Releases 拉取新版本的能力。由于它不经过应用商店分发,更新包存在被截断、损坏甚至被人为替换的风险。本文用大白话拆解:IPVIO Stream 是如何用 GitHub Releases + SHA-256 校验 + 签名验证 三道防线,在下载后、安装前拦截一切异常 APK 的。
上图右上角的铃铛图标,就是更新通知的入口——发现新版本时它会亮起红点,点一下即可下载并安装。
📦 更新源:应用是如何找到新版本的?
更新检查逻辑集中在 AppUpdate.kt 中,数据源有三级优先顺序:
| 优先级 | 数据源 | 特点 |
|---|---|---|
| 1️⃣ | 最新 Release 附带的 update.json |
包含 sha256 哈希,严格模式:没有哈希视为不完整 |
| 2️⃣ | GitHub Releases API(最新版本元数据) | 自动从附件中挑选 IPVIO-Stream.apk,无哈希 |
| 3️⃣ | 用户自定义地址(设置中可填) | 可指向自己的 JSON,sha256 可选 |
update.json 的字段在 docs/RELEASE.md 中有完整说明:
| 字段 | 含义 |
|---|---|
versionCode |
必须与该 APK 的版本号一致,不一致直接拒装 |
versionName |
展示给用户的版本号 |
apk |
APK 文件名或完整 https 地址 |
sha256 |
64 位十六进制哈希,内置数据源必填 |
minSupportedCode |
低于该版本的用户将被强制更新 |
mandatory |
true 时所有用户不可推迟此更新 |
notes |
更新说明,最多 300 字符 |
检查频率被刻意压低以节省配额:autoCheck 每天静默检查一次;startCheck 每次启动时检查,但最快也要间隔 10 分钟。出错时(断网、源不可达)通知完全不可见,不会打扰用户。
🔐 三道防线:安装前的深度体检
下载完成后、打开系统安装器之前,downloadAndInstall 会先调用 UpdateVerify.check 做完整体检。任何一项不过,文件立即删除并向用户显示清晰的中文场景错误说明,而不是 Android 那句莫名其妙的“App not installed”。
第一道防线:SHA-256 校验和(防损坏、防下载中断)
下载过程在 download 中完成,有两个细节值得注意:
- 边写边算:每读入一个 64 KB 缓冲区就同步喂给
MessageDigest("SHA-256"),无需二次遍历整个 APK,下载结束即得到摘要; - 完整性双保险:若服务器声明了内容长度,实际写入字节数与之不符直接判定“下载不完整”;随后再将实际摘要与
update.json中的sha256比对。
哈希比对前会先经过 normalizeSha 规范化:统一转小写、剔除空格(兼容旧版 certutil 输出带空格的格式),且必须是 64 位 0-9a-f,否则视为格式非法。
💡 需要清醒的一点:
update.json和 APK 来自同一个 Release,所以哈希只能发现损坏或传输错误的文件,无法防住“整个 Release 被替换”的情况——真正的防篡改靠下一道防线。这也是 docs/SECURITY.md 第 11 项明确写下的结论。
第二道防线:包名与版本号核对(防装错 App、防回退)
UpdateVerify 会解析 APK 本身并核对:
- 包名必须与当前应用一致(
com.ipvio.stream),防止误装其他应用的文件; - versionCode 必须高于已安装版本,且与
update.json中宣告的值相等(若宣告了)。规则由纯函数 versionProblem 实现:不相等报CODE_MISMATCH,不更新报NOT_NEWER。
第三道防线:签名者证书验证(防换 Key 替换 APK)
这是最核心的一道。Android 只在新旧应用用同一把密钥签名时才允许覆盖安装(历史记录、收藏、设置才能保留)。signersOf 读取两个 APK 的签名证书并各自计算 SHA-256 摘要,然后交给 sameSigners 判断:
- 新旧签名集合完全相等 → 通过;
- 新 APK 采用了密钥轮换(API 28+):已安装应用的签名出现在新 APK 的签名历史(history)中 → 通过;
- 读不到任何签名(空集合)永不匹配 → 拒绝,宁可错杀。
兼容性方面,API 28+ 使用 GET_SIGNING_CERTIFICATES 读取含历史证书的 SigningInfo,低版本回退到 GET_SIGNATURES(UpdateVerify.kt L26)。
用户点击"现在更新"
│
▼
下载 APK ──► 边写边算 SHA-256
│
├─ 字节数不符 ──► ❌ "下载不完整"
├─ 哈希不符 ──► ❌ "校验和不匹配(文件损坏或被篡改)"
▼
UpdateVerify 体检
├─ 非 APK 文件 ──► ❌ 清晰提示
├─ 包名不对 ──► ❌ "该文件属于另一个应用"
├─ 版本号不符/未更新 ──► ❌ 清晰提示
├─ 签名不一致 ──► ❌ "签名与已安装应用不匹配……"
▼ ✅ 全部通过
系统安装器打开(保留数据覆盖安装)
⚙️ 用户视角:强制更新与设置入口
当 update.json 标记 mandatory: true,或已安装版本号低于 minSupportedCode 时,isRequired 判定为强制更新。此时 UpdatePrompt 会显示“此更新是必需的”,并隐藏“稍后”按钮——但按返回键仍可关闭对话框,保证断网用户永远不会被锁死。首次启动时底部还会出现一张非阻塞的更新卡片(UpdateCard.kt),不抢占焦点。
手动检查更新的入口在“设置 → 关于 IPVIO Stream”,也可以在那里修改自定义更新地址或关闭自动检查:
🧪 测试与文档:规则全部纯函数化
安全规则与 Android 系统调用被刻意拆开:所有判断(解析 manifest、哈希规范化与比对、版本比对、签名集合比对)都写在纯 Kotlin 对象 UpdateLogic(Round17Logic.kt)里,由 UpdateLogicTest.kt 的 15 个单元测试覆盖,包括空输入的已知 SHA-256 基准值、63/65 位非法哈希、密钥轮换历史匹配等边界。UpdateVerify 只负责“读 APK 这个文件”,规则改动时无需触碰 Android API。
📚 延伸阅读
- 发布流程(含 Windows 下用
certutil计算哈希的步骤):docs/RELEASE.md - 安全审计第 11 项(更新机制现状与限制):docs/SECURITY.md
- T-015 任务全记录(设计决策、验收标准、设备测试清单):docs/tasks/T-015-harden-update.md
- 核心源码:AppUpdate.kt · UpdateVerify.kt · UpdatePrompt.kt
🛡️ 一句话总结:哈希负责抓“坏的”,签名负责抓“假的”——两者叠加,才让一个不走应用商店的开源播放器,也能把更新链路上的篡改风险压到最低。

