Na tej stronie opisujemy różne metody sprawdzania, czy plik APK zainstalowany na urządzeniu z Androidem odpowiada deklaracji złożonej w modelu wnioskodawcy. Obejmuje to pobranie danego pliku APK z urządzenia, sprawdzenie integralności jego kodu i przeprowadzenie weryfikacji uwzględnienia w dzienniku wyodrębnionego artefaktu.
Proces weryfikacji
Dziennik przejrzystości jest implementowany za pomocą drzewa Merkle składającego się z haszy. Węzeł liścia zawiera dane, a węzeł nadrzędny – hasz węzłów podrzędnych.
Zasadniczo na drzewie Merkle wykonywane są 2 obliczenia, które pozwalają zweryfikować, czy logi przejrzystości nie zostały zmodyfikowane: dowód uwzględnienia i dowód spójności. Pierwszy z nich potwierdza, że log zawiera wpis odpowiadający konkretnej wersji pakietu APK. Wpis logu zawiera skrót, który jest skrótem SHA256 tokena podpisu kodu w formie tokena sieciowego JSON (JWT), który można uzyskać z odpowiednich plików APK. To drugie potwierdza, że gdy do drzewa dodawane są nowe wpisy, nowy punkt kontrolny jest (kryptograficznie) zgodny z poprzednią wersją drzewa.
Aby zweryfikować objęty ochroną pakiet APK, przeprowadź test dowodu uwzględnienia na podstawie punktu kontrolnego z potwierdzeniem. Pamiętaj, że planujemy zintegrować ten dziennik z publiczną siecią świadków za pomocą ustandaryzowanego protokołu świadków. Zapewni to punkt kontrolny z poświadczeniem, który gwarantuje spójność logu.
Jeśli chcesz się upewnić, że pakiet APK na Twoim urządzeniu jest zgodny z twierdzeniem zawartym w modelu wnioskodawcy, zapoznaj się z poniższym opisem.
Dowód uwzględnienia
Użytkownik Androida może sprawdzić, czy objęty ochroną pakiet APK na jego urządzeniu znajduje się w dzienniku, wyodrębniając najpierw pakiet APK i powiązane z nim metadane, a następnie porównując ponownie obliczony skrót główny ze skrótem głównym zawartym w opublikowanym punkcie kontrolnym. Jeśli są zgodne, użytkownik Androida może mieć pewność, że niektóre zabezpieczenia opisane w modelu zagrożeń są aktywne.
Jak sprawdzić, czy pakiet APK został uwzględniony w logu
Jak wspomnieliśmy wcześniej, listę pakietów APK, które są obecnie objęte ochroną, znajdziesz na stronie Przegląd.
Weryfikacja – wymagania wstępne
Zanim przejdziesz do weryfikacji, czy artefakt (oprogramowanie układowe lub plik APK) jest zgodny z deklaracją, upewnij się, że na komputerze połączonym z siecią są dostępne te narzędzia. W zależności od celu weryfikacji możesz nie potrzebować wszystkich tych informacji.
Golang
Narzędzie do weryfikacji jest napisane w języku Go. Aby je skompilować, zainstaluj Go w wersji 1.24 lub nowszej ze strony Go.
Android Debug Bridge (ADB)
ADB to narzędzie, które komunikuje się z urządzeniem z Androidem, aby sprawdzić obraz lub wyodrębnić pliki APK. Jest ono dostępne na stronie narzędzi platformy Android SDK.
Weryfikator dowodu uwzględnienia
Weryfikator dowodu uwzględnienia to moduł Go, który wysyła zapytanie do dziennika przejrzystości i zwraca informację, czy artefakt jest uwzględniony w dzienniku.
Jest on opublikowany w repozytorium GitHub android-binary-transparency pod adresem https://github.com/android/android-binary-transparency/tree/main.
Aby sklonować repozytorium AOSP avb:
computer:~$ git clone https://android.googlesource.com/platform/external/avb
Aby sklonować repozytorium GitHub android-binary-transparency:
computer:~$ git clone https://github.com/android/android-binary-transparency
AAPT2
AAPT2 (Android Asset Packaging Tool) to narzędzie do kompilowania i pakowania zasobów aplikacji na Androida. Można go znaleźć jako samodzielne narzędzie w Android SDK Build Tools w wersji 26.0.2 lub nowszej.
bundletool
bundletool to narzędzie służące do tworzenia pakietów Android App Bundle (AAB). Można go też używać do weryfikowania podpisów kodu APK.
Można go pobrać z GitHub.
wget lub curl
wget i curl to narzędzia, których można używać do pobierania plików z internetu. Upewnij się, że masz zainstalowane jedno z tych narzędzi, ponieważ skrypty weryfikacyjne mogą ich wymagać.
Avbtool
avbtool służy do obliczania skrótu VBMeta obrazów fabrycznych i weryfikacji plików binarnych.
Po sklonowaniu repozytorium avb (jak pokazano w sekcji Weryfikator dowodu uwzględnienia) plik avbtool.py można znaleźć w sklonowanym katalogu avb.
Dodaj ten katalog do zmiennej środowiskowej $PATH.
computer:~$ PATH=$PATH:DIRECTORY_CONTAINING_AVBTOOL
Fbpacktool
fbpacktool to skrypt w Pythonie służący do rozpakowywania poszczególnych komponentów w pliku bootloader.img Pixela.
Nie jest to konieczne, jeśli weryfikujesz pliki APK.
To narzędzie jest ważne, ponieważ pozwala firmie avbtool.py znaleźć obrazy wymagane do weryfikacji.
fbpacktool wymaga Pythona w wersji 3.6 lub nowszej oraz pakietu PyYAML (np. python3 -m pip install pyyaml).
Aby korzystać z tego narzędzia, pobierz te 6 skryptów Pythona do katalogu, w którym znajduje się plik avbtool.py, ustaw plik fbpacktool.py jako wykonywalny i dla wygody utwórz dowiązanie symboliczne o nazwie fbpacktool do pliku fbpacktool.py.
Jeśli masz 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
Jeśli masz 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 pomaga wykonywać różne operacje kryptograficzne za pomocą terminala w przepływie pracy weryfikacji. Sprawdź, czy jest zainstalowany w systemie. Możesz to sprawdzić w terminalu, uruchamiając to polecenie i upewniając się, że zwrócony wynik nie jest pusty:
computer:~$ which openssl
/usr/bin/openssl
Tworzenie ładunku do weryfikacji
Aby sprawdzić, czy plik APK wyodrębniony z urządzenia jest zgodny z naszymi twierdzeniami, musisz utworzyć ładunek logu na podstawie informacji pochodzących z pliku APK.
Zanim zaczniesz, upewnij się, że na urządzeniu można używać adb, włączając debugowanie adb.
Następnie znajdź miejsce, w którym plik APK jest zainstalowany na urządzeniu. W tym przewodniku jako przykładu użyjemy pliku APK systemowego weryfikatora kluczy Androida (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
Jeśli na urządzeniu jest zainstalowany systemowy weryfikator kluczy Androida w postaci pliku APK, powyższe polecenie zwróci ścieżkę wskazującą, gdzie jest on zainstalowany. W przeciwnym razie nie zobaczysz żadnych danych wyjściowych.
Następnie pobierz plik APK z urządzenia z Androidem na komputer, na którym pracujesz, używając tego polecenia (pamiętaj, że rzeczywista lokalizacja i nazwa pliku APK na urządzeniu mogą się różnić):
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
Aby uzyskać i zweryfikować nazwę pakietu pobranego pliku APK, musisz najpierw rozpakować plik APK, ponieważ jest to specjalny rodzaj pliku ZIP.
computer:/tmp/testdir$ mkdir extracted && unzip contactkeys_candidate.apk -d extracted/
Ten krok spowoduje rozpakowanie wszystkich plików, z których składa się pakiet APK. Nazwę i wersję pakietu znajdziesz w pliku manifestu pakietu APK, który zwykle znajduje się w pliku o nazwie AndroidManifest.xml.
Jednak uzyskany plik manifestu jest w formacie binarnym, który nie jest zrozumiały dla człowieka.
Aby przekonwertować plik XML w formacie binarnym na format czytelny dla człowieka, używamy narzędzia aapt2 zainstalowanego wcześniej (zgodnie z wymaganiami instalacji w sekcji Wymagania wstępne).
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'
Z powyższych danych wyjściowych wynika, że nazwa pakietu tego pliku APK to com.google.android.contactkeys, a numer wersji (versionCode) to 1413.
Teraz wyszukamy podpis przejrzystości kodu w pliku APK. Powinien to być plik o nazwie code_transparency_signed.jwt znajdujący się w folderze META-INF wśród innych plików wyodrębnionych z pakietu APK.
computer:/tmp/testdir$ sha256sum extracted/META-INF/code_transparency_signed.jwt
1779a2aee029112c2c9bfc9390b9678f3e5f4595b39705e8528dd522e8042f11 code_transparency_signed.jwt
Dzięki temu ciągowi znaków mamy teraz wszystkie informacje potrzebne do utworzenia ładunku logu zgodnie z formatem opisanym w sekcji Treść logu. W tym przykładzie odpowiedni ładunek logu powinien wyglądać tak:
1779a2aee029112c2c9bfc9390b9678f3e5f4595b39705e8528dd522e8042f11
SHA256(Signed Code Transparency JWT)
com.google.android.contactkeys
1143
Zwróć też uwagę na znak nowego wiersza po wersji pakietu.
Możesz zapisać zawartość w pliku, np. payload.txt. Przyda się to później podczas testu dowodu uwzględnienia.
Weryfikowanie autentyczności podpisu kodu pakietu APK
Teraz powinniśmy zweryfikować autentyczność tokena podpisu kodu umieszczonego w pliku APK. W tym celu używamy bundletool i klucza publicznego pary kluczy, która została użyta do podpisania. Są one publikowane w każdej sekcji odpowiednich plików APK. Jeśli certyfikat klucza publicznego (np. dla systemowego weryfikatora kluczy Androida) został zapisany w pliku o nazwie signing_cert_pubkey.pem, wykonaj czynności opisane poniżej, aby przeprowadzić weryfikację podpisu kodu.
Najpierw utwórz plik ZIP i dodaj do niego kandydujący plik APK.
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
Możemy teraz użyć polecenia check-transparency narzędzia bundletool, aby sprawdzić, czy podpis kodu umieszczony w kandydacie na plik APK jest zgodny z opublikowanym.
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.
Upewnij się, że dane wyjściowe powyższego polecenia wskazują, że zarówno podpis przejrzystości kodu, jak i przejrzystość kodu zostały zweryfikowane.
Jeśli nie, na przykład jeśli widzisz dane wyjściowe takie jak Code transparency verification failed because the provided public key
certificate does not match the transparency file, oznacza to, że integralność kodu danego pakietu APK może być naruszona i nie należy ufać temu pakietowi APK.
Pamiętaj, aby sprawdzić, czy weryfikujesz je za pomocą prawidłowego certyfikatu klucza publicznego.
Jeśli wszystko inne jest w porządku, oznacza to, że autentyczność podpisu kodu została zweryfikowana w przypadku sprawdzanego pliku APK.
Weryfikowanie uwzględnienia pakietu (dowód uwzględnienia)
Korzystając z utworzonego wcześniej ładunku, możesz teraz sprawdzić, czy dany pakiet został uwzględniony w dzienniku przejrzystości.
Narzędzie do potwierdzania uwzględnienia zostało opublikowane w repozytorium avb w ramach Projektu Android Open Source. Aby go uruchomić:
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
Weryfikator używa odpowiedniego punktu kontrolnego i zawartości dziennika (znajdującej się w katalogu kafelków), aby sprawdzić, czy ładunek pakietu APK znajduje się w dzienniku przejrzystości, i potwierdzić, że został on opublikowany przez Google.
Dane wyjściowe polecenia są zapisywane w stdout:
OK. inclusion check success!, jeśli kod pakietu jest uwzględniony w dzienniku;FAILURE, jeśli nie jest.