Como Gerar um CSR para um Certificado de Assinatura de Código com o Java Keytool

O utilitário keytool, incluído no Java Development Kit (JDK), cria um par de chaves dentro de um keystore Java e o transforma numa CSR (Certificate Signing Request), o bloco codificado que uma Autoridade Certificadora (CA) lê para identificá-lo antes de emitir um certificado. Para assinatura de código, o que o keytool pode ser legitimamente usado para mudou em 1 de junho de 2023. Este guia apresenta primeiro a regra e depois percorre os comandos do keytool que continuam corretos: contra um keystore de software para assinatura interna, e contra um token de hardware ou HSM através do PKCS#11.

As chaves de assinatura de código devem ser geradas em hardware

Desde 1 de junho de 2023, os Requisitos de Base para Assinatura de Código do CA/Browser Forum exigem que a chave privada de cada certificado de assinatura de código publicamente confiável seja gerada e armazenada num módulo criptográfico de hardware que cumpra o padrão FIPS 140-2 Nível 2, Common Criteria EAL4+, ou um padrão equivalente. A chave deve ser não exportável. Isto aplica-se tanto a certificados padrão (Validação de Organização) como a certificados de Validação Estendida. Os certificados EV de assinatura de código sempre exigiram hardware; a alteração de 2023 estendeu a mesma regra aos certificados padrão. Os mesmos requisitos definem um tamanho mínimo de chave de RSA 3072 para certificados de assinatura de código, em vigor desde 1 de junho de 2021.

A consequência para esta página é direta. Um ficheiro keystore que o keytool cria no seu portátil ou servidor, seja no formato PKCS12 ou no formato JKS mais antigo, contém uma chave de software. Uma CSR gerada a partir dele não é aceite por uma Autoridade Certificadora pública para um certificado de assinatura de código. As Autoridades Certificadoras deixaram de suportar a geração de chaves no navegador e ficheiros de chave descarregáveis para estes produtos. A sua chave agora tem origem num de dois locais:

• Um token pré-configurado que a CA lhe envia. A CA gera o par de chaves e a CSR num token USB certificado do seu lado, carrega o certificado emitido nele, e envia-lhe o token por correio. Não há CSR para você criar.
• O seu próprio HSM ou token, com atestação de chave. Você gera a chave dentro do dispositivo, produz uma CSR a partir dela, e submete um ficheiro de atestação que prova à CA que a chave foi criada em hardware compatível e não pode ser exportada. Ambas as partes são obrigatórias; uma CSR sem atestação válida é rejeitada.

Qual das duas vias se aplica é decidido no momento da encomenda. Para a comparação, consulte os métodos de entrega de certificados de assinatura de código. Se já possui hardware compatível, siga o guia para o seu dispositivo: geração de CSR e atestação no YubiKey 5 FIPS ou o guia de CSR e atestação do Luna Network Attached HSM v7.x.

Onde o keytool ainda se encaixa

Nada do acima citado torna o keytool obsoleto. Continua a ser a ferramenta certa em três situações, e apenas a primeira produz uma CSR que pode enviar a uma CA pública:

• Como interface PKCS#11 para o seu token ou HSM. O keytool fala PKCS#11 nativamente. Aponte-o para a biblioteca PKCS#11 do seu fornecedor e a chave nunca sai do dispositivo, enquanto o familiar comando -certreq continua a produzir a CSR. Os comandos estão na secção sobre hardware abaixo.
• Para assinatura interna ou empresarial. Se assinar software interno com a sua própria CA organizacional, é a sua política interna que rege o armazenamento das chaves, não os Requisitos de Base públicos. Um keystore de software é uma escolha normal nesse caso.
• Para ensaios. Acertar o nome do assunto à primeira tentativa é mais fácil se já tiver percorrido os prompts uma vez num keystore descartável.

Um limite que vale a pena conhecer antes de começar: o keytool não gera atestação de chave. A atestação é produzida pelas próprias ferramentas do fornecedor do token ou HSM, portanto, mesmo na via PKCS#11, você usará a ferramenta do fornecedor para esse ficheiro e o keytool apenas para a CSR.

Gerar a CSR com o keytool

Se já criou a sua CSR e a Autoridade Certificadora emitiu o certificado, avance para importar a resposta da CA, o passo que falha silenciosamente quando o alias não corresponde.

O keytool vem com o JDK, portanto instale primeiro um JDK atual, caso não tenha um. O JDK 25 é a versão atual de suporte a longo prazo e o JDK 26 é a versão atual de curto prazo. Os comandos abaixo funcionam no JDK 17 e posteriores, e as diferenças de versão relevantes são assinaladas onde ocorrem. Confirme que a ferramenta está no seu path:

java -version
keytool -help
jarsigner -version

Um Java Runtime Environment isolado não é suficiente, e um keytool funcional não é prova de que tem um JDK: o antigo Oracle JRE 8 inclui o keytool mas não o jarsigner. Execute agora os três comandos. Se os dois primeiros responderem e o terceiro não, está a usar um JRE, e instalar um JDK nesse momento é mais fácil do que descobrir isso quando for assinar.

Passo 1: Criar o keystore e o par de chaves

Execute isto num terminal, ou no Command Prompt ou PowerShell no Windows, a partir do diretório onde deseja que o ficheiro keystore fique guardado:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12

Quatro detalhes nesse comando diferem de instruções mais antigas, e cada um deles importa:

• -genkeypair, não -genkey. A antiga grafia -genkey ainda funciona e o keytool não emite qualquer aviso sobre isso, mas é mantida no código-fonte apenas como um alias legado e já não aparece em nenhum lugar da documentação do JDK. Escreva -genkeypair.
• -storetype PKCS12, não JKS. O JKS é o formato de keystore proprietário da Oracle. O PKCS12 é o formato padrão da indústria e tem sido o padrão do JDK desde o Java 9. Se ainda assim criar um keystore JKS, o keytool avisa-o em todos os comandos que o tocam: “The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format.”
• O nome do ficheiro não define o formato. Nomear um ficheiro keystore.jks não o torna um keystore JKS. O keytool determina o tipo a partir de -storetype, ou da propriedade keystore.type no ficheiro de segurança do JDK quando este é omitido. No JDK 9 e posteriores, essa propriedade é pkcs12, portanto um comando que escreve para keystore.jks sem -storetype produz silenciosamente um ficheiro PKCS12 com um nome enganador.
• -keysize 3072, não 2048. Os Requisitos de Base definem RSA 3072 como o mínimo para assinatura de código, portanto um pedido de 2048 bits é rejeitado. Os JDKs atuais têm como padrão 3072 para RSA, mas o JDK 17 e anteriores têm como padrão 2048, portanto passe a opção explicitamente e o comando comporta-se da mesma forma em qualquer lugar.

O alias, codesign no exemplo, é o rótulo desta entrada dentro do keystore. Escolha algo que reconheça e anote-o: todos os comandos seguintes precisam dele, e uma incompatibilidade é o que quebra a importação do certificado descrita mais abaixo.

Uma chave ECDSA também é permitida. Substitua as opções RSA por -keyalg EC -groupname secp256r1 se preferir P-256, e confirme com a sua CA que o produto que encomendou suporta ECDSA.

Passo 2: Responder aos prompts que constroem o seu nome distinto

O keytool pede duas vezes uma palavra-passe para o keystore, e depois faz seis perguntas exatamente por esta ordem. A ordem importa: o segundo prompt pergunta pela unidade organizacional, não pela organização, e guias mais antigos listam-na de forma errada, pelo que um leitor que digite o nome da empresa aí acaba por colocá-lo no componente errado do nome.

• What is your first and last name? Isto torna-se o Common Name (CN), apesar da redação. Para um certificado de assinatura de código, o CN é a identidade do editor que os utilizadores verão, portanto introduza o nome legal exato da sua organização, ou o seu próprio nome legal completo para um certificado individual. Não introduza um nome de domínio aqui.
• What is the name of your organizational unit? O departamento, por exemplo TI. Não pressione Enter para saltar esta pergunta: o keytool escreve então o valor literal Unknown no nome, e OU=Unknown acaba na sua CSR. Se não quiser nenhuma unidade organizacional, use o formato -dname abaixo e deixe o componente OU fora da string.
• What is the name of your organization? O nome legal registado, escrito exatamente como consta nos registos oficiais. A CA verifica isto contra registos públicos.
• What is the name of your City or Locality? A cidade de registo, escrita por extenso.
• What is the name of your State or Province? O nome completo, não uma abreviatura.
• What is the two-letter country code for this unit? O código ISO, por exemplo US.

O keytool imprime então o nome montado e pede-lhe para o confirmar:

Is CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US correct?
  [no]:

A resposta padrão é no, portanto pressionar Enter devolve-o a todas as seis perguntas. Escreva yes para aceitar. Leia a linha com atenção antes: este é o nome distinto completo, não apenas o Common Name, e cada componente dele entra na CSR.

Não existe uma palavra-passe de chave separada num keystore PKCS12. Guias mais antigos terminam este passo com “introduza uma palavra-passe para a chave”, que é um comportamento do JKS. Num keystore PKCS12, a palavra-passe da chave é a palavra-passe do keystore, e se passar -keypass com um valor diferente, o keytool informa-o disso: “Different store and key passwords not supported for PKCS12 KeyStores. Ignoring user-specified -keypass value.”

