Como Gerar um CSR no Android

Este tutorial mostra como gerar um CSR (Certificate Signing Request) para Android com o utilitário Java keytool.

O Android não gera CSRs TLS de CA pública no próprio telefone: um certificado de CA pública é emitido para um servidor (ou um dispositivo que o utilizador controla), e as aplicações e navegadores Android consomem-no. O fluxo do keytool abaixo produz um pedido PKCS #10 a partir de uma keystore Java, que é o caminho correto quando precisa de um certificado TLS que uma aplicação Android ou um site direcionado a dispositivos móveis irá confiar.

Escolha o procedimento correto para o seu caso

“CSR para Android” pode significar três coisas diferentes. Certifique-se de que está na página certa antes de executar quaisquer comandos:

• Um certificado TLS para um servidor com o qual os clientes Android irão comunicar. Este é o caso mais comum, e o resto desta página aborda-o. Use o keytool (abaixo) ou gere o CSR fora do servidor com o nosso CSR Generator e, em seguida, instale o certificado emitido no servidor web, gateway de API ou broker MQTT que a sua aplicação acede.
• Uma chave de assinatura para um APK ou AAB. A assinatura de aplicações Android usa uma chave RSA ou EC autoassinada numa keystore Java: não existe nenhuma CA pública envolvida nem CSR para submeter. Gere a chave com o keytool a partir do assistente Build > Generate Signed Bundle / APK do Android Studio (ou execute o keytool manualmente) e, em seguida, registe a chave com o Google Play App Signing. Não encomende um certificado público para isto.
• Um certificado de dispositivo fornecido por um MDM ou EMM. O Android Enterprise emite certificados de cliente para dispositivos geridos através de SCEP, EST ou da Managed Configurations API. O CSR é gerado e o certificado instalado automaticamente pelo MDM. Não há nenhum passo manual do keytool.

Se o seu caso for o primeiro, continue. O fluxo tem duas partes: criar uma keystore PKCS12 que contém a chave privada e, em seguida, exportar o CSR dessa keystore.

O que vai precisar

• Uma instalação Java (JDK ou JRE) para que o comando keytool esteja disponível no seu PATH. Confirme com keytool -help. No Windows, a pasta bin do Java deve estar no PATH, ou pode executar o keytool diretamente a partir do diretório bin do JDK.
• O nome de domínio totalmente qualificado (FQDN) exato que deseja proteger (por exemplo, www.oseusite.com), além de quaisquer outros nomes de host que deseje no mesmo certificado (para a lista de Subject Alternative Name).
• Os dados legais da sua organização (país, estado, cidade, nome da organização) para o Distinguished Name. Use os valores exatamente como aparecem nos registos públicos da empresa: a CA rejeitará quaisquer discrepâncias.

Passo 1: Crie a keystore e a chave privada

Se já gerou o seu CSR, avance para submeter o CSR e depois para as instruções de instalação SSL no Android.

Abra um terminal (ou a Linha de Comandos no Windows) e execute o comando keytool abaixo. Ele cria uma nova keystore no formato PKCS12, gera um par de chaves RSA de 2048 bits dentro dela e armazena a chave sob o alias que escolher. O PKCS12 é o formato de keystore predefinido desde o JDK 9; o formato JKS, mais antigo, está obsoleto e deve ser evitado para novas chaves.

keytool -genkeypair 
  -alias myalias 
  -keyalg RSA -keysize 2048 
  -storetype PKCS12 
  -keystore yoursite.p12 
  -validity 825

No Windows, o mesmo comando numa só linha fica assim (note o caminho absoluto para poder encontrar o ficheiro novamente):

keytool -genkeypair -alias myalias -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore C:certsyoursite.p12 -validity 825

O que fazem as flags:

