Verificação completa de transparência do APK dos serviços do sistema do Google

Nesta página, descrevemos vários métodos para garantir que o APK instalado no dispositivo Android corresponda à declaração feita no Modelo de Reclamante. Isso envolve extrair o APK em questão do dispositivo, verificar a integridade do código e realizar uma prova de inclusão de registro no artefato extraído.

Processo de verificação

Um registro de transparência é implementado com uma árvore de Merkle que consiste em hashes. Um nó folha contém dados, e um nó pai contém o hash dos filhos.

Basicamente, duas computações são realizadas na árvore de Merkle para verificar a propriedade de inviolabilidade dos registros de transparência: a prova de inclusão e a prova de consistência. A primeira prova que o registro inclui uma entrada correspondente a uma versão específica do APK. A entrada de registro inclui um hash, que é o resumo SHA256 do token de assinatura de código na forma de um JSON Web Token (JWT), que pode ser obtido nos APKs correspondentes. A última prova que, quando novas entradas são adicionadas à árvore, o novo checkpoint é (criptograficamente) consistente com a versão anterior da árvore.

Para verificar um APK coberto, faça um teste de prova de inclusão com base em um checkpoint testemunhado. Planejamos integrar esse registro a uma rede de testemunhas pública usando um protocolo de testemunha padronizado. Isso vai fornecer um checkpoint testemunhado, que garante a consistência do registro.

Se você quiser confirmar que o APK no seu dispositivo está em conformidade com a declaração feita no modelo de requerente, consulte o texto abaixo.

Comprovação de inclusão

Um usuário do Android pode verificar se um APK coberto no dispositivo está no registro. Para isso, primeiro ele extrai o APK e os metadados relevantes e, em seguida, compara o hash raiz recalculado com o hash raiz contido no checkpoint publicado. Se houver correspondência, o usuário do Android poderá ter certeza de que algumas proteções descritas no modelo de ameaças estão em vigor.

Como verificar a inclusão de um APK no registro

Como descrito anteriormente, a lista de APKs cobertos no momento pode ser encontrada na página de visão geral.

Pré-requisitos de verificação

Antes de verificar se o artefato (firmware ou APK) está de acordo com a declaração, confira se as ferramentas a seguir estão disponíveis em um computador conectado à rede. Dependendo do destino da verificação, talvez você não precise de todos eles.

Golang

A ferramenta de verificação é escrita em Go. Para criá-la, instale o Go 1.24 ou mais recente no site do Go.

Android Debug Bridge

O ADB é uma ferramenta que se comunica com um dispositivo Android para inspecionar a imagem ou extrair APKs, disponível no site do SDK do Android Platform-Tools.

Verificador de prova de inclusão

O verificador de prova de inclusão é um módulo do Go que consulta o registro de transparência e informa se um artefato está incluído no registro. Ele é publicado no repositório do GitHub android-binary-transparency em https://github.com/android/android-binary-transparency/tree/main.

Para clonar o repositório avb do AOSP:

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

Para clonar o repositório do GitHub android-binary-transparency:

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

AAPT2

O AAPT2 (Android Asset Packaging Tool) é uma ferramenta de build usada para compilar e empacotar os recursos de um app Android. Ele pode ser encontrado como uma ferramenta independente no Android SDK Build Tools, versão 26.0.2 e mais recentes.

bundletool

bundletool é uma ferramenta usada para criar um Android App Bundle (AAB). Ela também pode ser usada para verificar assinaturas de código de APK. Ele pode ser baixado no GitHub.

wget ou curl

wget e curl são ferramentas que podem ser usadas para recuperar ou baixar arquivos da Internet. Instale uma dessas ferramentas, já que os scripts de verificação podem depender delas.

Avbtool

A avbtool é usada para calcular o resumo do VBMeta das imagens de fábrica e a verificação de binários. Depois de clonar o repositório avb (conforme mostrado na seção "Verificador de prova de inclusão"), avbtool.py pode ser encontrado no diretório avb clonado. Adicione esse diretório à variável de ambiente $PATH.

computer:~$ PATH=$PATH:DIRECTORY_CONTAINING_AVBTOOL

Fbpacktool

fbpacktool é um script Python usado para descompactar componentes individuais no bootloader.img do Pixel. Isso não é necessário se você estiver verificando APKs. Essa ferramenta é importante porque permite que o avbtool.py descubra as imagens necessárias para verificação.

O fbpacktool requer o Python 3.6 ou mais recente e o pacote PyYAML (por exemplo, python3 -m pip install pyyaml).

Para usar essa ferramenta, faça o download dos seis scripts Python a seguir no diretório em que o avbtool.py está, torne o fbpacktool.py executável e crie um link simbólico chamado fbpacktool para fbpacktool.py para facilitar.

