אימות מלא של שקיפות חבילות APK בשירותי המערכת של Google

בדף הזה מפורטות שיטות שונות לוודא שה-APK שמותקן במכשיר Android תואם לטענה שנטענה במודל התובע. התהליך כולל שליפת ה-APK הרלוונטי מהמכשיר, בדיקת תקינות הקוד שלו וביצוע הוכחת הכללה ביומן על פריט המידע שחולץ.

תהליך האימות

יומן שקיפות מיושם באמצעות עץ מרקל (Merkle tree) שמורכב מגיבובים (hashes). צומת עלה מכיל נתונים, וצומת הורה מכיל את ה-hash של הצאצאים שלו.

בעצם, מתבצעים שני חישובים בעץ מרקל כדי לאמת את המאפיין של יומני השקיפות שמעיד על שיבוש: הוכחת הכללה והוכחת עקביות. ההוכחה הראשונה מאשרת שהיומן כולל רשומה שתואמת לגרסת APK מסוימת. רשומת היומן כוללת גיבוב (hash), שהוא תקציר SHA256 של אסימון החתימה של הקוד בצורת אסימון אינטרנט מסוג JSON‏ (JWT), שאפשר לקבל מקובצי APK תואמים. ההוכחה השנייה מאשרת שכאשר רשומות חדשות מתווספות לעץ, נקודת הבדיקה החדשה תואמת (מבחינה קריפטוגרפית) לגרסה הקודמת של העץ.

כדי לאמת קובץ APK מכוסה, מבצעים בדיקת הוכחת הכללה על סמך נקודת ביקורת מאומתת. חשוב לדעת שאנחנו מתכננים לשלב את היומן הזה עם רשת עדים ציבורית באמצעות פרוטוקול עדים סטנדרטי. כך תהיה נקודת ביקורת מאומתת, שמבטיחה את העקביות של היומן.

אם אתם רוצים לוודא שקובץ ה-APK במכשיר שלכם תואם לטענה שמופיעה במודל התובע, עיינו בתיאור שבהמשך.

הוכחת הכללה

משתמשי Android יכולים לוודא שקובץ APK שכלול ביומן נמצא במכשיר שלהם. קודם הם צריכים לחלץ את קובץ ה-APK ואת המטא-נתונים הרלוונטיים שלו, ואז להשוות בין גיבוב הבסיס שחושב מחדש לבין גיבוב הבסיס שכלול בנקודת הבדיקה שפורסמה. אם הם תואמים, משתמשי Android יכולים להיות בטוחים שהם נהנים מחלק מאמצעי ההגנה שמתוארים במודל האיומים.

איך מאמתים שקובץ APK נכלל ביומן

כמו שצוין קודם, רשימת קובצי ה-APK שכלולים כרגע מופיעה בדף הסקירה הכללית.

דרישות מוקדמות לאימות

לפני שמאמתים שהפריט (קושחה או APK) תואם לטענה, צריך לוודא שהכלים הבאים זמינים במחשב שמחובר לרשת. יכול להיות שלא תצטרכו את כל המסמכים האלה, בהתאם ליעד האימות.

Golang

כלי האימות כתוב ב-Go. כדי ליצור אותו, צריך להתקין את Go בגרסה 1.24 ואילך מאתר Go.

Android Debug Bridge‏ (ADB)

‫ADB הוא כלי שמתקשר עם מכשיר Android כדי לבדוק את קובץ האימג' או לחלץ קובצי APK. הוא זמין באתר של Android SDK Platform Tools.

מאמת הוכחת ההכללה

המאמת של הוכחת ההכללה הוא מודול Go ששולח שאילתות ליומן השקיפות ומפיק פלט שמציין אם פריט מידע כלול ביומן. הוא מתפרסם במאגר של android-binary-transparency ב-GitHub בכתובת https://github.com/android/android-binary-transparency/tree/main

כדי לשכפל את המאגר של AOSP avb:

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

כדי לשכפל את המאגר של android-binary-transparency ב-GitHub:

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

AAPT2

