このページでは、Android デバイスにインストールされている APK が、クレームモデルで行われたクレームに対応していることを確認するためのさまざまな方法について説明します。これには、問題の APK をデバイスから取得し、コードの整合性を確認して、抽出されたアーティファクトに対してログ包含証明を実行することが含まれます。
適格性の確認プロセス
透明性ログは、ハッシュで構成されるマークルツリーを使用して実装されます。リーフノードにはデータが含まれ、親ノードにはその子のハッシュが含まれます。
基本的に、透明性ログの改ざん検知プロパティを検証するために、マークルツリーで 2 つの計算(包含証明と整合性証明)が実行されます。前者は、ログに特定の APK バージョンに対応するエントリが含まれていることを証明します。ログエントリには、対応する APK から取得できる JSON Web Token(JWT)形式のコード署名トークンの SHA256 ダイジェストであるハッシュが含まれています。後者は、新しいエントリがツリーに追加されると、新しいチェックポイントが(暗号的に)以前のバージョンのツリーと整合していることを証明します。
対象となる APK を検証するには、監視対象のチェックポイントに基づいて包含証明テストを実行します。このログは、標準化されたウィットネス プロトコルを使用して、公開ウィットネス ネットワークと統合する予定です。これにより、ログの一貫性を保証する、監視されたチェックポイントが提供されます。
デバイス上の APK が、申立人モデルで作成されたクレームに準拠していることを確認するには、以下の説明をご覧ください。
包含証明
Android ユーザーは、まず APK とその関連メタデータを抽出し、再計算したルートハッシュを公開されたチェックポイントに含まれるルートハッシュと比較することで、デバイス上の対象 APK がログに記録されていることを確認できます。一致する場合、Android ユーザーは脅威モデルに記載されている保護機能の一部を確実に利用できます。
APK がログに含まれていることを確認する方法
前述のように、現在対象となっている APK のリストは、概要ページに記載されています。
認定の前提条件
アーティファクト(ファームウェアまたは APK)がクレームに準拠していることを確認する前に、ネットワークに接続されたパソコンで次のツールが利用可能であることを確認してください。確認対象によっては、すべてが必要になるとは限りません。
Golang
検証ツールは Go で記述されています。ビルドするには、Go サイトから Go 1.24 以降をインストールします。
Android Debug Bridge(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 Asset Packaging Tool)は、Android アプリのリソースのコンパイルとパッケージ化に使用されるビルドツールです。Android SDK Build Tools バージョン 26.0.2 以降では、スタンドアロン ツールとして使用できます。
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 は、Google Pixel の bootloader.img 内の個々のコンポーネントを解凍するために使用される Python スクリプトです。APK を検証する場合は、この操作は必要ありません。このツールは、avbtool.py が検証に必要なイメージを検出できるようにするために重要です。
fbpacktool には、Python 3.6 以降と PyYAML パッケージ(python3 -m pip install pyyaml など)が必要です。
このツールを使用するには、次の 6 つの Python スクリプトを avbtool.py が存在するディレクトリにダウンロードし、fbpacktool.py を実行可能にして、便宜上 fbpacktool.py への fbpacktool という名前のシンボリック リンクを作成する必要があります。
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 が Google の主張に沿っていることを確認するには、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 がデバイスにインストールされている場合、上記のコマンドは、デバイスにインストールされている場所を示すパスを返します。それ以外の場合、出力は表示されません。
次に、次のコマンドを使用して、Android デバイスから作業中のパソコンに APK をダウンロードします(デバイス上の実際の場所と 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 内のコード透明性署名を検索します。これは、APK から抽出された他のファイルとともに META-INF フォルダに含まれる code_transparency_signed.jwt という名前のファイルです。
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(そうでない場合)。