• -alias myalias: o nome da entrada dentro da keystore. Escolha um rótulo que reconheça e anote-o. Deve reutilizar este alias exato ao exportar o CSR e novamente ao importar o certificado assinado.
• -keyalg RSA -keysize 2048: uma chave RSA de 2048 bits é o mínimo público atual aceite por todas as CAs. Use 3072 bits para uma chave com maior duração, ou gere uma chave ECDSA com -keyalg EC -groupname secp256r1 para uma chave mais pequena e mais rápida (todas as CAs modernas emitem com base em ECDSA P-256 e P-384).
• -storetype PKCS12: força a keystore PKCS12 moderna. A extensão correspondente é .p12 (ou .pfx).
• -keystore yoursite.p12: o ficheiro de keystore a criar. Substitua o nome por algo que se lembre e mantenha o ficheiro seguro: ele contém a sua chave privada.
• -validity 825: durante quanto tempo o certificado autoassinado provisório dentro da keystore é válido. O certificado assinado pela CA substitui-o mais tarde, portanto este valor não afeta a duração em produção.

O keytool pede então uma palavra-passe da keystore. Escolha uma palavra-passe forte e guarde-a no seu gestor de segredos. Vai precisar dela para todos os comandos keytool seguintes e para qualquer servidor que consuma a keystore. Com keystores PKCS12, a palavra-passe da chave é igual à palavra-passe da keystore, pelo que há apenas uma palavra-passe a memorizar.

Passo 2: Introduza os dados da sua organização (DN)

O keytool pede agora o Distinguished Name (DN): os campos de identidade que aparecerão no CSR. Responda a cada pedido com o valor legal exato da sua organização. Use apenas caracteres ASCII padrão: letras não latinas quebram o pedido. A pontuação também importa, pois a CA compara os seus valores com os registos públicos da empresa.

• Qual é o seu nome próprio e apelido? Esta é a formulação do keytool para o Common Name (CN). Introduza o FQDN exato que deseja proteger (por exemplo, www.oseusite.com), ou um wildcard como *.oseusite.com. Não introduza o nome de uma pessoa.
• Qual é o nome da sua unidade organizacional? O CA/Browser Forum retirou o atributo organizationalUnitName em 2022-09-01, e as CAs públicas removem-no dos certificados emitidos. Note que premir Enter não deixa o campo vazio: o keytool substitui-o pelo seu próprio valor predefinido, pelo que o DN acaba por conter OU=Unknown, e esse valor é transportado para o CSR. Para omitir o atributo de facto, salte os pedidos e passe o DN diretamente com -dname, deixando o OU fora da string.
• Qual é o nome da sua organização? Introduza o nome legal completo da sua empresa, exatamente como registado (por exemplo, Sua Empresa Lda). Obrigatório para certificados OV e EV; para certificados de Validação de Domínio (DV) o valor é ignorado, pelo que qualquer texto de preenchimento curto funciona.
• Qual é o nome da sua cidade ou localidade? Escreva o nome completo da cidade onde a sua empresa está registada (por exemplo, Lisboa, e não LIS).
• Qual é o nome do seu estado ou província? Introduza o nome completo do estado ou província (por exemplo, Califórnia, e não CA).
• Qual é o código de país de duas letras para esta unidade? Introduza o código ISO 3166-1 alpha-2 de duas letras (por exemplo, US, GB, DE). Consulte a lista oficial ISO em caso de dúvida.

O keytool apresenta o DN montado e pergunta Is CN=…, OU=…, O=…, L=…, ST=…, C=… correct? Escreva yes e prima Enter para confirmar. Se detetar um erro de digitação, escreva no e o keytool reinicia os pedidos.

Passo 3: Exporte o CSR com um Subject Alternative Name

Agora exporte o CSR com keytool -certreq. Todas as CAs públicas validam o nome de host em relação à extensão Subject Alternative Name (SAN), e não ao Common Name (os navegadores e as bibliotecas TLS modernas deixaram de verificar o CN há anos), por isso inclua um SAN mesmo para um único nome de host. Use o mesmo alias definido no Passo 1:

