> [!NOTE]
> **Note:** This guide applies to verifying historical entries in the archived Google System Services APK Code Transparency Log. For verifying active releases, refer to the [Google Product Application Transparency Verification
> Guide](https://developers.google.com/android/binary_transparency/google_apk/verification_details).

This page outlines various methods to ensure that the APK that is installed on
your Android device corresponds to the claim that was made in the
[Claimant Model](https://developers.google.com/android/binary_transparency/google1p/overview.md.txt#claimant_model). This involves pulling the APK in
question from your device, checking its code integrity, and performing a log
inclusion proof on the extracted artifact.

## Verification Process

A transparency log is implemented with a Merkle tree consisting of hashes.
A leaf node contains data, and a parent node contains the hash of its children.

Basically, two computations are performed on the Merkle tree to verify the
tamper-evident property of transparency logs: the inclusion proof and
consistency proof. The former proves that the log includes an entry
corresponding to a particular APK version. The log entry includes a hash, which
is the SHA256 digest of the code signature token in the form of a JSON Web Token
(JWT), which can be obtained from corresponding APKs. The latter proves that
when new entries are added to the tree, the new checkpoint is
(cryptographically) consistent with the previous version of the tree.

To verify a covered APK, perform an inclusion proof test based on a witnessed
checkpoint.
Note that we are planning to integrate this log with a public witness network
using a standardized
[witness protocol](https://github.com/C2SP/C2SP/blob/main/tlog-witness.md).
This will provide a witnessed checkpoint, which guarantees the consistency of
the log.

If you want to convince yourself that the APK you have on your device conforms
to the claim that is made in the claimant model, refer to the write-up below.

### Inclusion Proof

An Android user can check that a covered APK on their device is in the log by
first extracting the APK and its relevant metadata, then comparing their
recomputed root hash with the root hash contained in the published checkpoint.
If they match, then the Android user can be assured of some protections
described in the Threat Model.

## How to Verify an APK Inclusion In Log

As described earlier, the list of APKs that are currently covered can be found
listed in the [Overview page](https://developers.google.com/android/binary_transparency/google1p/overview.md.txt).

### Verification Prerequisites

Before proceeding to verify that the artifact (firmware or APK) is in accordance
with the claim, ensure that the following tools are available on a
network-connected computer.
Depending on the verification target, you might not need all of them.

#### Golang

The [verification tool](https://github.com/android/android-binary-transparency/tree/main/verifier_tools/verify)
is written in Go. To build it, install Go 1.24 or later
from the [Go site](https://go.dev/doc/install).

#### Android Debug Bridge (ADB)

`ADB` is a tool that communicates with an Android device to inspect the image or
extract APKs, available on the Android SDK Platform Tools [website](https://developer.android.com/tools/releases/platform-tools).

#### Inclusion Proof verifier

The inclusion proof verifier is a Go module that queries the transparency log
and outputs whether an artifact is included in the log.
It's published in the `android-binary-transparency` GitHub repository at
<https://github.com/android/android-binary-transparency/tree/main>

To clone the AOSP `avb` repository:

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

To clone the `android-binary-transparency` GitHub repository:

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

#### AAPT2

AAPT2 (Android Asset Packaging Tool) is a build tool used to compile and package
an Android app's resources.
It can be found as a standalone tool in [Android SDK Build Tools](https://developer.android.com/studio/releases/build-tools)
version 26.0.2 and higher.

#### bundletool

`bundletool` is a tool used to build an Android App Bundle (AAB). It can also be
used to verify APK code signatures.
It can be downloaded from [GitHub](https://github.com/google/bundletool/releases).

#### wget or curl

[wget](https://www.gnu.org/software/wget/) and
[curl](https://curl.se/download.html)
are tools that can be used to retrieve or download files from the Internet.
Be sure to have either of these tools installed, as the verification scripts may
rely on them.

#### Avbtool

[avbtool](https://android.googlesource.com/platform/external/avb/+/master/avbtool.py)
is used to compute the VBMeta digest of the factory images and verification of
binaries.
After cloning the `avb` repository (as shown in the Inclusion Proof verifier
section), `avbtool.py` can be found within the cloned `avb` directory.
You should add this directory to your `$PATH` environment variable.

    computer:\~$ PATH=$PATH:DIRECTORY_CONTAINING_AVBTOOL

#### Fbpacktool

[fbpacktool](https://developers.google.com/android/binary_transparency/tools/pixel/fbpacktool/fbpacktool.py)
is a Python script used to unpack individual components in Pixel's
`bootloader.img`.
You don't need this if you are verifying APKs.
This tool is important because it lets `avbtool.py` discover the required
images for verification.

`fbpacktool` requires Python 3.6 or later and the
[PyYAML](https://pypi.org/project/PyYAML/) package
(for example, `python3 -m pip install pyyaml`).

To make use of this tool, you should download the following six python scripts
into the directory where your `avbtool.py` lives,
make `fbpacktool.py` executable,
and create a symlink named `fbpacktool` to `fbpacktool.py` for convenience.

If you have `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

If you have `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](https://www.openssl.org/source/) helps perform various cryptographic
operations using the terminal in the verification workflow.
Make sure it's installed on your system.
You can check on your terminal by running the following command and making sure
the returned result isn't empty:

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

### Construct a Payload for Verification

To verify that the APK you extracted from your device according to our claims,
you must construct a log payload from information derived from the APK.

Before you begin, make sure that `adb` can be used on your device by
[enabling adb debugging](https://developer.android.com/tools/adb#Enabling) on
your device.

Then, locate where the APK is installed on your device. For the purposes of this
guide, we will make use of the
[Android System Key Verifier](https://developers.google.com/android/binary_transparency/google1p/overview.md.txt#android_system_key_verifier) APK
(com.google.android.contactkeys) as our working example.

    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

If the Android System Key Verifier APK is installed on your device,
the command above will return
a path indicating where it is installed on your device.
Else, you **won't** see any output.

Then, download the APK from your Android device onto the computer you are
working using this command (note that the actual location and the APK filename
on your device may vary):

    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

To obtain and thus verify the package name of the APK you have just downloaded,
you will need to first unzip the APK, as an APK is ultimately a special kind of
ZIP file.

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

This step unpacks all the files that made up the APK. The package name and
version can be found in the
[manifest](https://developer.android.com/guide/topics/manifest/manifest-intro)
of the APK, which is usually in a file named `AndroidManifest.xml`.

However, the obtained manifest file is in a binary form, which is not human
readable.
In order to convert the binary XML into a human readable form, we make
use of the `aapt2` tool installed earlier (as required to be installed in the
[prerequisite](https://developers.google.com/android/binary_transparency/google1p/verification_details.md.txt#aapt2)) section.

    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'

From the output above, we now can be sure that this APK's package name is
`com.google.android.contactkeys` and the version number (versionCode) is `1413`.

Now, we will search for the code transparency signature within the APK. It
should be a file named `code_transparency_signed.jwt` contained within the
`META-INF` folder amongst the other extracted files from the APK.

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

With this hash string, we now have every piece of information needed to piece
together a log payload according to the format described in the
[Log Content section](https://developers.google.com/android/binary_transparency/google1p/overview.md.txt#log_content). In this example, a corresponding
log payload should look like the following:

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

Also note the newline character after the package version.

You can save the content into a file, such as `payload.txt`. This will come in
handy when doing inclusion proof test later.

### Verify the Authenticity of APK Code Signature

Now, we should verify the authenticity of the code signature token
embedded within the APK. To do so, we make use of `bundletool` and the public
key of the key pair that has been used to sign it in the first place. They are
[published](https://developers.google.com/android/binary_transparency/google1p/overview.md.txt#covered_packages) within each section of the respective
APKs. Assuming that you have saved the public key certificate
(e.g. for [Android System Key Verifier](https://developers.google.com/android/binary_transparency/google1p/overview.md.txt#android_system_key_verifier))
into a file named `signing_cert_pubkey.pem`,
follow the guide below to perform code signature verification.

First, you should create a zip archive and add the candidate APK into the zip
archive.

    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

We are now ready to make use of `bundletool`'s `check-transparency` command to
verify if the code signature embedded within the candidate APK matches the one
that is published.

    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.

You should make sure that the output of the command above states that both the
*code transparency signature* and the *code transparency* are
verified.
If they are not, for example, if you are seeing output such as
`Code transparency verification failed because the provided public key
certificate does not match the transparency file`,
this means the code integrity of the APK in question may potentially be
compromised and you should **not** trust the APK.
Remember to double check that you are verifying them against the correct public
key certificate.
Otherwise, if everything else checks out, this signifies that the authenticity
of the code signature is verified for the APK you are validating.

### Verifying Package Inclusion (Inclusion Proof)

Using the payload that you have constructed
[earlier](https://developers.google.com/android/binary_transparency/google1p/verification_details.md.txt#construct_a_payload_for_verification), you are now ready to test if
the package in question has been included in the transparency log.

An inclusion proof tool has been published in the `avb` [repository](https://android.googlesource.com/platform/external/avb/+/refs/heads/main/tools/transparency/verify/) within
the Android Open Source Project. To run it:

    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

The verifier uses the corresponding checkpoint and the log contents (found at
the [tile directory](https://developers.google.com/android/binary_transparency/tile.md.txt)) to check that your APK payload is in the transparency
log, verifying that it is indeed published by Google.

The output of the command is written to stdout:

- `OK. inclusion check success!` if the package's code is included in the log,
- `FAILURE` if it isn't.