apksigner

A ferramenta apksigner, disponível a partir da revisão 24.0.3 das Ferramentas de compilação 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 compatíveis com esses APKs. 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 compatíveis com a ferramenta. Para ver uma descrição mais completa de como a ferramenta apksigner é usada para assinar seus APKs, consulte o guia Assinar o app.

Cuidado: se você assinar usando o apksigner e fizer outras mudanças no APK, a assinatura será invalidada. Por esse motivo, use ferramentas como zipalign 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. Caso seja necessário assinar um APK usando vários signatários, use a opção --next-signer para separar o conjunto de opções gerais para aplicar a cada signatário:

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

Verificar a assinatura de um APK

A sintaxe para confirmar que a assinatura de um APK será verificada nas plataformas compatíveis é a seguinte:

apksigner verify [options] app-name.apk

Girar chaves de assinatura

A sintaxe para rotação de 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

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, substituindo 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.
--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 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 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 fornecido.
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 por meio do conjunto de caracteres padrão do console. Por padrão, o apksigner tenta descriptografar usando várias formas da senha: o formato Unicode, o formato codificado usando o conjunto de caracteres padrão da JVM e, no Java 8 e versões anteriores, o formato 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 diferente ou em uma localidade diferente.

--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 é 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 fornecido.
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 0 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 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

--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

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

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 (API de nível 15) 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