Google 系统服务 APK 透明度完整验证

本页概述了各种方法,以确保 Android 设备上安装的 APK 与版权主张方模型中的版权主张相对应。这涉及从设备中提取相关 APK、检查其代码完整性,并对提取的工件执行日志包含证明。

验证流程

透明度日志通过由哈希组成的 Merkle 树实现。 叶节点包含数据,父节点包含其子节点的哈希。

基本上,系统会对 Merkle 树执行两项计算,以验证透明度日志的防篡改属性:包含证明和一致性证明。前者证明日志包含与特定 APK 版本对应的条目。日志条目包含一个哈希值,该哈希值是代码签名令牌的 SHA256 摘要,采用 JSON Web 令牌 (JWT) 的形式,可从相应的 APK 中获取。后者证明,当向树中添加新条目时,新检查点与树的先前版本(以加密方式)一致。

如需验证涵盖的 APK,请根据见证检查点执行包含证明测试。 请注意,我们计划使用标准化的见证人协议将此日志与公共见证人网络集成。 这将提供一个见证检查点,以保证日志的一致性。

如果您想确信设备上的 APK 符合版权主张方模型中的声明,请参阅以下说明。

包含证明

Android 用户可以先提取 APK 及其相关元数据,然后将重新计算的根哈希与已发布检查点中包含的根哈希进行比较,从而检查其设备上受涵盖的 APK 是否在日志中。如果匹配,则 Android 用户可以确信,他们会受到威胁模型中所述的一些保护。

如何验证 APK 是否已包含在日志中

如前所述,您可以在“概览”页面中找到当前涵盖的 APK 列表。

通过验证需要满足的前提条件

在继续验证制品(固件或 APK)是否符合声明之前,请确保联网计算机上提供了以下工具。 您可能不需要全部提供,具体取决于验证目标。

Go 语言

验证工具是用 Go 编写的。如需构建该工具,请从 Go 网站安装 Go 1.24 或更高版本。

Android 调试桥 (ADB)

ADB 是一款可与 Android 设备通信以检查映像或提取 APK 的工具,可在 Android SDK 平台工具网站上找到。

包含证明验证器

包含证明验证程序是一个 Go 模块,用于查询透明度日志并输出制品是否包含在日志中。该工具已发布在 android-binary-transparency GitHub 代码库中,网址为 https://github.com/android/android-binary-transparency/tree/main

如需克隆 AOSP avb 代码库,请运行以下命令:

computer:~$ git clone https://android.googlesource.com/platform/external/avb

如需克隆 android-binary-transparency GitHub 代码库,请运行以下命令:

computer:~$ git clone https://github.com/android/android-binary-transparency

AAPT2

AAPT2(Android 资源打包工具)是一种构建工具,用于编译和打包 Android 应用的资源。您可以在 Android SDK Build Tools 26.0.2 及更高版本中找到作为独立工具提供的 AAPT2。

bundletool

bundletool 是用于构建 Android App Bundle (AAB) 的工具。它还可用于验证 APK 代码签名。 您可以从 GitHub 下载该工具。

wget 或 curl

wget 和 curl 是可用于从互联网检索或下载文件的工具。请务必安装其中一个工具,因为验证脚本可能依赖于它们。

Avbtool

avbtool 用于计算出厂映像的 VBMeta 摘要和验证二进制文件。克隆 avb 代码库(如“包含证明验证程序”部分所示)后,您可以在克隆的 avb 目录中找到 avbtool.py。您应将此目录添加到 $PATH 环境变量中。

computer:~$ PATH=$PATH:DIRECTORY_CONTAINING_AVBTOOL

Fbpacktool

fbpacktool 是一个 Python 脚本,用于解压缩 Pixel 的 bootloader.img 中的各个组件。如果您要验证 APK,则不需要此文件。 此工具非常重要,因为它可让 avbtool.py 发现所需的映像以进行验证。

fbpacktool 需要 Python 3.6 或更高版本以及 PyYAML 软件包(例如 python3 -m pip install pyyaml)。

