Keystore: o que é, quais formatos existem e como funciona

O que é um Keystore

Keystore (KeyStore) é um mecanismo padrão da Java Cryptography Architecture (JCA) para armazenar chaves criptográficas, certificados e entradas confiáveis. No desenvolvimento Android, o Keystore é usado para armazenar a chave privada que assina o aplicativo antes da publicação. A assinatura garante que o aplicativo foi realmente publicado pelo desenvolvedor especificado e que seu código não foi alterado após a publicação. Cada atualização do aplicativo deve ser assinada com a mesma chave, caso contrário o Google Play rejeitará o APK ou App Bundle.

Um Keystore pode conter várias entradas (aliases), cada uma representando um par de chaves (privada e pública) com um certificado. Alias é um nome de entrada único pelo qual o aplicativo acessa a chave durante a assinatura. Em um projeto Android típico, o Keystore contém uma entrada para assinar a versão de lançamento e pode conter entradas adicionais para assinar compilações de depuração. O Google Play Console exibe as impressões digitais SHA-1 e SHA-256 do certificado para cada aplicativo enviado.

O Android Studio inclui suporte integrado para Keystore através do menu Build → Generate Signed Bundle / APK. O assistente de assinatura do Android Studio permite criar um novo Keystore ou selecionar um existente, especificar um alias, senhas do Keystore e da chave, bem como os dados do certificado (nome da organização, cidade, país). Esses dados são incorporados ao certificado e ficam visíveis para os usuários ao verificar a assinatura do APK. O Google Play exige que o certificado seja válido por pelo menos 25 anos; o Android verifica a data de expiração ao instalar o aplicativo.

Por que o Keystore é importante para Android

As atualizações de aplicativos no Google Play só são possíveis com a mesma chave que assinou a primeira versão. Se o Keystore for perdido, é impossível publicar uma atualização — o aplicativo teria que ser republicado com um nome de pacote diferente. De acordo com Google Play Console Help (2026), a chave de assinatura do aplicativo só pode ser recuperada através do Google Play App Signing, um serviço que armazena a chave no lado do Google. Se o desenvolvedor usou esta opção, perder o Keystore local não é crítico.

Como funciona um Keystore

O processo de assinatura de um aplicativo Android envolve criar um resumo (hash) do conteúdo do APK e criptografá-lo com a chave privada do Keystore. Android SDK Build Tools incluem o utilitário apksigner, que realiza a assinatura usando APK Signature Scheme v2 (ou v3 para Android 9+). Ao instalar o aplicativo, o Android verifica a assinatura: descriptografa a assinatura com a chave pública do certificado, compara o hash do APK com o original — se os hashes não coincidirem, a instalação é rejeitada.

O Android suporta vários esquemas de assinatura: v1 (JAR signing), v2 (APK Signature Scheme), v3 (APK Signature Scheme com suporte a rotação de chaves) e v4 (instalações incrementais para Android 11+). O Google Play exige v2 ou v3 para novos aplicativos. O apksigner adiciona automaticamente todos os esquemas necessários durante a assinatura se a chave suportar os algoritmos correspondentes. Android 11+ suporta instalação ADB com assinatura v4, o que acelera o carregamento incremental de APKs grandes no dispositivo.

Algoritmos: o Android recomenda usar RSA-2048 ou ECDSA P-256 para a chave de assinatura. O certificado deve ser X.509 v3. O Android verifica se o certificado é válido no momento da instalação; se expirou, a instalação é bloqueada. É por isso que o Google recomenda definir o período de validade do certificado para pelo menos 25 anos. Google Play App Signing usa duas chaves: a chave de assinatura do aplicativo (app signing key) e a chave de upload (upload key) — o desenvolvedor usa a chave de upload para enviar o APK para a Console, e o Google assina o aplicativo para os usuários com a chave principal.

Formatos de Keystore: JKS e PKCS12

O Java suporta dois formatos principais de Keystore: JKS (Java KeyStore), um formato proprietário da Oracle que existe desde o JDK 1.2, e PKCS12, o formato padronizado Public-Key Cryptography Standards #12 da RSA Laboratories. O JKS usa seu próprio formato de armazenamento de dados e é suportado apenas dentro do ecossistema Java. O PKCS12 é um padrão aberto suportado por Java, .NET, OpenSSL, Python (cryptography) e a maioria das outras bibliotecas criptográficas.

O Google Play recomenda o PKCS12 como formato preferido para novos Keystores criados após 2021. JDK 9 e versões posteriores criam Keystores no formato PKCS12 por padrão (anteriormente o padrão era JKS). A principal vantagem do PKCS12 é a compatibilidade: um arquivo .p12 pode ser aberto em qualquer ambiente não vinculado ao Java. OpenSSL pode extrair certificados do PKCS12 e convertê-los para o formato PEM. Arquivos JKS exigem utilitários JDK para leitura e não podem ser processados pelo OpenSSL.

A conversão entre formatos é feita com o utilitário keytool do JDK. Ao migrar de JKS para PKCS12, certifique-se de que todos os aliases e senhas sejam transferidos corretamente. O comando keytool -importkeystore permite importar o conteúdo de um Keystore para outro independentemente do formato. Após a conversão, é melhor excluir o arquivo JKS antigo para evitar confusão com versões de chave. Android Studio suporta ambos os formatos ao gerar uma compilação assinada.

Criar um Keystore com keytool

