apksigner

A ferramenta apksigner, disponível na revisão 24.0.3 e versões mais recentes das Ferramentas de build do SDK do Android, permite assinar APKs e confirmar que a assinatura de um APK será verificada em todas as versões da plataforma Android que ofereçam suporte a esse APK.

Esta página apresenta um pequeno guia para usar a ferramenta e serve como referência para as diferentes opções de linha de comando que oferecem suporte à ferramenta. Para uma descrição mais completa de como a ferramenta apksigner é usada para assinar seus APKs, consulte Assinar o app.

Cuidado: se você assinar usando o apksigner e fizer outras mudanças no APK, a assinatura vai ser invalidada. Se você usar o zipalign para alinhar seu APK, faça isso antes de assinar o APK.

Uso

Assinar um APK

A sintaxe para assinar um APK usando a ferramenta apksigner é a seguinte: 

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

Ao assinar um APK usando a ferramenta apksigner, forneça a chave privada e o certificado do assinante. Você pode incluir essas informações de duas maneiras:

  • Especifique um arquivo keystore usando a opção --ks.
  • Especifique o arquivo de chave privada e o arquivo de certificado separadamente usando as opções --key e --cert, respectivamente. O arquivo de chave privada precisa usar o formato PKCS #8 e o arquivo de certificado precisa usar o formato X.509.

Normalmente, você assina um APK usando apenas um signatário. Se você precisar assinar um APK usando vários signatários, use a opção --next-signer para separar o conjunto de opções gerais a serem aplicadas a cada um deles: 

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

Verificar a assinatura de um APK

A sintaxe para confirmar a verificação da assinatura de um APK em plataformas com suporte é a seguinte: 

apksigner verify [options] app-name.apk

Girar chaves de assinatura

A sintaxe para alternar uma linhagem de certificado de assinatura ou uma nova sequência de assinaturas é esta:

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

Opções

As listas a seguir incluem o conjunto de opções para cada comando compatível com a ferramenta apksigner.

Comando de assinatura

O comando de sinal apksigner tem estas opções.

Opções gerais

As opções a seguir especificam as configurações básicas a serem aplicadas a um signatário.

--out <apk-filename>
O local em que você quer salvar o APK assinado. Caso essa opção não seja fornecida explicitamente, o pacote do APK será assinado no local, que substitui o arquivo APK de entrada.
--min-sdk-version <integer>
O nível mais baixo da API de framework do Android que o apksigner usa para confirmar que a assinatura do APK será verificada. Valores mais altos permitem que a ferramenta use parâmetros de segurança mais rigorosos ao assinar o app, mas limitam a disponibilidade do APK a dispositivos com versões mais recentes do Android. Por padrão, apksigner usa o valor do atributo minSdkVersion do arquivo de manifesto do app.
--max-sdk-version <integer>
O nível mais alto da API de framework do Android que o apksigner usa para confirmar que a assinatura do APK será verificada. Por padrão, a ferramenta usa o nível de API mais alto possível.
--rotation-min-sdk-version <integer>
O nível de API mais baixo que a chave de assinatura alternada do APK precisa usar para produzir a assinatura do APK. A chave de assinatura original (não alternada) do APK vai ser usada em todas as versões anteriores da plataforma. Por padrão, as chaves de assinatura alternada, que oferecem suporte para dispositivos que executam o Android 13 (nível 33 da API) ou versões mais recentes, são usadas com o bloco de assinatura v3.1.

Observação: caso o app tenha sido assinado por uma chave de assinatura alternada em um dispositivo com o Android 12L (nível 32 da API) ou versões anteriores, é necessário usar --rotation-min-sdk-version 28 para continuar assinando seu app com a chave de assinatura alternada para o Android 9 (nível 28 da API).

