Como Gerar um CSR em Servidores JBoss

Este tutorial mostra como gerar um CSR (Certificate Signing Request) no JBoss EAP e WildFly usando o utilitário Java keytool. O fluxo é composto por dois comandos: primeiro, keytool -genkeypair cria um keystore e uma chave privada sob um alias escolhido, e depois keytool -certreq exporta o CSR correspondente com os Subject Alternative Names que a CA irá emitir. O mesmo alias é reutilizado mais tarde quando você importa o certificado assinado, de modo que a chave, o CSR e o certificado final ficam todos no mesmo lugar.

Nota sobre versões: a versão moderna do JBoss é o Red Hat JBoss Enterprise Application Platform (EAP) 8, lançado em fevereiro de 2024 e baseado no projeto de origem WildFly (WildFly 41, lançado em julho de 2026, é a versão comunitária atual). Ambos configuram o HTTPS através do subsistema elytron e do https-listener do Undertow; a configuração mais antiga de conectores Tomcat ou Jetty mostrada em guias legados já não se aplica. A etapa do CSR em si, porém, é idêntica em todas as versões recentes, pois trata-se de uma simples operação Java com o keytool.

O que você vai precisar

• Uma instalação Java (JDK ou JRE) para que o comando keytool esteja disponível. O JBoss EAP 8.0 é executado em Java 11 (obsoleto) ou 17, o EAP 8.1 adiciona o Java 21, e o WildFly 41 é executado em Java 17, 21 ou 25 (o Java 11 já não é suportado na origem). Confirme com keytool -help.
• Acesso via shell ou terminal no servidor JBoss que irá hospedar a chave privada. A chave privada deve permanecer neste servidor.
• O nome de domínio totalmente qualificado (FQDN) exato que você deseja proteger, por exemplo www.seudominio.com, além de quaisquer outros nomes de host adicionais que deseja incluir no campo SAN.
• Os dados legais da sua organização (país, estado, localidade, nome da organização) para o Distinguished Name do CSR.

Passo 1: Criar o keystore e a chave privada

Se já gerou o seu CSR, avance para enviar o CSR e depois para instalar o seu certificado SSL no JBoss.

Abra um terminal no servidor JBoss e crie um novo keystore no formato PKCS12. O PKCS12 é o padrão moderno e portátil (RFC 7292) e é o formato de keystore padrão no Java desde o JDK 9; o formato proprietário mais antigo JKS está obsoleto. Execute:

keytool -genkeypair 
  -alias jboss 
  -keyalg RSA -keysize 2048 
  -storetype PKCS12 
  -keystore yourdomain.p12 
  -validity 825

O que significam os parâmetros:

• -alias jboss: o nome da entrada dentro do keystore. Escolha um rótulo que você reconheça (frequentemente jboss, server, ou o seu domínio). Anote-o. É necessário reutilizar exatamente este alias quando gerar o CSR e novamente quando importar o certificado assinado. Usar um alias diferente na importação é o erro mais comum ao usar o keytool.
• -keyalg RSA -keysize 2048: uma chave RSA de 2048 bits é o mínimo público atual. Para novos keystores que pretende manter por vários anos, 3072 bits é uma atualização razoável. A maioria das CAs públicas também aceita ECDSA (-keyalg EC -groupname secp256r1) se preferir uma chave menor e mais rápida. A opção -groupname requer JDK 13 ou posterior; no Java 11, use -keyalg EC -keysize 256, que seleciona a mesma curva secp256r1. O keytool rejeita ambas as opções no mesmo comando.
• -storetype PKCS12: força o uso do keystore moderno PKCS12. A extensão correspondente é .p12 (ou .pfx).
• -keystore yourdomain.p12: o ficheiro de keystore a criar. Substitua o nome por algo que você reconheça e mantenha este ficheiro em segurança; ele contém a sua chave privada.
• -validity 825: por quanto tempo o certificado autoassinado provisório dentro do keystore é válido. O certificado assinado pela CA substitui-o mais tarde, portanto o valor exato não afeta a vida útil em produção.

O keytool pede então uma senha do keystore. Escolha uma senha forte e guarde-a no seu gestor de segredos: você precisará dela em todos os comandos keytool posteriores e para a credential-reference do Elytron que irá configurar no JBoss. Com keystores PKCS12, a senha da chave é igual à senha do keystore, portanto há apenas uma senha para memorizar.

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

O keytool pede agora o Distinguished Name (DN): os campos de identidade que vão para o CSR. Responda a cada pergunta com o valor exato e legal para a sua organização. A pontuação e a precisão são importantes, porque uma CA irá rejeitar discrepâncias em relação aos registos empresariais públicos.

• Primeiro e último nome (CN): esta é a forma como o keytool a designa, mas trata-se do campo Common Name. Introduza o FQDN exato que está a proteger, por exemplo www.seudominio.com, ou um wildcard como *.seudominio.com. Não introduza o nome de uma pessoa.
• Unidade organizacional (OU): este campo já não é emitido pelas CAs públicas e é melhor deixá-lo em branco. Note que pressionar Enter não o deixa vazio: o keytool substitui-o pelo seu próprio valor padrão, pelo que o DN acaba por conter OU=Unknown, que depois é transportado para o CSR. Para omitir realmente o campo, use a forma não interativa -dname abaixo e deixe o OU fora da string.
• Organização (O): o nome legal completo da sua empresa, por exemplo Your Company LLC. Os certificados OV e EV exigem este campo; para certificados DV, muitas CAs aceitam-no como informativo, portanto preenchê-lo é mais seguro do que deixá-lo em branco.
• Cidade ou localidade (L): o nome completo da cidade, por exemplo San Jose. Não abrevie.
• Estado ou província (ST): o nome completo do estado ou província, por exemplo California. Não use um código de duas letras.
• Código do país (C): o código ISO de duas letras do país, por exemplo US, GB, DE.