O utilitário keytool faz parte do JDK (Java Development Kit) e fornece um conjunto completo de comandos para criar, visualizar e gerenciar Keystores. Para criar um novo Keystore com um par de chaves, usa-se o comando keytool -genkeypair especificando o formato PKCS12, o algoritmo RSA, o tamanho da chave e o período de validade do certificado. O Google Play exige uma validade de certificado de pelo menos 25 anos (9125 dias) — recomenda-se especificar este valor no parâmetro -validity.

Criar um novo Keystore

Exemplo de geração de um Keystore no formato PKCS12 para um projeto Android. O parâmetro -dname contém o Nome Distinto X.500 do certificado. O parâmetro -ext inclui o Subject Alternative Name se necessário — para Android, Basic Constraints é suficiente:

# Criação de um Keystore PKCS12 para Android
keytool -genkeypair -alias "upload_key" \
  -keyalg RSA -keysize 2048 -validity 9125 \
  -keystore "release-keystore.p12" \
  -storetype PKCS12 \
  -dname "CN=Developer,O=Company,C=RU"

Keytool solicitará a senha do Keystore e a senha da chave (podem ser iguais). O parâmetro -storetype PKCS12 cria um arquivo no formato moderno. -keysize 2048 atende aos requisitos do Google para o tamanho mínimo da chave RSA. -validity 9125 (25 anos) garante compatibilidade durante todo o ciclo de vida esperado do aplicativo. Após criar o Keystore, recomenda-se verificar seu conteúdo com o comando keytool -list -v -keystore release-keystore.p12.

Visualizar o conteúdo do Keystore

Para verificar as entradas do Keystore, usa-se o comando com a flag -list. A saída inclui o alias, datas de criação e expiração, tipo de entrada e impressões digitais SHA-256. Android Studio exibe as mesmas informações no diálogo Generate Signed Bundle / APK ao selecionar um Keystore existente:

# Visualização de entradas do Keystore
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Usar Keystore em CI/CD

Em um pipeline de CI/CD, o Keystore deve ser armazenado de forma segura e passado ao agente de compilação sem risco de comprometimento. GitHub Actions fornece Secrets para armazenar arquivos binários no formato base64. O Keystore é codificado com o comando base64, a string resultante é salva nos segredos do repositório e, durante a compilação, é decodificada de volta para um arquivo. GitLab CI usa um mecanismo semelhante através de Variables do tipo File.

Um exemplo de configuração de uma compilação CI com Keystore no GitHub Actions inclui decodificar o Keystore de um segredo, configurar as propriedades do Gradle e executar uma compilação assinada. Gradle, o plugin Android, lê o caminho do Keystore e as senhas do arquivo keystore.properties (excluído do .gitignore para desenvolvimento local) ou de variáveis de ambiente do sistema CI:

// build.gradle (app) — configuração de assinatura
@Override
android {
    signingConfigs {
        release {
            storeFile file("release-keystore.p12")
            storePassword System.getenv("STORE_PASSWORD")
            keyAlias System.getenv("KEY_ALIAS")
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Gradle lê as variáveis de ambiente definidas pelo sistema CI. O arquivo Keystore deve estar localizado na raiz do módulo do aplicativo, conforme especificado em storeFile. Por segurança, nunca armazene senhas no repositório — use os Secrets do sistema CI. Fastlane para Android fornece o plugin supply, que funciona com o Google Play Console, mas a assinatura do APK ainda requer um Keystore local no agente.

Uma alternativa é o Google Play App Signing. Ao usar esta opção, o desenvolvedor envia apenas a chave de upload (upload key) para o Google Play, e o Google assina o APK final com sua própria chave. Neste caso, o Keystore é usado apenas para criar a chave de upload, e sua perda não bloqueia atualizações — uma nova chave de upload pode ser gerada e registrada na Console. O Google Play App Signing é obrigatório para novos aplicativos desde agosto de 2021.

Segurança e backup do Keystore

Perder um Keystore é um dos problemas mais críticos no desenvolvimento Android. Sem um backup, é impossível lançar uma atualização de um aplicativo existente — o Google Play rejeita APKs assinados com uma chave diferente. Recomenda-se manter pelo menos duas cópias de backup do Keystore em diferentes armazenamentos físicos ou na nuvem: por exemplo, um arquivo criptografado no armazenamento em nuvem da equipe e uma mídia física no cofre da organização. As senhas do Keystore e da chave são armazenadas separadamente do arquivo, por exemplo, em um gerenciador de senhas com controle de acesso.

Android Studio, ao criar um novo Keystore no diálogo Generate Signed Bundle / APK, oferece lembrar os caminhos para compilações futuras. No entanto, o ambiente de desenvolvimento por si só não cria um backup — esta é a responsabilidade do desenvolvedor. Para desenvolvimento em equipe, recomenda-se usar o Google Play App Signing com a chave de upload transmitida por um canal seguro a todos os membros da equipe. Gradle pode assinar compilações de depuração automaticamente com um debug.keystore gerado, que não requer backup — é o mesmo para todas as instalações do Android Studio.

Segurança do Keystore durante a transferência: arquivos .p12 ou .jks devem ser transferidos apenas através de canais criptografados (SFTP, HTTPS, anexos de e-mail criptografados). Nunca inclua o Keystore no repositório de código fonte, mesmo que privado. GitGuardian ou GitHub secret scanning detectam automaticamente a publicação de credenciais, mas armazenar o Keystore em um repositório ainda é uma violação de segurança. Para CI/CD, use o mecanismo de segredos da plataforma (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) com criptografia em nível de infraestrutura.