--v1-signing-enabled <true | false>
Determina se o apksigner assina o pacote APK fornecido usando o esquema de assinatura tradicional baseado em JAR. Por padrão, a ferramenta usa os valores de --min-sdk-version e --max-sdk-version para decidir quando aplicar esse esquema de assinatura.
--v2-signing-enabled <true | false>
Determina se apksigner assina o pacote APK usando o Esquema de assinatura de APK v2. Por padrão, a ferramenta usa os valores de --min-sdk-version e --max-sdk-version para decidir quando aplicar esse esquema de assinatura.
--v3-signing-enabled <true | false>
Determina se o apksigner assina o pacote APK usando o Esquema de assinatura de APK v3. Por padrão, a ferramenta usa os valores de --min-sdk-version e --max-sdk-version para decidir quando aplicar esse esquema de assinatura.
--v4-signing-enabled <true | false | only>

Determina se apksigner assina o pacote APK usando o Esquema de assinatura de APK v4. Esse esquema produz uma assinatura em um arquivo separado (apk-name.apk.idsig). Se true e o APK não estiverem assinados, uma assinatura v2 ou v3 será gerada com base nos valores de --min-sdk-version e --max-sdk-version. Assim, o comando produz o arquivo .idsig com base no conteúdo do APK assinado.

Use only para gerar apenas a assinatura v4 sem modificar o APK e as assinaturas que tinha antes da invocação. only vai falhar caso o APK ainda não tenha uma assinatura v2 ou v3 ou se a assinatura usou uma chave diferente da fornecida para a invocação atual.

Por padrão, a ferramenta usa os valores de --min-sdk-version e --max-sdk-version para decidir quando aplicar esse esquema de assinatura.

-v, --verbose
Usa o modo de saída detalhado.

Opções por signatário

As opções a seguir especificam a configuração de um signatário específico. Essas opções não serão necessárias se você assinar seu app usando apenas um signatário.

--next-signer <signer-options>
Usado para especificar diferentes opções gerais para cada signatário.
--v1-signer-name <basename>
O nome base para os arquivos que compõem a assinatura baseada em JAR para o signatário atual. Por padrão, o apksigner usa o alias de chave do keystore ou o nome base do arquivo de chave para esse signatário.

Opções de chave e certificado

As opções a seguir especificam a chave privada e o certificado do signatário.

--ks <filename>
A chave privada e a cadeia de certificados do signatário residem no arquivo do keystore baseado em Java. Se o nome do arquivo for configurado como "NONE", o keystore que contém a chave e o certificado não precisará de um arquivo especificado, como é o caso de alguns keystores PKCS #11.
--ks-key-alias <alias>
O nome do alias que representa a chave privada e os dados do certificado do signatário no keystore. Caso o keystore associado ao signatário tenha várias chaves, será necessário especificar essa opção.
--ks-pass <input-format>

A senha do keystore que contém a chave privada e o certificado do signatário. Você precisa fornecer uma senha para abrir um keystore. A ferramenta apksigner é compatível com os seguintes formatos:

  • pass:<password>: senha fornecida inline com o resto do comando apksigner sign.
  • env:<name>: a senha é armazenada na variável de ambiente fornecida.
  • file:<filename>: a senha é armazenada como uma única linha no arquivo fornecido.
  • stdin: a senha é fornecida como uma única linha no stream de entrada padrão. Esse é o comportamento padrão para --ks-pass.

Observação: se você incluir várias senhas no mesmo arquivo, será necessário especificá-las em linhas separadas. A ferramenta apksigner associa as senhas aos signatários de um APK com base na ordem especificada dos signatários. Caso você tenha fornecido duas senhas para um signatário, apksigner interpretará a primeira como a senha do keystore e a segunda como a senha da chave.

--pass-encoding <charset>
Inclui as codificações de caracteres especificadas, como ibm437 ou utf-8, ao tentar processar senhas contendo caracteres não ASCII.

