apksigner

A ferramenta apksigner, disponível na revisão 24.0.3 e versões posteriores do Android SDK Build Tools, permite assinar APKs e confirmar que a assinatura de um APK será verificada em todas as versões da plataforma Android compatíveis com 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 compatíveis com a ferramenta. Para uma descrição mais completa de como a ferramenta apksigner é usada para assinar seus APKs, consulte o guia Assinar o aplicativo.

Atenção: se você assinar seu APK usando o apksigner e fizer outras alterações no APK, a assinatura será invalidada. Portanto, 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 signatário. 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 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 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 onde você quer salvar o APK assinado. Se essa opção não for 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 Android Framework 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, 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 Android Framework 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 determinado pacote do APK 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 o apksigner assina o pacote do 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.
-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 sã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. Se o keystore associado ao signatário tiver várias chaves, você precisará 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 fluxo de entrada padrão. Esse é o comportamento padrão para --ks-pass.

Observação: se você incluir várias senhas no mesmo arquivo, precisará 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. Se você tiver fornecido duas senhas para um signatário, o 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 com 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 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, é preciso 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 sistema operacional 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 fornecida.
  • file:<filename>: a senha é armazenada como uma única linha no arquivo fornecido.
  • stdin: a senha é fornecida como uma única linha no fluxo de entrada padrão. Esse é o comportamento padrão para --key-pass.

Observação: se você incluir várias senhas no mesmo arquivo, precisará 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. Se você tiver fornecido duas senhas para um signatário, o apksigner interpretará a primeira como a senha do keystore e a segunda como a senha da chave.

--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, 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, 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 passado como argumento para o construtor da classe JCA Provider. A classe é definida com a opção --ks-provider-class. Por padrão, o apksigner usa o construtor de 0 argumento 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. Se a chave for 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 Android Framework 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, 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 Android Framework 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 posterior:

    $ 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