апксигнер

Инструмент 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 Signer имеет следующие параметры.

Общие параметры

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

--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 будет использоваться для всех предыдущих версий платформы. По умолчанию с блоком подписи v3.1 используются чередующиеся ключи подписи, которые поддерживаются на устройствах под управлением Android 13 (уровень API 33) или выше.

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

--v1-signing-enabled <true | false>
Определяет, подписывает ли apksigner данный пакет APK, используя традиционную схему подписи на основе JAR. По умолчанию инструмент использует значения --min-sdk-version и --max-sdk-version чтобы решить, когда применять эту схему подписи.
--v2-signing-enabled <true | false>
Определяет, подписывает ли apksigner данный пакет APK с помощью схемы подписи APK v2 . По умолчанию инструмент использует значения --min-sdk-version и --max-sdk-version чтобы решить, когда применять эту схему подписи.
--v3-signing-enabled <true | false>
Определяет, подписывает ли apksigner данный пакет APK с помощью схемы подписи APK 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 еще не имеет подписи v2 или v3 или если в подписи использовался ключ, отличный от того, который предоставлен для текущего вызова.

По умолчанию инструмент использует значения --min-sdk-version и --max-sdk-version чтобы решить, когда применять эту схему подписи.

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

Опции для каждого подписывающего лица

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

--next-signer <signer-options>
Используется для указания различных общих параметров для каждого подписывающего лица.
--v1-signer-name <basename>
Базовое имя файлов, составляющих подпись на основе JAR для текущего подписывающего лица. По умолчанию apksigner использует псевдоним ключа KeyStore или базовое имя файла ключа для этого подписывающего лица.

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

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

--ks <filename>
Закрытый ключ и цепочка сертификатов подписывающего лица находятся в данном файле KeyStore на основе 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>
Включает указанные кодировки символов, такие как ibm437 или utf-8 , при попытке обработки паролей, содержащих символы, отличные от ASCII.

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

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

    • В Java 9 apksigner не может определить кодировку консоли. Возможно, вам придется указать --pass-encoding если используется пароль, отличный от ASCII. Вам также может потребоваться указать эту опцию с помощью KeyStores, который 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, который будет использоваться при запросе реализации KeyStore подписывающей стороны. По умолчанию apksigner использует поставщика с наивысшим приоритетом.
    --ks-provider-class <class-name>
    Полное имя класса поставщика JCA, которое будет использоваться при запросе реализации KeyStore подписывающей стороны. Этот параметр служит альтернативой --ks-provider-name . По умолчанию apksigner использует провайдера, указанного в опции --ks-provider-name .
    --ks-provider-arg <value>
    Строковое значение, передаваемое в качестве аргумента конструктору класса поставщика JCA; сам класс определяется опцией --ks-provider-class . По умолчанию apksigner использует конструктор класса без аргументов.
    --key <filename>
    Имя файла, содержащего закрытый ключ подписывающего лица. Этот файл должен использовать формат PKCS #8 DER. Если ключ защищен паролем, apksigner запрашивает пароль, используя стандартный ввод, если вы не укажете другой формат ввода с помощью опции --key-pass .
    --cert <filename>
    Имя файла, содержащего цепочку сертификатов подписывающей стороны. Этот файл должен использовать формат X.509 PEM или DER.

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

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

    --print-certs
    Показать информацию о сертификатах подписи APK.
    --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, которые поддерживает APK:

    $ 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