Se você tiver 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

Se você tiver 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

O openssl ajuda a realizar várias operações criptográficas usando o terminal no fluxo de trabalho de verificação. Verifique se ele está instalado no seu sistema. Para verificar no terminal, execute o seguinte comando e confira se o resultado retornado não está vazio:

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

Criar um payload para verificação

Para verificar se o APK extraído do dispositivo está de acordo com nossas declarações, é necessário criar um payload de registro com base nas informações derivadas do APK.

Antes de começar, verifique se o adb pode ser usado no seu dispositivo ativando a depuração do adb nele.

Em seguida, localize onde o APK está instalado no dispositivo. Para os fins deste guia, vamos usar o APK do Verificador de Chaves do Sistema Android (com.google.android.contactkeys) como exemplo de trabalho.

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

Se o APK do Verificador de Chaves do Sistema Android estiver instalado no seu dispositivo, o comando acima vai retornar um caminho indicando onde ele está instalado no dispositivo. Caso contrário, você não vai ver nenhuma saída.

Em seguida, baixe o APK do dispositivo Android para o computador em que você está trabalhando usando este comando (o local real e o nome do arquivo APK no dispositivo podem variar):

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

Para obter e verificar o nome do pacote do APK que você acabou de baixar, primeiro é necessário descompactar o APK, já que ele é um tipo especial de arquivo ZIP.

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

Essa etapa descompacta todos os arquivos que compõem o APK. O nome e a versão do pacote podem ser encontrados no manifesto do APK, que geralmente está em um arquivo chamado AndroidManifest.xml.

No entanto, o arquivo de manifesto obtido está em um formato binário, que não é legível por humanos. Para converter o XML binário em um formato legível por humanos, usamos a ferramenta aapt2 instalada anteriormente, conforme exigido na seção Pré-requisitos.

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'

Com a saída acima, agora podemos ter certeza de que o nome do pacote desse APK é com.google.android.contactkeys e o número da versão (versionCode) é 1413.

Agora, vamos procurar a assinatura de transparência do código no APK. Ele precisa ser um arquivo chamado code_transparency_signed.jwt contido na pasta META-INF entre os outros arquivos extraídos do APK.

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

Com essa string de hash, agora temos todas as informações necessárias para montar um payload de registro de acordo com o formato descrito na seção Conteúdo do registro. Neste exemplo, um payload de registro correspondente deve ser semelhante ao seguinte:

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

Observe também o caractere de nova linha após a versão do pacote.

Você pode salvar o conteúdo em um arquivo, como payload.txt. Isso será útil ao fazer o teste de prova de inclusão mais tarde.

Verificar a autenticidade da assinatura de código do APK

Agora, precisamos verificar a autenticidade do token de assinatura de código incorporado ao APK. Para isso, usamos bundletool e a chave pública do par de chaves que foi usado para assiná-lo em primeiro lugar. Eles são publicados em cada seção dos respectivos APKs. Supondo que você tenha salvo o certificado de chave pública (por exemplo, para o Verificador de Chaves do Sistema Android) em um arquivo chamado signing_cert_pubkey.pem, siga o guia abaixo para realizar a verificação de assinatura de código.

Primeiro, crie um arquivo ZIP e adicione o APK candidato a ele.

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

Agora podemos usar o comando check-transparency do bundletool para verificar se a assinatura de código incorporada ao APK candidato corresponde à publicada.

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.

Verifique se a saída do comando acima indica que a assinatura de transparência do código e a transparência do código foram verificadas. Se não forem, por exemplo, se você estiver vendo uma saída como Code transparency verification failed because the provided public key certificate does not match the transparency file, isso significa que a integridade do código do APK em questão pode estar comprometida e você não deve confiar no APK. Verifique se você está comparando os dados com o certificado de chave pública correto. Caso contrário, se tudo estiver correto, isso significa que a autenticidade da assinatura do código foi verificada para o APK que você está validando.

Verificação da inclusão do pacote (comprovação de inclusão)

Com o payload que você criou anteriormente, agora é possível testar se o pacote em questão foi incluído no registro de transparência.

Uma ferramenta de prova de inclusão foi publicada no repositório avb no Android Open Source Project. Para executá-lo:

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

O verificador usa o checkpoint correspondente e o conteúdo do registro (encontrado no diretório de blocos) para verificar se o payload do APK está no registro de transparência, confirmando se ele foi realmente publicado pelo Google.

A saída do comando é gravada em stdout:

  • OK. inclusion check success! se o código do pacote estiver incluído no registro;
  • FAILURE se não for.