апксигнер

Инструмент apksigner , доступный в версиях 24.0.3 и выше пакета Android SDK Build Tools, позволяет подписывать APK-файлы и подтверждать, что подпись APK-файла будет успешно проверена на всех версиях платформы Android, поддерживаемых этим APK-файлом.

На этой странице представлено краткое руководство по использованию инструмента, а также справочник по различным параметрам командной строки, поддерживаемым инструментом. Более подробное описание использования инструмента apksigner для подписи ваших APK-файлов см. в разделе «Подпишите ваше приложение» .

Внимание: если вы подпишете свой APK-файл с помощью apksigner и внесете в него дальнейшие изменения, подпись APK-файла станет недействительной. Если вы используете zipalign для выравнивания APK-файла, используйте его перед подписанием APK-файла.

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

Подписать APK

Синтаксис для подписи APK-файла с помощью инструмента apksigner выглядит следующим образом:

apksigner sign --ks keystore.jks |
  --key key.pk8 --cert cert.x509.pem
  [signer_options] app-name.apk

При подписании APK-файла с помощью инструмента apksigner необходимо предоставить закрытый ключ и сертификат подписывающего лица. Эту информацию можно указать двумя способами:

• Укажите файл хранилища ключей с помощью параметра --ks .
• Укажите файл закрытого ключа и файл сертификата отдельно, используя параметры --key и --cert соответственно. Файл закрытого ключа должен использовать формат PKCS #8, а файл сертификата — формат X.509.

Обычно APK-файл подписывается только одним подписантом. Если вам необходимо подписать APK-файл несколькими подписантами, используйте параметр --next-signer , чтобы разделить набор общих параметров , применяемых к каждому подписанту:

apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk

Проверьте подпись APK-файла.

Синтаксис для подтверждения успешной проверки подписи APK-файла на поддерживаемых платформах выглядит следующим образом:

apksigner verify [options] app-name.apk

Поворот клавиш подписи

Синтаксис для смены последовательности подписей в сертификате подписи выглядит следующим образом:

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file \
  --old-signer --ks old-signer-jks \
  --new-signer --ks new-signer-jks

Параметры

Ниже приведен список параметров для каждой команды, поддерживаемой инструментом apksigner .

Подписать команду

