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;FAILUREse não for.