In questa pagina vengono descritti vari metodi per garantire che l'APK installato sul tuo dispositivo Android corrisponda alla rivendicazione effettuata nel modello di richiedente. Ciò comporta l'estrazione dell'APK in questione dal dispositivo, il controllo dell'integrità del codice e l'esecuzione di una prova di inclusione nel log sull'artefatto estratto.
Procedura di verifica
Un log di trasparenza viene implementato con un albero di Merkle composto da hash. Un nodo foglia contiene dati, mentre un nodo padre contiene l'hash dei relativi nodi figlio.
In sostanza, sull'albero di Merkle vengono eseguiti due calcoli per verificare la proprietà di rilevamento delle manomissioni dei log di trasparenza: la prova di inclusione e la prova di coerenza. La prima dimostra che il log include una voce corrispondente a una determinata versione dell'APK. La voce di log include un hash, ovvero il digest SHA256 del token di firma del codice sotto forma di token JWT (JSON Web Token), che può essere ottenuto dagli APK corrispondenti. Quest'ultima dimostra che, quando vengono aggiunte nuove voci all'albero, il nuovo checkpoint è (crittograficamente) coerente con la versione precedente dell'albero.
Per verificare un APK coperto, esegui un test di prova di inclusione basato su un checkpoint testimoniato. Tieni presente che prevediamo di integrare questo log con una rete di testimoni pubblici utilizzando un protocollo di testimonianza standardizzato. In questo modo verrà fornito un checkpoint con testimonianza, che garantisce la coerenza del log.
Se vuoi verificare che l'APK sul tuo dispositivo sia conforme alla dichiarazione fatta nel modello di richiedente, consulta la descrizione di seguito.
Prova di inclusione
Un utente Android può verificare che un APK coperto sul suo dispositivo sia presente nel log estraendo prima l'APK e i relativi metadati, quindi confrontando l'hash radice ricalcolato con l'hash radice contenuto nel checkpoint pubblicato. Se corrispondono, l'utente Android può essere certo di alcune protezioni descritte nel modello di minacce.
Come verificare l'inclusione di un APK nel log
Come descritto in precedenza, l'elenco degli APK attualmente coperti è disponibile nella pagina Panoramica.
Prerequisiti di verifica
Prima di procedere alla verifica che l'artefatto (firmware o APK) sia conforme alla dichiarazione, assicurati che i seguenti strumenti siano disponibili su un computer connesso alla rete. A seconda del target di verifica, potresti non aver bisogno di tutti.
Linguaggio Go
Lo strumento di verifica è scritto in Go. Per crearlo, installa Go 1.24 o versioni successive dal sito di Go.
Android Debug Bridge (ADB)
ADB è uno strumento che comunica con un dispositivo Android per ispezionare l'immagine o estrarre gli APK, disponibile sul sito web degli strumenti della piattaforma SDK Android.
Verificatore della prova di inclusione
Il verificatore della prova di inclusione è un modulo Go che esegue query sul log di trasparenza e restituisce se un artefatto è incluso nel log.
È pubblicato nel repository GitHub android-binary-transparency all'indirizzo
https://github.com/android/android-binary-transparency/tree/main
Per clonare il repository AOSP avb:
computer:~$ git clone https://android.googlesource.com/platform/external/avb
Per clonare il repository GitHub android-binary-transparency:
computer:~$ git clone https://github.com/android/android-binary-transparency
AAPT2
AAPT2 (Android Asset Packaging Tool) è uno strumento di build utilizzato per compilare e pacchettizzare le risorse di un'app per Android. Può essere trovato come strumento autonomo in SDK Android Build Tools versione 26.0.2 e successive.
bundletool
bundletool è uno strumento utilizzato per creare un Android App Bundle (AAB). Può essere utilizzato anche per verificare le firme del codice APK.
Può essere scaricato da GitHub.
wget o curl
wget e curl sono strumenti che possono essere utilizzati per recuperare o scaricare file da internet. Assicurati di aver installato uno di questi strumenti, poiché gli script di verifica potrebbero utilizzarli.
Avbtool
avbtool
viene utilizzato per calcolare il digest VBMeta delle immagini del produttore e la verifica dei
file binari.
Dopo aver clonato il repository avb (come mostrato nella sezione Verificatore della prova di inclusione), avbtool.py si trova nella directory avb clonata.
Devi aggiungere questa directory alla variabile di ambiente $PATH.
computer:~$ PATH=$PATH:DIRECTORY_CONTAINING_AVBTOOL
Fbpacktool
fbpacktool
è uno script Python utilizzato per decomprimere i singoli componenti nel file
bootloader.img di Pixel.
Non è necessario se stai verificando gli APK.
Questo strumento è importante perché consente a avbtool.py di scoprire le immagini richieste per la verifica.
fbpacktool richiede Python 3.6 o versioni successive e il pacchetto PyYAML (ad esempio python3 -m pip install pyyaml).
Per utilizzare questo strumento, devi scaricare i seguenti sei script Python nella directory in cui si trova avbtool.py, rendere eseguibile fbpacktool.py e creare un collegamento simbolico denominato fbpacktool a fbpacktool.py per praticità.
Se hai 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 hai 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 aiuta a eseguire varie operazioni crittografiche utilizzando il terminale nel workflow di verifica. Assicurati che sia installato sul tuo sistema. Puoi controllare il terminale eseguendo questo comando e assicurandoti che il risultato restituito non sia vuoto:
computer:~$ which openssl
/usr/bin/openssl
Crea un payload per la verifica
Per verificare che l'APK estratto dal dispositivo corrisponda alle nostre dichiarazioni, devi creare un payload di log dalle informazioni derivate dall'APK.
Prima di iniziare, assicurati che adb possa essere utilizzato sul tuo dispositivo
attivando il debug adb sul
dispositivo.
Quindi, individua dove è installato l'APK sul tuo dispositivo. Ai fini di questa guida, utilizzeremo l'APK Android System Key Verifier (com.google.android.contactkeys) come esempio di lavoro.
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 l'APK Android System Key Verifier è installato sul tuo dispositivo, il comando precedente restituirà un percorso che indica dove è installato sul tuo dispositivo. In caso contrario, non vedrai alcun output.
Quindi, scarica l'APK dal tuo dispositivo Android sul computer su cui stai lavorando utilizzando questo comando (tieni presente che la posizione effettiva e il nome file dell'APK sul tuo dispositivo potrebbero variare):
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
Per ottenere e quindi verificare il nome del pacchetto dell'APK che hai appena scaricato, devi prima decomprimere l'APK, poiché un APK è in definitiva un tipo speciale di file ZIP.
computer:/tmp/testdir$ mkdir extracted && unzip contactkeys_candidate.apk -d extracted/
Questo passaggio decomprime tutti i file che componevano l'APK. Il nome e la versione del pacchetto sono disponibili nel manifest dell'APK, che di solito si trova in un file denominato AndroidManifest.xml.
Tuttavia, il file manifest ottenuto è in formato binario, che non è leggibile.
Per convertire l'XML binario in un formato leggibile, utilizziamo lo strumento aapt2 installato in precedenza (come richiesto nella sezione Prerequisiti).
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'
Dall'output riportato sopra, ora possiamo essere certi che il nome del pacchetto di questo APK è
com.google.android.contactkeys e il numero di versione (versionCode) è 1413.
Ora cercheremo la firma di trasparenza del codice all'interno dell'APK. Dovrebbe essere un file denominato code_transparency_signed.jwt contenuto nella cartella META-INF tra gli altri file estratti dall'APK.
computer:/tmp/testdir$ sha256sum extracted/META-INF/code_transparency_signed.jwt
1779a2aee029112c2c9bfc9390b9678f3e5f4595b39705e8528dd522e8042f11 code_transparency_signed.jwt
Con questa stringa hash, ora abbiamo tutte le informazioni necessarie per mettere insieme un payload di log in base al formato descritto nella sezione Contenuto dei log. In questo esempio, un payload di log corrispondente dovrebbe avere il seguente aspetto:
1779a2aee029112c2c9bfc9390b9678f3e5f4595b39705e8528dd522e8042f11
SHA256(Signed Code Transparency JWT)
com.google.android.contactkeys
1143
Tieni presente anche il carattere di nuova riga dopo la versione del pacchetto.
Puoi salvare i contenuti in un file, ad esempio payload.txt. Questo sarà utile quando eseguirai il test della prova di inclusione in un secondo momento.
Verifica l'autenticità della firma del codice APK
Ora dobbiamo verificare l'autenticità del token di firma del codice
incorporato nell'APK. Per farlo, utilizziamo bundletool e la chiave pubblica della coppia di chiavi utilizzata per firmarlo in primo luogo. Vengono pubblicate all'interno di ogni sezione dei rispettivi APK. Supponendo che tu abbia salvato il certificato di chiave pubblica
(ad es. per Android System Key Verifier)
in un file denominato signing_cert_pubkey.pem,
segui la guida di seguito per eseguire la verifica della firma del codice.
Innanzitutto, devi creare un file ZIP e aggiungere l'APK candidato al file 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
Ora possiamo utilizzare il comando check-transparency di bundletool per verificare se la firma del codice incorporata nell'APK candidato corrisponde a quella pubblicata.
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.
Assicurati che l'output del comando precedente indichi che sia la firma della trasparenza del codice sia la trasparenza del codice sono verificate.
In caso contrario, ad esempio se visualizzi un output come
Code transparency verification failed because the provided public key
certificate does not match the transparency file,
significa che l'integrità del codice dell'APK in questione potrebbe essere
compromessa e non devi considerare attendibile l'APK.
Ricorda di verificare che la verifica venga eseguita con il certificato di chiave pubblica corretto.
In caso contrario, se tutto il resto è corretto, significa che l'autenticità della firma del codice è verificata per l'APK che stai convalidando.
Verifica dell'inclusione del pacchetto (prova di inclusione)
Utilizzando il payload che hai creato in precedenza, ora puoi verificare se il pacchetto in questione è stato incluso nel log di trasparenza.
Uno strumento di prova di inclusione è stato pubblicato nel repository avb all'interno di Android Open Source Project. Per eseguirlo:
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
Il verificatore utilizza il checkpoint corrispondente e i contenuti del log (disponibili nella directory dei tile) per controllare che il payload dell'APK sia presente nel log di trasparenza, verificando che sia effettivamente pubblicato da Google.
L'output del comando viene scritto in stdout:
OK. inclusion check success!se il codice del pacchetto è incluso nel log,FAILUREse non lo è.