Depois da última pergunta, o keytool mostra um resumo como CN=www.seudominio.com, OU=Unknown, O=Your Company LLC, L=San Jose, ST=California, C=US. Digite yes para confirmar. O ficheiro do keystore agora existe com uma entrada: o seu alias, contendo a chave privada e um certificado autoassinado provisório.

Se preferir um comando não interativo, passe o DN diretamente e evite as perguntas:

keytool -genkeypair 
  -alias jboss 
  -keyalg RSA -keysize 2048 
  -storetype PKCS12 
  -keystore yourdomain.p12 
  -dname "CN=www.yourdomain.com, O=Your Company LLC, L=San Jose, ST=California, C=US" 
  -validity 825

Passo 3: Gerar o CSR com SAN

Os navegadores e clientes TLS modernos validam os certificados face à extensão Subject Alternative Name (SAN), e não apenas face ao Common Name. Solicite os SANs diretamente no CSR para que a CA os inclua no certificado emitido. Use o mesmo alias e keystore do Passo 1:

keytool -certreq 
  -alias jboss 
  -keystore yourdomain.p12 
  -file yourdomain.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

O que significam os parâmetros:

• -alias jboss: deve corresponder ao alias do Passo 1. Este é o alias cuja chave privada assina o pedido.
• -keystore yourdomain.p12: deve corresponder ao keystore do Passo 1.
• -file yourdomain.csr: o nome do ficheiro de saída para o CSR.
• -ext san=dns:…: a extensão Subject Alternative Name. Liste todos os nomes de host que o certificado deve cobrir, incluindo tanto o domínio principal (yourdomain.com) como o subdomínio www. Adicione mais entradas separadas por vírgulas, por exemplo dns:api.yourdomain.com.

O keytool pede a senha do keystore e escreve o CSR em yourdomain.csr no diretório atual.

Fundamental: mantenha o seu alias e keystore

O erro mais comum ao usar o keytool no JBoss é importar o certificado assinado sob um novo alias. Ao fazer isso, o certificado é guardado como uma entrada confiável independente sem qualquer chave privada associada, e o key-manager do Elytron não conseguirá iniciar uma sessão TLS. Importe sempre a resposta assinada de volta para o mesmo alias que contém a chave privada (o alias do Passo 1).

Anote agora estes três valores, antes de fechar o terminal:

• O alias (neste guia, jboss).
• O caminho do ficheiro do keystore (por exemplo, yourdomain.p12; no JBoss, este geralmente encontra-se em $JBOSS_HOME/standalone/configuration/).
• A senha do keystore.

Se não tiver certeza de qual alias contém a sua chave, liste o conteúdo do keystore e procure pela entrada cujo tipo é PrivateKeyEntry:

keytool -list -v -keystore yourdomain.p12

Passo 4: Verificar o CSR antes de o enviar

Detete erros de digitação no DN ou SANs em falta antes de a CA os validar. Imprima o CSR com o keytool:

keytool -printcertreq -file yourdomain.csr

Ou, se o OpenSSL estiver instalado, pode usá-lo em vez disso:

openssl req -noout -text -in yourdomain.csr

Confirme três coisas no resultado: o Subject mostra o seu DN exato, o Subject Alternative Name lista todos os nomes de host necessários, e o tamanho da Public-Key corresponde ao que solicitou (RSA de 2048 bits, ou o que tiver escolhido). Também pode colar o CSR no nosso CSR Decoder para a mesma verificação num navegador.

Passo 5: Enviar o CSR à sua Autoridade Certificadora

Abra o ficheiro yourdomain.csr em qualquer editor de texto. O ficheiro é texto simples, começando com -----BEGIN NEW CERTIFICATE REQUEST----- e terminando com -----END NEW CERTIFICATE REQUEST-----. A palavra NEW é o que o keytool escreve, e é esperado: o conteúdo é um pedido PKCS#10 padrão que todas as CAs aceitam. Copie o bloco completo, incluindo essas linhas de cabeçalho e rodapé, e cole-o no campo de CSR durante o processo de compra com a sua CA. No Windows, use Ctrl + A e depois Ctrl + C para copiar o texto completo; no macOS, use Cmd + A e depois Cmd + C.

Faça uma cópia de segurança do ficheiro do keystore antes de fazer qualquer outra coisa. Se perder o ficheiro yourdomain.p12, perde também a chave privada, o que significa que o certificado assinado devolvido pela CA ficará inutilizável e terá de começar de novo com um CSR novo.

Depois de a CA validar o seu pedido e emitir o certificado, continue com como instalar o seu certificado SSL no JBoss. Irá importar o certificado assinado de volta para o mesmo alias no mesmo keystore, e depois referenciar esse keystore a partir de um key-store, key-manager e server-ssl-context do Elytron, configurados no https-listener do Undertow.

Posso reutilizar um CSR para uma renovação?

Pode, mas a melhor prática de segurança é gerar um novo keystore, uma nova chave privada e um novo CSR para cada certificado. Uma nova chave em cada renovação limita o impacto caso a chave antiga seja alguma vez comprometida, e o processo é o mesmo: execute keytool -genkeypair e keytool -certreq num novo ficheiro de keystore. A vida útil dos certificados TLS públicos está a diminuir sob as regras do CA/Browser Forum (200 dias a partir de 15 de março de 2026, reduzindo para 100 dias em 2027 e 47 dias em 2029), por isso planeie ciclos de CSR mais frequentes, ou automatize a emissão através do ACME onde a sua CA o suporte.