‫AAPT2 (כלי Android Asset Packaging Tool) הוא כלי build שמשמש לקמפול ולאריזה של המשאבים של אפליקציה ל-Android. הוא זמין ככלי נפרד ב-Android SDK Build Tools מגרסה 26.0.2 ואילך.

כלי Bundletool

‫bundletool הוא כלי שמשמש ליצירת קובץ Android App Bundle ‏(AAB). אפשר גם להשתמש בו כדי לאמת חתימות קוד של APK. אפשר להוריד אותו מ-GitHub.

‫wget או curl

‫wget ו-curl הם כלים שאפשר להשתמש בהם כדי לאחזר או להוריד קבצים מהאינטרנט. חשוב לוודא שאחד מהכלים האלה מותקן, כי יכול להיות שסקריפטים של אימות מסתמכים עליהם.

Avbtool

avbtool משמש לחישוב תקציר VBMeta של קובצי האימג' להגדרות המקוריות ואימות של קבצים בינאריים. אחרי שמשכפלים את המאגר של avb (כפי שמוצג בקטע "גורם מאמת הוכחת הכללה"), אפשר למצוא את avbtool.py בספרייה המשוכפלת של avb. צריך להוסיף את הספרייה הזו למשתנה הסביבה $PATH.

computer:~$ PATH=$PATH:DIRECTORY_CONTAINING_AVBTOOL

Fbpacktool

‫fbpacktool הוא סקריפט Python שמשמש לפריקת רכיבים נפרדים ב-bootloader.img של Pixel. אין צורך בכך אם מאמתים קובצי APK. הכלי הזה חשוב כי הוא מאפשר ל-avbtool.py לגלות את התמונות הנדרשות לאימות.

כדי להשתמש ב-fbpacktool צריך להתקין את Python בגרסה 3.6 ואילך ואת החבילה PyYAML (לדוגמה, python3 -m pip install pyyaml).

כדי להשתמש בכלי הזה, צריך להוריד את ששת הסקריפטים הבאים של Python לספרייה שבה נמצא avbtool.py, להפוך את fbpacktool.py לקובץ הפעלה וליצור קישור סימבולי בשם fbpacktool ל-fbpacktool.py לנוחות.

אם יש לכם 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

אם יש לכם 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 עוזר לבצע פעולות קריפטוגרפיות שונות באמצעות הטרמינל בתהליך האימות. חשוב לוודא שהיא מותקנת במערכת. כדי לבדוק את הטרמינל, מריצים את הפקודה הבאה ומוודאים שהתוצאה שמוחזרת לא ריקה:

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

יצירת מטען ייעודי (payload) לאימות

כדי לאמת את ה-APK שחילצתם מהמכשיר בהתאם לטענות שלנו, אתם צריכים ליצור מטען ייעודי (payload) של יומן ממידע שנגזר מה-APK.

לפני שמתחילים, צריך לוודא שאפשר להשתמש ב-adb במכשיר על ידי הפעלת ניפוי באגים ב-adb במכשיר.

