Прозрачность кода для пакетов приложений

Прозрачность кода — это дополнительный механизм подписи и проверки кода для приложений, опубликованных с помощью Android App Bundle. Он использует ключ подписи прозрачности кода, который принадлежит исключительно разработчику приложения.

Прозрачность кода не зависит от схемы подписи, используемой для пакетов приложений и APK-файлов. Ключ прозрачности кода является отдельным и отличается от ключа подписи приложения, который хранится в защищенной инфраструктуре Google при использовании подписи приложений Play .

Как работает прозрачность кода

Этот процесс включает в себя файл прозрачности кода в пакет после его сборки, но до его загрузки в Play Console для распространения.

Файл прозрачности кода — это веб-токен JSON (JWT), который содержит список файлов DEX и собственных библиотек, включенных в пакет, а также их хэши. Затем он подписывается с использованием ключа прозрачности кода, который хранится только у разработчика.

Code transparency diagram

Этот файл прозрачности кода распространяется в базовый APK, созданный из пакета приложения (в частности, в основную часть базового модуля). Тогда можно убедиться, что:

  • Все файлы DEX и собственного кода, присутствующие в APK, имеют соответствующие хеши в файле прозрачности кода.
  • Компонент открытого ключа ключа подписи прозрачности кода в приложении соответствует открытому ключу разработчика (который должен быть предоставлен разработчиком по отдельному безопасному каналу).

В совокупности эта информация подтверждает, что код, содержащийся в APK-файлах, соответствует замыслу разработчика и не был изменен.

Файл прозрачности кода не проверяет ресурсы, активы, манифест Android или любые другие файлы, которые не являются файлами DEX или собственными библиотеками, содержащимися в папке lib/ .

Проверка прозрачности кода используется исключительно с целью проверки разработчиками и конечными пользователями, которые хотят убедиться, что выполняемый ими код соответствует коду, который изначально был создан и подписан разработчиком приложения.

Известные ограничения

Существуют определенные ситуации, когда прозрачность кода использовать нельзя:

  • Приложения, которые указывают sharedUserId в манифесте. Такие приложения могут использовать свой процесс совместно с другими приложениями, что затрудняет гарантию качества кода, который они выполняют.
  • Приложения, использующие защиту от несанкционированного доступа или любую другую службу, которая вносит изменения в код после создания файла прозрачности кода, приведут к сбою проверки прозрачности кода.
  • Приложения, использующие устаревший Multidex на уровнях API ниже 21 (Android 5.0) и использующие функциональные модули. Прозрачность кода продолжит работать, когда приложение будет установлено из Google Play на устройствах Android 5.0+. Прозрачность кода будет отключена в старых версиях ОС.

Как добавить прозрачность кода

Прежде чем вы сможете добавить прозрачность кода в свое приложение, убедитесь, что у вас есть пара частного и открытого ключей, которую можно использовать для подписи прозрачности кода. Это должен быть уникальный ключ, отличающийся от ключа подписи приложения, который вы используете для подписи приложений в Play, и он должен храниться в безопасности и никогда не передаваться за пределы вашей организации.

Если у вас нет ключа, вы можете следовать инструкциям в руководстве по подписанию приложения , чтобы создать его на своем компьютере. Для прозрачности кода используется стандартный файл хранилища ключей, поэтому, хотя руководство предназначено для подписи приложений, процесс генерации ключей одинаков.

Использование плагина Android Gradle

Для поддержки прозрачности кода требуется плагин Android Gradle версии 7.1.0-alpha03 или новее. Чтобы настроить ключ, используемый для подписи прозрачности кода, добавьте следующее в блок bundle .

классный 

// In your app module's build.gradle file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

Котлин

// In your app module's build.gradle.kts file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

Используемый ключ должен быть тем, который вы будете использовать только для прозрачности кода, а не ключом подписи приложения, который используется функцией подписи приложений в Play.

Использование bundletool в командной строке

Для поддержки прозрачности кода требуется Bundletool версии 1.7.0 или новее, который можно скачать с GitHub .

Выполните следующую команду, чтобы добавить прозрачность кода в пакет приложений Android. Используемый ключ должен быть тем, который вы будете использовать только для прозрачности кода, а не ключом подписи приложения, который используется функцией подписи приложений в Play.

bundletool add-transparency \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --ks=/MyApp/keystore.jks \
  --ks-pass=file:/MyApp/keystore.pwd \
  --ks-key-alias=MyKeyAlias \
  --key-pass=file:/MyApp/key.pwd

В качестве альтернативы, если вы хотите использовать свои собственные инструменты подписи, вы можете использовать Bundletool для создания файла прозрачности неподписанного кода, подписать его в отдельной среде и внедрить подпись в пакет:

# Generate code transparency file
bundletool add-transparency \
  --mode=generate_code_transparency_file \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/code_transparency_file.jwt \
  --transparency-key-certificate=/MyApp/transparency.cert

# Add code transparency signature to the bundle
bundletool add-transparency \
  --mode=inject_signature \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert \
  --transparency-signature=/MyApp/signature

Проверка прозрачности кода приложения

Существуют разные методы проверки кода на соответствие файлу прозрачности кода, в зависимости от того, установлены ли APK-файлы на устройстве Android или загружены локально на ваш компьютер.

Использование Bundletool для проверки пакета приложений или набора APK

Вы можете использовать Bundletool для проверки прозрачности кода в пакете приложений или наборе APK. Используйте команду check-transparency , чтобы распечатать отпечаток общедоступного сертификата:

# For checking a bundle:
bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab

No APK present. APK signature was not checked.
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.


# For checking a ZIP containing app's APK splits:
bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

При желании вы можете указать общедоступный сертификат, по которому вы хотите проверить пакет или набор APK, чтобы вам не приходилось сравнивать хэши вручную: 

bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert

No APK present. APK signature was not checked.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.


bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.

Использование Bundletool для проверки приложения, установленного на устройстве

Чтобы проверить приложение, установленное на устройстве Android, убедитесь, что устройство подключено к вашему компьютеру через ADB, и введите следующую команду:

bundletool check-transparency \
  --mode=connected_device \
  --package-name="com.my.app"

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

Проверка прозрачности подключенного устройства также может дополнительно сверить подпись с указанным вами открытым ключом:

bundletool check-transparency \
  --mode=connected-device \
  --package-name="com.my.app" \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.