IPVIO Stream 应用内更新机制:GitHub Releases + SHA-256 校验与签名验证如何防篡改

原创2026-11-15 16:31:052,305 阅读

IPVIO Stream 应用内更新机制:GitHub Releases + SHA-256 校验与签名验证如何防篡改

IPVIO Stream 是一款免费、开源的 Android TV / Fire TV IPTV 播放器,自带从 GitHub Releases 拉取新版本的能力。由于它不经过应用商店分发,更新包存在被截断、损坏甚至被人为替换的风险。本文用大白话拆解:IPVIO Stream 是如何用 GitHub Releases + SHA-256 校验 + 签名验证 三道防线,在下载后、安装前拦截一切异常 APK 的。

IPVIO Stream 主界面与右上角更新通知铃铛

上图右上角的铃铛图标,就是更新通知的入口——发现新版本时它会亮起红点,点一下即可下载并安装。

📦 更新源:应用是如何找到新版本的?

更新检查逻辑集中在 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 本身并核对:

  1. 包名必须与当前应用一致(com.ipvio.stream),防止误装其他应用的文件;
  2. 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”,也可以在那里修改自定义更新地址或关闭自动检查:

IPVIO Stream 设置页面,关于应用与手动检查更新入口所在处

🧪 测试与文档:规则全部纯函数化

安全规则与 Android 系统调用被刻意拆开:所有判断(解析 manifest、哈希规范化与比对、版本比对、签名集合比对)都写在纯 Kotlin 对象 UpdateLogic(Round17Logic.kt)里,由 UpdateLogicTest.kt 的 15 个单元测试覆盖,包括空输入的已知 SHA-256 基准值、63/65 位非法哈希、密钥轮换历史匹配等边界。UpdateVerify 只负责“读 APK 这个文件”,规则改动时无需触碰 Android API。

📚 延伸阅读

🛡️ 一句话总结:哈希负责抓“坏的”,签名负责抓“假的”——两者叠加,才让一个不走应用商店的开源播放器,也能把更新链路上的篡改风险压到最低。

登录后查看全文
IPVIO-Stream