Para saltar totalmente os prompts, forneça o nome completo com -dname. Mantenha o valor entre um único par de aspas retas:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12 -dname "CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US"

Não coloque -storepass na linha de comandos e deixe o keytool pedi-la. Passar uma palavra-passe como argumento grava-a no histórico da sua shell e expõe-a a qualquer pessoa que possa listar processos em execução.

Passo 3: Criar a CSR

O keystore agora contém uma chave privada e um certificado autoassinado temporário. Transforme essa entrada num pedido de certificado:

keytool -certreq -alias codesign -keystore codesign.p12 -file codesign.csr

Introduza a palavra-passe do keystore quando solicitado. Não precisa de -storetype aqui: o keytool deteta o formato de um ficheiro keystore que já existe. O alias deve ser o do passo 1, porque a CSR é assinada pela chave privada dessa entrada.

Este comando não cria uma chave privada. A chave foi criada no passo 1 e permanece dentro do keystore, razão pela qual o ficheiro keystore e a sua palavra-passe são agora tão sensíveis como a própria chave. Quem tiver ambos pode assinar software em seu nome.

Passo 4: Verificar a CSR antes de a enviar

Uma CSR rejeitada custa um ciclo de validação, portanto descodifique-a e leia-a novamente:

keytool -printcertreq -file codesign.csr

Confirme três coisas no resultado. A linha Subject deve listar os seus dados nos componentes corretos, com o nome legal da organização em O e a identidade do editor em CN. A linha da chave pública deve indicar 3072-bit RSA key ou superior. O algoritmo de assinatura deve ser um algoritmo SHA-2: os JDKs atuais assinam um pedido RSA de 3072 bits com SHA384withRSA e os mais antigos usam SHA256withRSA, e ambos são aceitáveis. Esse algoritmo apenas prova que possui a chave privada, e não é o algoritmo que a CA usará para assinar o seu certificado.

Também pode colar o pedido no nosso descodificador de CSR para ler os mesmos campos no navegador.

Ao submeter o pedido, abra o ficheiro num editor de texto simples e copie tudo, incluindo a primeira e a última linha. O keytool escreve exatamente estes marcadores, com cinco hífenes de cada lado:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIID3TCCAkUCAQAwaDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB0Zsb3JpZGExDjAM
...base64 encoded request...
-----END NEW CERTIFICATE REQUEST-----

A expressão NEW CERTIFICATE REQUEST é normal na saída do keytool e os formulários de registo aceitam-na. Se o seu editor tiver substituído alguma sequência de hífenes por um traço longo, o pedido será recusado: reescreva os marcadores como hífenes simples ou copie o ficheiro com um editor de código em vez disso.

Gerar a CSR num token ou HSM com o keytool

Este é o caminho que produz uma CSR sobre a qual uma CA pública pode agir. O keytool comunica com um token de hardware através do provedor SunPKCS11, portanto o par de chaves é criado dentro do dispositivo e nunca existe como ficheiro. Comece por escrever um pequeno ficheiro de configuração, por exemplo token.cfg, que nomeia o seu token e aponta para a biblioteca PKCS#11 que o seu fornecedor instalou:

name = token
library = /usr/local/lib/libeToken.so

Essas duas linhas, name e library, são as únicas obrigatórias. O caminho da biblioteca é específico do fornecedor e varia consoante o sistema operativo, portanto obtenha-o na documentação do seu token em vez deste exemplo. No Windows é uma DLL sob o diretório do sistema. Sem uma linha slot, o provedor associa-se ao primeiro slot que o dispositivo comunica, o que é o desejado quando apenas um token está ligado. Se tiver mais de um leitor ou token, adicione ou slotListIndex com a posição nessa lista, contando a partir de zero, ou slot com o ID numérico do slot que o utilitário do seu fornecedor imprime. Apenas um dos dois pode aparecer no ficheiro, e um ID de slot não é o mesmo número que uma posição de lista, portanto não adivinhe slot = 0.

Liste o que está no dispositivo. O token fornece o alias, portanto precisa disto antes de mais nada:

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg

-keystore NONE é obrigatório sempre que o keystore não é um ficheiro, e o pedido de palavra-passe está a solicitar o PIN do token. O keytool também aceita -addprovider SunPKCS11 -providerarg token.cfg em vez do par -providerClass e -providerArg; ambos os formatos funcionam, e a documentação das Autoridades Certificadoras geralmente mostra o mais antigo.

Com o alias em mãos, gere a chave no dispositivo e depois peça a CSR sobre ela:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -dname "CN=Example LLC, O=Example LLC, L=Miami, ST=Florida, C=US"

keytool -certreq -alias codesign -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -file codesign.csr