Команда apksigner sign` имеет следующие параметры.

Общие варианты

Следующие параметры определяют основные настройки, применяемые к подписывающему лицу:

--out <apk-filename>

Место, куда вы хотите сохранить подписанный APK-файл. Если этот параметр не указан явно, APK-пакет будет подписан на месте, что перезапишет исходный APK-файл.

--min-sdk-version <integer>

Самый низкий уровень API фреймворка Android, который apksigner использует для подтверждения проверки подписи APK-файла. Более высокие значения позволяют инструменту использовать более надежные параметры безопасности при подписании приложения, но ограничивают доступность APK-файла для устройств, работающих под управлением более новых версий Android. По умолчанию apksigner использует значение атрибута minSdkVersion из файла манифеста приложения.

--max-sdk-version <integer>

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

--rotation-min-sdk-version <integer>

Самый низкий уровень API, который должен использовать повернутая подпись APK для создания подписи APK. Для всех предыдущих версий платформы будет использоваться исходный (неповернутый) ключ подписи APK. По умолчанию поворотные ключи подписи, поддерживаемые на устройствах под управлением Android 13 (уровень API 33) или выше, используются с блоком подписи версии 3.1.

Примечание: Если ваше приложение было подписано с помощью измененного ключа подписи на устройстве под управлением Android 12L (уровень API 32) или ниже, то для продолжения подписи приложения с помощью измененного ключа подписи для Android 9 (уровень API 28) необходимо использовать --rotation-min-sdk-version 28 .

--v1-signing-enabled <true | false>

Определяет, будет ли apksigner подписывать данный APK-пакет, используя традиционную схему подписи на основе JAR-файлов. По умолчанию инструмент использует значения параметров --min-sdk-version и --max-sdk-version для определения того, когда следует применять эту схему подписи.

--v2-signing-enabled <true | false>

Определяет, будет ли apksigner подписывать данный APK-пакет с использованием схемы подписи APK Signature Scheme v2 . По умолчанию инструмент использует значения параметров --min-sdk-version и --max-sdk-version для определения момента применения данной схемы подписи.

--v3-signing-enabled <true | false>

Определяет, будет ли apksigner подписывать данный APK-пакет с использованием схемы подписи APK Signature Scheme v3 . По умолчанию инструмент использует значения параметров --min-sdk-version и --max-sdk-version для определения момента применения этой схемы подписи.

--v4-signing-enabled <true | false | only>

Определяет, подписывает ли apksigner данный APK-пакет с использованием схемы подписи APK v4 . Эта схема создает подпись в отдельном файле ( apk-name .apk.idsig ). Если true и APK не подписан, то генерируется подпись v2 или v3 в зависимости от значений параметров --min-sdk-version и --max-sdk-version . Затем команда создает файл .idsig на основе содержимого подписанного APK.

Используйте only для генерации подписи версии 4 без изменения APK-файла и любых подписей, которые были у него до вызова. Ошибка возникает only в том случае, если у APK-файла еще нет подписи версии 2 или 3, или если для подписи использовался другой ключ, отличный от предоставленного для текущего вызова.

По умолчанию инструмент использует значения параметров --min-sdk-version и --max-sdk-version для определения момента применения данной схемы подписи.

-v , --verbose

Используйте режим подробного вывода.

Параметры для каждого подписанта

Следующие параметры определяют конфигурацию конкретного подписанта. Эти параметры не требуются, если вы подписываете приложение, используя только одного подписанта.

--next-signer <signer-options>

Используется для указания различных общих параметров для каждого подписанта.

--v1-signer-name <basename>

Базовое имя для файлов, составляющих JAR-подпись для текущего подписывающего лица. По умолчанию apksigner использует псевдоним ключа из хранилища ключей или базовое имя файла ключа для данного подписывающего лица.

Варианты ключей и сертификатов

Следующие параметры указывают закрытый ключ и сертификат подписывающего лица:

--ks <filename>

Закрытый ключ и цепочка сертификатов подписывающего лица находятся в указанном файле хранилища ключей на основе Java. Если имя файла задано как "NONE" , то для хранилища ключей, содержащего ключ и сертификат, указывать файл не требуется, что имеет место для некоторых хранилищ ключей PKCS #11.

--ks-key-alias <alias>

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

--ks-pass <input-format>

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

• pass:<password> – Пароль предоставляется непосредственно в команде apksigner sign .
• env:<name> – Пароль хранится в указанной переменной окружения.
• file:<filename> – Пароль хранится в указанном файле в виде одной строки.
• stdin – Пароль передается в виде одной строки в стандартный поток ввода. Это поведение по умолчанию для --ks-pass .

Примечание: Если вы указываете несколько паролей в одном файле, делайте это на отдельных строках. Инструмент apksigner связывает пароли с подписантами APK-файла в зависимости от порядка их указания. Если вы указали два пароля для подписанта, apksigner интерпретирует первый пароль как пароль хранилища ключей, а второй — как пароль ключа.

--pass-encoding <charset>

При попытке обработки паролей, содержащих символы, отличные от ASCII, включаются указанные кодировки символов, такие как ibm437 или utf-8 .

Keytool часто шифрует хранилища ключей, преобразуя пароль с использованием кодировки по умолчанию консоли. По умолчанию apksigner пытается расшифровать пароль, используя несколько его вариантов:

Форма Юникода

Форма закодирована с использованием кодировки символов по умолчанию JVM.

В Java 8 и более ранних версиях форма кодируется с использованием кодировки символов по умолчанию для консоли.

В Java 9 apksigner не может определить кодировку консоли. Возможно, вам потребуется указать параметр --pass-encoding если используется пароль, отличный от ASCII. Также может потребоваться указать этот параметр для хранилищ ключей, созданных keytool в другой операционной системе или в другой локали.

--key-pass <input-format>

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

• pass:<password> – Пароль указывается непосредственно в команде apksigner sign .
• env:<name> – Пароль хранится в указанной переменной окружения.
• file:<filename> – Пароль хранится в указанном файле в виде одной строки.
• stdin – Пароль передается в виде одной строки в стандартный поток ввода. Это поведение по умолчанию для --key-pass .

--ks-type <algorithm>

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

--ks-provider-name <name>

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

--ks-provider-class <class-name>

Полное имя класса поставщика JCA, используемого при запросе реализации хранилища ключей подписывающего лица. Этот параметр служит альтернативой параметру --ks-provider-name . По умолчанию apksigner использует поставщика, указанного с помощью параметра --ks-provider-name .

--ks-provider-arg <value>

Строковое значение, передаваемое в качестве аргумента конструктору класса JCA Provider; сам класс определяется с помощью опции --ks-provider-class . По умолчанию apksigner использует конструктор класса без аргументов.

--key <filename>

Имя файла, содержащего закрытый ключ подписывающего лица. Этот файл должен использовать формат PKCS #8 DER. Если ключ защищен паролем, apksigner запросит пароль через стандартный ввод, если вы не укажете другой формат ввода с помощью параметра --key-pass .

--cert <filename>

Имя файла, содержащего цепочку сертификатов подписавшего лица. Этот файл должен быть в формате X.509 PEM или DER.

Проверить команду

Команда apksigner verify` имеет следующие параметры.