keytool -certreq 
  -alias myalias 
  -file certreq.csr 
  -keystore yoursite.p12 
  -ext SAN=DNS:www.yoursite.com,DNS:yoursite.com

No Windows, o mesmo comando numa só linha:

keytool -certreq -alias myalias -file certreq.csr -keystore C:certsyoursite.p12 -ext SAN=DNS:www.yoursite.com,DNS:yoursite.com

Adicione uma entrada DNS: por nome de host para um certificado multi-domínio (separe-os com vírgulas, sem espaços). Para um wildcard, use DNS:*.oseusite.com. O keytool pede a palavra-passe da keystore e, em seguida, grava o CSR em certreq.csr no seu diretório atual.

Passo 4: Abra o CSR e submeta-o à CA

Abra certreq.csr em qualquer editor de texto (Notepad, TextEdit, nano, vim). Também pode imprimi-lo no terminal:

cat certreq.csr

Na Linha de Comandos do Windows:

type certreq.csr

Verá um bloco semelhante a este:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIDXjCCAkYCAQAwgZQxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlh
... (many lines of base64) ...
-----END NEW CERTIFICATE REQUEST-----

Selecione o bloco inteiro, incluindo as linhas BEGIN NEW CERTIFICATE REQUEST e END NEW CERTIFICATE REQUEST (algumas CAs designam-nas como BEGIN CERTIFICATE REQUEST / END CERTIFICATE REQUEST: ambas as designações são aceites). Copie-o e cole-o no campo CSR do seu formulário de encomenda.

Verifique o CSR antes de o submeter (opcional)

Vale a pena confirmar o Common Name, as entradas SAN e o tamanho da chave antes de enviar o pedido à CA. O keytool apresenta a mesma informação em relação à entrada da keystore:

keytool -printcertreq -file certreq.csr

Prefere uma ferramenta online? Cole o conteúdo do pedido no CSR Decoder da SSL Dragon para ler novamente o subject, a lista SAN e os parâmetros da chave pública. Confirme que o Common Name corresponde ao nome de host que os clientes utilizarão e que todos os nomes necessários aparecem na lista Subject Alternative Name.

O Android irá confiar no certificado emitido?

Sim, para qualquer certificado assinado por uma CA de confiança pública. O Android inclui um armazenamento de sistema de certificados raiz que reflete as listas de confiança dos principais navegadores, pelo que um certificado emitido sob uma dessas raízes é confiado pelo Chrome, pelo WebView e por qualquer aplicação que use o armazenamento de confiança do sistema, sem necessidade de configuração adicional.

Vale a pena conhecer duas ressalvas se também estiver a instalar o certificado (ou uma raiz de CA privada) no próprio dispositivo:

• As CAs instaladas pelo utilizador são ignoradas pelas aplicações no Android 7 e posteriores. Desde o Android 7 (Nougat), apenas o armazenamento do sistema é confiado pelo tráfego das aplicações por predefinição, e o Google Chrome também ignora as CAs instaladas pelo utilizador. Se a sua aplicação precisar de confiar numa CA privada, o programador tem de optar explicitamente por uma network security configuration que inclua <certificates src="user" />. Os certificados de CA pública não precisam disto: já se encontram no armazenamento do sistema.
• Faça pinning a um identificador estável, não a um único certificado. Se implementar certificate pinning na sua aplicação, faça pinning ao hash SPKI da chave pública ou à CA emissora, e não a um certificado folha específico. Caso contrário, a próxima renovação bloqueará os utilizadores.

Próximos passos

Depois de a CA validar o CSR e emitir o seu certificado, importe o certificado emitido de volta para a mesma keystore (sob o mesmo alias) e, em seguida, implemente a keystore no servidor que os clientes Android irão acessar. Consulte o nosso guia de instalação SSL no Android para os passos de instalação do lado do dispositivo, ou os guias de instalação específicos da plataforma em como instalar um certificado SSL se o seu back end funcionar em Tomcat, JBoss, Nginx ou outro servidor.