Muitas vezes, o keytool criptografa os keystores convertendo a senha pelo charset padrão do console. Por padrão, apksigner tenta descriptografar usando várias formas da senha:

  • O formulário Unicode
  • O formulário codificado usando o conjunto de caracteres padrão da JVM.
  • No Java 8 e versões anteriores, o formulário é codificado usando o conjunto de caracteres padrão do console.

    • No Java 9, o apksigner não detecta o conjunto de caracteres do console. Portanto, talvez seja necessário especificar --pass-encoding quando uma senha não ASCII for usada. Também pode ser necessário especificar essa opção com keystores que o keytool criou em um SO ou em uma localidade diferentes.

    --key-pass <input-format>

    A senha da chave privada do signatário, que é necessária se a chave for protegida por senha. A ferramenta apksigner oferece suporte a estes formatos:

    • pass:<password>: senha fornecida inline com o resto do comando apksigner sign.
    • env:<name>: a senha é armazenada na variável de ambiente fornecida.
    • file:<filename>: a senha é armazenada como uma única linha no arquivo fornecido.
    • stdin: a senha é fornecida como uma única linha no stream de entrada padrão. Esse é o comportamento padrão para --key-pass.
    --ks-type <algorithm>
    O tipo ou algoritmo associado ao keystore que contém a chave privada e o certificado do signatário. Por padrão, apksigner usa o tipo definido como a constante keystore.type no arquivo de propriedades de segurança.
    --ks-provider-name <name>
    O nome do JCA Provider a ser usado ao solicitar a implementação do keystore do signatário. Por padrão, apksigner usa o provedor com prioridade mais alta.
    --ks-provider-class <class-name>
    O nome completo da classe do JCA Provider a ser usado ao solicitar a implementação do keystore do signatário. Essa opção é uma alternativa para --ks-provider-name. Por padrão, o apksigner usa o provedor especificado na opção --ks-provider-name.
    --ks-provider-arg <value>
    Um valor de string a ser transmitido como o argumento para o construtor da classe JCA Provider. A própria classe é definida com a opção --ks-provider-class. Por padrão, apksigner usa o construtor de argumento zero da classe.
    --key <filename>
    O nome do arquivo que contém a chave privada do signatário. Esse arquivo precisa usar o formato PKCS #8 DER. Caso a chave seja protegida por senha, o apksigner vai solicitar a senha usando a entrada padrão, a menos que você especifique um tipo diferente de formato de entrada usando a opção --key-pass.
    --cert <filename>
    O nome do arquivo que contém a cadeia de certificados do signatário. Esse arquivo precisa usar o formato X.509 PEM ou DER.

    Verificar comando

    O comando de verificação apksigner tem estas opções abaixo.

    --print-certs
    Mostra informações sobre os certificados de assinatura do APK.
    --min-sdk-version <integer>
    O nível mais baixo da API de framework do Android que o apksigner usa para confirmar que a assinatura do APK será verificada. Valores mais altos permitem que a ferramenta use parâmetros de segurança mais rigorosos ao assinar o app, mas limitam a disponibilidade do APK a dispositivos com versões mais recentes do Android. Por padrão, apksigner usa o valor do atributo minSdkVersion do arquivo de manifesto do app.
    --max-sdk-version <integer>
    O nível mais alto da API de framework do Android que o apksigner usa para confirmar que a assinatura do APK será verificada. Por padrão, a ferramenta usa o nível de API mais alto possível.
    -v: --verbose
    Usa o modo de saída detalhado.
    -Werr
    Trata os avisos como erros.

    Exemplos

    Confira exemplos usando apksigner abaixo.

    Assinar um APK

    Assine um APK usando release.jks, que é a única chave do keystore:

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

    Assine um APK usando uma chave privada e um certificado, armazenados como arquivos separados: 

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

    Assine um APK usando duas chaves: 

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

    Assine um APK com uma chave de assinatura alternada e a alternação destinada à versão 28 ou mais recente do SDK: 

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

    Assine um APK com uma chave de assinatura alternada e a alternação destinada à versão 33 ou mais recente do SDK: 

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

    Verificar a assinatura de um APK

    Verifique se as assinaturas do APK precisam ser confirmadas como válidas em todas as plataformas Android compatíveis com o APK: 

    $ apksigner verify app.apk

    Verifique se as assinaturas do APK precisam ser confirmadas como válidas no Android 4.0.3 (nível 15 da API) ou versões mais recentes: 

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

    Girar chaves de assinatura

    Ative uma linhagem de certificado de assinatura que seja compatível com a rotação de chaves:

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

    Gire suas chaves de assinatura novamente:

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