--print-certs

Отобразить информацию о сертификатах подписи APK-файла.

--print-certs-pem

Отобразить информацию о сертификатах подписи APK и вывести PEM-кодировку каждого сертификата подписи в стандартный вывод.

--min-sdk-version <integer>

Самый низкий уровень API фреймворка Android, который apksigner использует для подтверждения проверки подписи APK-файла. Более высокие значения позволяют инструменту использовать более надежные параметры безопасности при подписании приложения, но ограничивают доступность APK-файла для устройств, работающих под управлением более новых версий Android. По умолчанию apksigner использует значение атрибута minSdkVersion из файла манифеста приложения.

--max-sdk-version <integer>

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

-v , --verbose

Используйте режим подробного вывода.

-Werr

Рассматривайте предупреждения как ошибки.

Примеры

Ниже приведены примеры использования apksigner .

Подписать APK

Подпишите APK-файл, используя release.jks , единственный ключ в KeyStore:

$ apksigner sign --ks release.jks app.apk

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

$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk

Подпишите APK-файл, используя два ключа:

$ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk

Подпишите APK-файл с помощью повернутого ключа подписи, при этом поворот будет ориентирован на версию SDK 28+:

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk \
  --rotation-min-sdk-version 28

Подпишите APK-файл с помощью повернутого ключа подписи, при этом поворот будет ориентирован на версию SDK 33+:

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk

Проверьте подпись APK-файла.

Проверьте, ожидается ли подтверждение действительности цифровых подписей APK-файла на всех поддерживаемых им платформах Android:

$ apksigner verify app.apk

Проверьте, ожидается ли подтверждение действительности цифровых подписей APK-файла на Android 4.0.3 (уровень API 15) и выше:

$ apksigner verify --min-sdk-version 15 app.apk

Поворот клавиш подписи

Включите отслеживание происхождения сертификатов подписи с поддержкой ротации ключей:

$ apksigner rotate --out /path/to/new/file --old-signer \
    --ks release.jks --new-signer --ks release2.jks

Снова поверните ключи подписи:

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file --old-signer --ks release2.jks \
  --new-signer --ks release3.jks