Como Gerar um CSR no GlassFish

Este tutorial mostra como gerar um CSR (Certificate Signing Request) para GlassFish (agora Eclipse GlassFish) usando o utilitário Java keytool.

O GlassFish é diferente de forma útil: uma instalação nova já vem com um keystore (keystore.p12 no Eclipse GlassFish 7.1 e versões mais recentes, ou keystore.jks em versões mais antigas) e uma entrada de certificado padrão sob o alias s1as. Você pode gerar o CSR diretamente a partir dessa chave existente, ou substituí-la por uma nova chave sob o mesmo alias. De qualquer forma, o mesmo alias é reutilizado quando você importa o certificado assinado, de modo que a chave, o CSR e o certificado emitido ficam todos no mesmo lugar.

O que você vai precisar

• Uma instalação funcional do GlassFish (ou Eclipse GlassFish). O keystore padrão fica no diretório de configuração do domínio, por exemplo glassfish/domains/domain1/config/keystore.p12 no Eclipse GlassFish 7.1 e versões mais recentes, ou keystore.jks em versões mais antigas.
• Uma instalação Java para que o comando keytool esteja disponível. O GlassFish vem com um JDK, então o keytool normalmente já está no PATH. Confirme com keytool -help.
• Acesso ao shell ou terminal no servidor GlassFish. 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 nomes de host adicionais para o campo SAN.
• Os dados legais da sua organização (país, estado, localidade, nome da organização) para o Nome Distinto (Distinguished Name) do CSR.
• A senha mestra do GlassFish para o domínio. O padrão de fábrica é changeit; altere-a em sistemas de produção com asadmin change-master-password.

Duas formas de gerar o CSR

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

Existem dois fluxos comuns com o keytool no GlassFish. Escolha o que corresponde à sua situação:

• Opção A: Gerar o CSR a partir da chave s1as existente (recomendado). Um novo domínio GlassFish já possui uma chave privada sob o alias s1as dentro do keystore padrão (keystore.p12 na versão 7.1+, keystore.jks em versões mais antigas). O caminho mais rápido e de menor risco é deixar essa chave no lugar e apenas exportar um CSR a partir dela. Vá para a Opção A.
• Opção B: Substituir a chave s1as padrão por uma nova chave e depois gerar o CSR. Use esta opção se quiser um tamanho de chave e um DN conhecidos e atualizados, ou se suspeitar que a chave padrão foi usada ou exposta. Vá para a Opção B.

Independentemente da opção escolhida, o alias deve permanecer como s1as (ou, se você alterá-lo, também deverá atualizar o domain.xml para corresponder). O listener HTTPS do GlassFish procura o certificado pelo alias, portanto um alias incompatível significa que o GlassFish não conseguirá encontrar a chave e o TLS não será iniciado.

Opção A: Gerar o CSR a partir da chave s1as existente

Passo 1: Acesse o diretório de configuração do GlassFish

Abra um terminal e vá para o diretório que contém o keystore do seu domínio. Numa instalação padrão, essa é a pasta config do domain1:

cd /opt/glassfish7/glassfish/domains/domain1/config

Ajuste o caminho conforme o local onde você instalou o GlassFish (versões mais antigas do GlassFish 4 organizam a instalação sob uma pasta de nível superior glassfish4/; Eclipse GlassFish 6, 7 e 8 normalmente são instalados sob glassfish7/, glassfish8/, ou similar). Se você criou o seu próprio domínio, substitua domain1 pelo nome desse domínio. Execute ls *.p12 *.jks nesse diretório para confirmar o nome do arquivo do keystore: no Eclipse GlassFish 7.1 e versões mais recentes você verá keystore.p12; em versões mais antigas verá keystore.jks. Substitua esse nome de arquivo onde os comandos abaixo mostrarem keystore.jks.

Passo 2: Confirme que a entrada s1as existe

Liste o conteúdo do keystore e verifique se s1as está presente e é um PrivateKeyEntry:

keytool -list -v -keystore keystore.jks -alias s1as

Digite a senha do keystore (padrão de fábrica changeit; num servidor de produção ela deve coincidir com a senha mestra do domínio). A saída deve incluir a linha Entry type: PrivateKeyEntry. Se, em vez disso, você receber a mensagem Alias <s1as> does not exist, mude para a Opção B e crie uma nova entrada.

Passo 3: Exporte o CSR com SAN

Navegadores e clientes TLS modernos validam os certificados com base na extensão Subject Alternative Name (SAN), e não apenas no Common Name. Solicite os SANs diretamente no CSR para que a CA os inclua no certificado emitido:

keytool -certreq 
  -alias s1as 
  -keystore keystore.jks 
  -file glassfish.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

O que significam os parâmetros:

• -alias s1as: o alias de certificado padrão do GlassFish já existente. A chave privada sob este alias assina a solicitação.
• -keystore keystore.jks: o arquivo de keystore padrão do GlassFish. O Eclipse GlassFish 7.1 e versões mais recentes vêm com um keystore PKCS12 chamado keystore.p12; versões mais antigas usam um keystore JKS chamado keystore.jks. Use o nome de arquivo que realmente existe nesse diretório. O comando em si é o mesmo em ambos os casos; o keytool detecta o formato.
• -file glassfish.csr: o nome do arquivo de saída do CSR. Escolha qualquer nome que preferir.
• -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 raiz (yourdomain.com) quanto o subdomínio www. Adicione mais entradas separadas por vírgula, por exemplo dns:api.yourdomain.com.

O keytool solicita a senha do keystore e grava o CSR em glassfish.csr no diretório atual. O Subject (Nome Distinto) do CSR é retirado do que estiver armazenado na entrada s1as; numa instalação nova do GlassFish, esse é o certificado autoassinado gerado automaticamente, portanto o DN não corresponderá à sua empresa. A maioria das CAs verifica apenas o Common Name e a lista SAN, permitindo que você substitua o restante do DN no formulário de pedido, mas se precisar de um CSR cujo DN já traga os dados legais da sua empresa, use a Opção B.

Opção B: Substituir a chave s1as padrão por uma nova

Use esta opção quando quiser controle total sobre o tamanho da chave e o DN, ou quando preferir não reutilizar a chave gerada de fábrica. O fluxo é: excluir a entrada padrão s1as, criar uma nova chave sob o mesmo alias e depois exportar o CSR. Manter o alias como s1as significa que você não precisará alterar o domain.xml depois.

Passo 1: Faça backup do keystore

Antes de excluir qualquer coisa, copie o keystore atual para que você possa revertê-lo se necessário. No diretório config do domínio:

cp keystore.jks keystore.jks.bak

Passo 2: Exclua a entrada s1as padrão

keytool -delete -alias s1as -keystore keystore.jks

Digite a senha do keystore quando solicitado.

Passo 3: Crie uma nova chave privada sob o mesmo alias

Gere uma nova chave RSA de 2048 bits sob o alias s1as e forneça o DN diretamente no comando para que ele seja não interativo:

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

O que significam os parâmetros:

• -alias s1as: reutiliza o alias padrão do GlassFish, para que o domain.xml não precise de alterações.
• -keyalg RSA -keysize 2048: uma chave RSA de 2048 bits é o mínimo público atual. Para novas chaves que você planeja 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) para uma chave menor e mais rápida.
• -keystore keystore.jks: o keystore padrão do GlassFish. Substitua por keystore.p12 no Eclipse GlassFish 7.1 e versões mais recentes. O keytool mantém o formato de keystore existente (JKS em instalações mais antigas, PKCS12 na 7.1+); ambos funcionam bem aqui.
• -dname “CN=…”: os campos do Nome Distinto gravados no CSR. Use os dados legais exatos da sua empresa:

• CN: o FQDN exato que você está protegendo, por exemplo www.seudominio.com, ou um wildcard como *.seudominio.com. Não insira o nome de uma pessoa, mesmo que o texto da solicitação do keytool no modo interativo sugira isso.
• O: o nome legal completo da sua empresa.
• L: o nome completo da cidade (não abrevie).
• ST: o nome completo do estado ou província (não use uma sigla de duas letras).
• C: o código de país ISO de duas letras, por exemplo US, GB, DE.
• OU (Unidade Organizacional): este campo já não é emitido pelas CAs públicas. Deixe-o fora do DN.

O keytool solicita a senha do keystore e a senha da chave. Num domínio GlassFish, a senha do keystore, a senha da chave e a senha mestra do domínio devem ser todas iguais, caso contrário o GlassFish não conseguirá desbloquear a chave na inicialização e o HTTPS falhará. Pressione Enter na solicitação da senha da chave para reutilizar a senha do keystore.

Passo 4: Exporte o CSR com SAN

Mesmo comando da Opção A, executado com a sua nova chave:

keytool -certreq 
  -alias s1as 
  -keystore keystore.jks 
  -file glassfish.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

Digite a senha do keystore. O keytool grava o CSR em glassfish.csr no diretório atual.

Fundamental: mantenha o alias como s1as

O erro mais comum com o keytool no GlassFish é alterar o alias em algum ponto do processo, seja ao gerar a chave ou ao importar o certificado assinado. Surgem dois modos de falha:

• Alias errado na chave. O listener HTTPS do GlassFish está configurado para usar s1as no domain.xml. Se você gerar uma chave sob um alias diferente, o GlassFish não conseguirá encontrá-la e o listener recorrerá ao certificado autoassinado padrão (ou falhará ao iniciar). Se você realmente quiser um alias diferente, terá que atualizar todas as referências a s1as no domain.xml para que correspondam.
• Alias errado na importação. Quando a CA retornar o seu certificado assinado, você deve importá-lo de volta para o mesmo alias que contém a chave privada. Importar sob um alias novo armazena o certificado como uma entrada confiável independente, sem nenhuma chave privada associada, e o TLS não funcionará.

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

• O alias (padrão s1as; mantenha-o).
• O caminho do arquivo do keystore, por exemplo glassfish/domains/domain1/config/keystore.p12 (ou keystore.jks em versões mais antigas).
• A senha do keystore (que deve ser igual à senha mestra do domínio).

Verifique o CSR antes de enviá-lo

Detecte erros de digitação no DN ou SANs ausentes antes que a CA os valide. Imprima o CSR com o keytool:

keytool -printcertreq -file glassfish.csr

Ou, se o OpenSSL estiver instalado, use-o em vez disso:

openssl req -noout -text -in glassfish.csr

Confirme três aspectos na saída: 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 você solicitou (RSA de 2048 bits, ou o que você escolheu). Você também pode colar o CSR no nosso Decodificador de CSR para fazer a mesma verificação num navegador.

Envie o CSR à sua Autoridade Certificadora

Abra o glassfish.csr em qualquer editor de texto. O arquivo é texto simples, começando com —–BEGIN CERTIFICATE REQUEST—– e terminando com —–END CERTIFICATE REQUEST—–. Copie o bloco inteiro, incluindo essas linhas de cabeçalho e rodapé, e cole-o no campo de CSR durante o checkout com a sua CA. No Windows, use Ctrl + A e depois Ctrl + C para copiar todo o texto; no macOS, use Cmd + A e depois Cmd + C.

Depois que a CA validar a sua solicitação e emitir o certificado, continue com como instalar o seu certificado SSL no GlassFish. Você importará a cadeia da CA como confiável, depois importará o certificado assinado de volta para o alias s1as no mesmo arquivo de keystore (keystore.p12 na versão 7.1+, keystore.jks em versões mais antigas), e finalmente apontará o listener HTTPS para esse alias.