如需使用此工具,您应将以下 6 个 Python 脚本下载到 avbtool.py 所在的目录中,使 fbpacktool.py 可执行,并为方便起见,创建一个名为 fbpacktool 的符号链接,指向 fbpacktool.py。

如果您有 wget:

computer:dir_to_avbtool$ wget https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/fbpacktool.py \
https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/fbpack.py \
https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/packedstruct.py \
https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/xmlparser.py \
https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/xmlserializer.py \
https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/yamlparser.py
computer:dir_to_avbtool$ chmod +x fbpacktool.py
computer:dir_to_avbtool$ ln -s fbpacktool.py fbpacktool

如果您有 curl:

computer:dir_to_avbtool$ curl -LO https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/fbpacktool.py
computer:dir_to_avbtool$ curl -LO https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/fbpack.py
computer:dir_to_avbtool$ curl -LO https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/packedstruct.py
computer:dir_to_avbtool$ curl -LO https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/xmlparser.py
computer:dir_to_avbtool$ curl -LO https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/xmlserializer.py
computer:dir_to_avbtool$ curl -LO https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/yamlparser.py
computer:dir_to_avbtool$ chmod +x fbpacktool.py
computer:dir_to_avbtool$ ln -s fbpacktool.py fbpacktool

OpenSSL

openssl 有助于在验证工作流中使用终端执行各种加密操作。请确保您的系统上已安装该工具。 您可以在终端上运行以下命令,并确保返回的结果不为空:

computer:~$ which openssl
/usr/bin/openssl

构建用于验证的载荷

如需验证您根据我们的声明从设备中提取的 APK,您必须根据从 APK 派生的信息构建日志载荷。

开始之前,请在设备上启用 adb 调试,确保 adb 可以在您的设备上使用。

然后,在设备上找到 APK 的安装位置。在本指南中,我们将使用 Android System Key Verifier APK (com.google.android.contactkeys) 作为工作示例。

computer:~$ adb shell pm list packages -f | grep contactkeys
package:/data/app/~~i5WYSO4PuAAv798-eHdM7A==/com.google.android.contactkeys-PQCKjnn7xDqjeVhcUDibBA==/base.apk=com.google.android.contactkeys

如果您的设备上安装了 Android System Key Verifier APK,上述命令将返回一个路径,指明其在设备上的安装位置。 否则,您不会看到任何输出。

然后,使用以下命令将 APK 从 Android 设备下载到您正在使用的计算机上(请注意,设备上的实际位置和 APK 文件名可能会有所不同):

computer:~$ mkdir -p /tmp/testdir && cd /tmp/testdir
computer:/tmp/testdir$ adb pull /data/app/~~i5WYSO4PuAAv798-eHdM7A==/com.google.android.contactkeys-PQCKjnn7xDqjeVhcUDibBA==/base.apk ./contactkeys_candidate.apk

如需获取并验证您刚刚下载的 APK 的软件包名称,您需要先解压缩该 APK,因为 APK 最终是一种特殊的 ZIP 文件。

computer:/tmp/testdir$ mkdir extracted && unzip contactkeys_candidate.apk -d extracted/

此步骤会解压构成 APK 的所有文件。软件包名称和版本可在 APK 的清单中找到,该清单通常位于名为 AndroidManifest.xml 的文件中。

不过,获取的清单文件采用二进制格式,人类无法读取。 为了将二进制 XML 转换为人类可读的形式,我们使用了之前安装的 aapt2 工具(根据前提条件部分的要求进行安装)。

computer:/tmp/testdir$ aapt2 dump badging ./contactkeys_candidate.apk
package: name='com.google.android.contactkeys' versionCode='7805' versionName='1.219.791156583' platformBuildVersionName='Baklava' platformBuildVersionCode='36' compileSdkVersion='36' compileSdkVersionCodename='Baklava'

