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 atributominSdkVersion
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
). Setrue
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. Useonly
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 comandoapksigner 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
ouutf-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, oapksigner
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 comandoapksigner 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
.
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. -
--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 constantekeystore.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, oapksigner
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 atributominSdkVersion
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