לאחר מכן, מאתרים את המיקום שבו ה-APK מותקן במכשיר. לצורך המדריך הזה, נשתמש ב-APK של Android System Key Verifier (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

אם קובץ ה-APK של Android System Key Verifier מותקן במכשיר, הפקודה שלמעלה תחזיר נתיב שמציין איפה הוא מותקן במכשיר. אחרת, לא יוצג פלט.

לאחר מכן, מורידים את ה-APK ממכשיר ה-Android למחשב שבו אתם עובדים באמצעות הפקודה הבאה (שימו לב שהמיקום בפועל ושם הקובץ של ה-APK במכשיר עשויים להשתנות):

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

כדי לקבל את שם החבילה של קובץ ה-APK שהורדתם ולאמת אותו, קודם צריך לחלץ את קובץ ה-APK, כי קובץ APK הוא בעצם סוג מיוחד של קובץ ZIP.

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

בשלב הזה מתבצעת פריקה של כל הקבצים שמרכיבים את ה-APK. שם החבילה והגרסה מופיעים במניפסט של ה-APK, שבדרך כלל נמצא בקובץ בשם AndroidManifest.xml.

עם זאת, קובץ המניפסט שמתקבל הוא בפורמט בינארי, שלא קריא לאנשים. כדי להמיר את ה-XML הבינארי לפורמט קריא לאנשים, אנחנו משתמשים בכלי aapt2 שהתקנו קודם (כפי שנדרש להתקין בקטע דרישות מוקדמות).

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'

מהפלט שלמעלה, אנחנו יכולים להיות בטוחים ששם החבילה של ה-APK הזה הוא com.google.android.contactkeys ומספר הגרסה (versionCode) הוא 1413.

עכשיו נחפש את החתימה של שקיפות הקוד ב-APK. זה צריך להיות קובץ בשם code_transparency_signed.jwt שנמצא בתיקייה META-INF בין שאר הקבצים שחולצו מה-APK.

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

מחרוזת ה-hash הזו מספקת את כל המידע שצריך כדי להרכיב מטען ייעודי (payload) של יומן, בהתאם לפורמט שמתואר בקטע "תוכן היומן". בדוגמה הזו, המטען הייעודי של היומן אמור להיראות כך:

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

שימו לב גם לתו השורה החדשה אחרי גרסת החבילה.

אתם יכולים לשמור את התוכן בקובץ, למשל payload.txt. הוא יהיה שימושי בהמשך, כשנבצע בדיקה של הוכחת הכללה.

אימות האותנטיות של חתימת הקוד של ה-APK

עכשיו צריך לאמת את האותנטיות של אסימון החתימה של הקוד שמוטמע ב-APK. כדי לעשות את זה, אנחנו משתמשים ב-bundletool ובמפתח הציבורי של זוג המפתחות ששימש לחתימה מלכתחילה. הם מתפרסמים בכל קטע של קובצי ה-APK הרלוונטיים. נניח ששמרתם את אישור המפתח הציבורי (למשל, של Android System Key Verifier) בקובץ בשם signing_cert_pubkey.pem. כדי לאמת את החתימה של הקוד, פועלים לפי ההוראות במדריך הבא.

קודם כל, צריך ליצור ארכיון ZIP ולהוסיף אליו את ה-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

עכשיו אנחנו מוכנים להשתמש בפקודה check-transparency של bundletool כדי לוודא שחתימת הקוד שמוטמעת ב-APK המועמד תואמת לזו שפורסמה.

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.

חשוב לוודא שבפלט של הפקודה שלמעלה מצוין שגם חתימת שקיפות הקוד וגם שקיפות הקוד מאומתות. אם הם לא זהים, למשל אם הפלט שמוצג הוא Code transparency verification failed because the provided public key certificate does not match the transparency file, סימן שיכול להיות שתקינות הקוד של ה-APK המדובר נפגעה, ולא כדאי לסמוך על ה-APK. חשוב לוודא שאתם מאמתים אותם מול האישור הנכון של המפתח הציבורי. אם כל שאר הבדיקות תקינות, זה אומר שהאותנטיות של חתימת הקוד אומתה עבור ה-APK שאתם מאמתים.

אימות הכללת החבילה (הוכחת הכללה)

בעזרת המטען הייעודי (payload) שיצרתם קודם, אתם יכולים לבדוק אם החבילה הרלוונטית נכללה ביומן השקיפות.

כלי להוכחת הכללה פורסם avb במאגר בפרויקט הקוד הפתוח של Android. כדי להפעיל אותו:

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

הגורם המאמת משתמש בנקודת הבדיקה המתאימה ובתוכן היומן (שנמצא בספריית המשבצות) כדי לבדוק אם המטען הייעודי (payload) של ה-APK נמצא ביומן השקיפות, וכך לאמת שהוא אכן פורסם על ידי Google.

הפלט של הפקודה נכתב ב-stdout:

  • OK. inclusion check success! אם הקוד של החבילה נכלל ביומן,
  • אם לא, FAILURE.