Aplicam-se dois avisos. Alguns tokens não permitem a geração de chaves via PKCS#11 e esperam que use o próprio utilitário do fornecedor, o que está bem: o keytool ainda pode criar a CSR sobre uma chave que a ferramenta do fornecedor gerou. E o keytool não consegue produzir o ficheiro de atestação que a sua CA irá pedir, portanto gere-o com as ferramentas do fornecedor ao mesmo tempo que a chave, seguindo o guia YubiKey ou Luna HSM.

Importar a resposta da CA para o mesmo alias

Quando o certificado chega, tem de voltar à entrada que gerou a CSR. Importe-o para qualquer outro lugar e o keytool continua a reportar sucesso enquanto produz um keystore incapaz de assinar, portanto leia esta secção antes de executar seja o que for.

Importe primeiro a raiz da CA e quaisquer certificados intermédios, cada um sob o seu próprio alias:

keytool -importcert -trustcacerts -alias caroot -file root.crt -keystore codesign.p12

O keytool imprime o certificado que está prestes a armazenar e pergunta Trust this certificate? com no como padrão, portanto escreva yes. Verifique a impressão digital contra a que a sua Autoridade Certificadora publica antes de responder.

Salte a importação da raiz e o comando seguinte falha com uma mensagem que não dá nenhuma pista sobre a causa:

keytool error: java.lang.Exception: Failed to establish chain from reply

Agora importe o seu certificado emitido usando o mesmo alias que usou no passo 1:

keytool -importcert -alias codesign -file codesign.crt -keystore codesign.p12

A mensagem que deseja ver é Certificate reply was installed in keystore. Isso significa que o keytool reconheceu uma chave privada existente sob esse alias e anexou o certificado emitido e a sua cadeia a ela.

Se inventar um novo alias em vez disso, o keytool aceita o ficheiro e imprime Certificate was added to keystore. Isso parece um sucesso e não é. O keytool armazenou o certificado como uma entrada confiável autónoma sem nenhuma chave privada por trás, e essa entrada nunca poderá assinar nada. O alias original, entretanto, ainda contém o certificado autoassinado temporário do passo 1. Verifique qual dos dois tem:

keytool -list -keystore codesign.p12

O seu alias de assinatura deve estar listado como PrivateKeyEntry. Um alias mostrado como trustedCertEntry é o erro descrito acima. Elimine-o com keytool -delete -alias wrongalias -keystore codesign.p12 e repita a importação para o alias correto. Adicione -v ao comando de listagem para confirmar que a entrada agora tem uma cadeia de certificados completa em vez de um único certificado autoassinado.

Num token de hardware, não há nada a importar na maioria dos casos, porque a CA carrega o certificado no dispositivo antes de o enviar. Se a sua CA lhe enviar um ficheiro de certificado para uma chave que gerou no seu próprio HSM, use o mesmo comando -importcert com as opções PKCS#11 da secção anterior.

Assinar um ficheiro JAR com o certificado

O objetivo de colocar um certificado de assinatura de código num keystore Java é assinar ficheiros JAR com o jarsigner, que também vem com o JDK. Com o certificado instalado sob o alias correto:

jarsigner -keystore codesign.p12 -tsa https://your-ca-timestamp-url application.jar codesign

Passe sempre -tsa com o URL de timestamp que a sua Autoridade Certificadora publica. Um timestamp regista que o JAR foi assinado enquanto o certificado ainda era válido, portanto a assinatura continua a funcionar após a expiração do certificado. Sem um, cada cópia do seu software deixa de validar no dia em que o certificado expira.

Quando a chave reside num token, aponte o jarsigner para PKCS#11 exatamente como o keytool faz:

jarsigner -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -tsa https://your-ca-timestamp-url application.jar codesign

Se o token tiver pouco espaço para a cadeia de certificados completa, forneça-a separadamente com -certchain. Verifique o resultado a seguir:

jarsigner -verify -verbose -certs application.jar

Uma execução bem-sucedida imprime jar verified juntamente com o nome distinto do signatário e os detalhes do timestamp. Os JDKs atuais usam SHA-384 como algoritmo de resumo padrão, portanto raramente precisará de definir manualmente -digestalg ou -sigalg.

Outras formas de criar este pedido são abordadas nos guias OpenSSL, CertReq, Microsoft Management Console e macOS Keychain Access, e a mesma regra de hardware aplica-se a todos eles. Veja também o nosso conjunto completo de tutoriais de assinatura de código e a visão geral sobre geração de CSR para certificados de assinatura de código. Se precisar de uma CSR do keytool para um certificado de website em vez de um de assinatura de código, siga o guia Tomcat ou JBoss.

Perguntas Frequentes