从上面的输出中,我们现在可以确定此 APK 的软件包名称为 com.google.android.contactkeys,版本号 (versionCode) 为 1413。

现在,我们将在 APK 中搜索代码公开透明签名。它应该是 META-INF 文件夹中名为 code_transparency_signed.jwt 的文件,位于从 APK 中提取的其他文件之间。

computer:/tmp/testdir$ sha256sum extracted/META-INF/code_transparency_signed.jwt
1779a2aee029112c2c9bfc9390b9678f3e5f4595b39705e8528dd522e8042f11  code_transparency_signed.jwt

有了这个哈希字符串,我们现在就有了根据日志内容部分中所述格式拼凑日志载荷所需的每条信息。在此示例中,相应的日志载荷应如下所示:

1779a2aee029112c2c9bfc9390b9678f3e5f4595b39705e8528dd522e8042f11
SHA256(Signed Code Transparency JWT)
com.google.android.contactkeys
1143

另请注意软件包版本后面的换行符。

您可以将内容保存到文件中,例如 payload.txt。这在稍后进行包含证明测试时会派上用场。

验证 APK 代码签名的真实性

现在,我们应该验证 APK 中嵌入的代码签名令牌的真实性。为此,我们使用 bundletool 以及最初用于对其进行签名的密钥对的公钥。它们在相应 APK 的每个部分中发布。假设您已将公钥证书(例如 Android System Key Verifier 的公钥证书)保存到名为 signing_cert_pubkey.pem 的文件中,请按照以下指南执行代码签名验证。

首先,您应创建一个 ZIP 归档文件,并将候选 APK 添加到该 ZIP 归档文件中。

computer:/tmp/testdir$ zip -u test.zip contactkeys_candidate.apk
        zip warning: test.zip not found or empty
  adding: contactkeys_candidate.apk (deflated 58%)

computer:/tmp/testdir$ file test.zip
test.zip: Zip archive data, at least v2.0 to extract, compression method=deflate

现在,我们可以使用 bundletool 的 check-transparency 命令来验证候选 APK 中嵌入的代码签名是否与已发布的签名匹配。

computer:/tmp/testdir$ java -jar BUNDLETOOL_INSTALL_PATH/bundletool-all-version.jar check-transparency \
  --mode=apk \
  --apk-zip=test.zip \
  --transparency-key-certificate=signing_cert_pubkey.pem

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): D9 E1 73 5B 2A 39 51 27 3A 87 35 B7 66 9E F1 9E F5 3A F1 C1 27 5C BA 31 39 3C 18 40 8B 03 79 D0
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.

您应确保上述命令的输出表明代码公开透明签名和代码公开透明均已通过验证。 如果未显示,例如,如果您看到 Code transparency verification failed because the provided public key certificate does not match the transparency file 等输出,则表示相关 APK 的代码完整性可能已遭到破坏,您不应信任该 APK。请务必仔细检查,确保您是根据正确的公钥证书验证这些签名。否则,如果其他所有内容都通过了检查,则表示您正在验证的 APK 的代码签名真实性已通过验证。

验证软件包是否包含在内(包含证明)

使用您之前构建的载荷,您现在可以测试相关软件包是否已包含在透明度日志中。

Android 开源项目中的 avb 代码库内已发布一个包含证明工具。如需运行该脚本,请执行以下操作:

computer:external/avb/tools/transparency/verify$ PAYLOAD_PATH=PATH_TO_PAYLOAD_DIR/payload.txt
computer:external/avb/tools/transparency/verify$ go build cmd/verifier/verifier.go
computer:external/avb/tools/transparency/verify$ ./verifier --payload_path=${PAYLOAD_PATH} --log_type=google_1p_code

验证方会使用相应的检查点和日志内容(位于图块目录中)来检查您的 APK 载荷是否在公开透明日志中,从而验证该载荷是否确实由 Google 发布。

该命令的输出会写入 stdout:

  • OK. inclusion check success!(如果日志中包含软件包的代码),
  • 如果不是,则为 FAILURE。