Como gerar um CSR no IBM HTTP Server

Este guia mostra como gerar um CSR (Certificate Signing Request) no IBM HTTP Server (IHS), e como fazer o mesmo no HCL Domino (anteriormente IBM Domino).

O IBM HTTP Server armazena chaves e certificados numa base de dados de chaves CMS (um ficheiro .kdb mais um .sth stash), que gere com a ferramenta gráfica IKEYMAN ou com o utilitário de linha de comandos gskcapicmd do IBM Global Security Kit (GSKit) que acompanha o IHS.

Os passos abaixo cobrem ambos os caminhos no IHS 9.0.5.x (a versão suportada atual), e depois os dois fluxos de CSR para o HCL Domino: a clássica base de dados Server Certificate Administration (mantida para instalações legadas) e a moderna tarefa Certificate Manager com certstore.nsf, que a HCL recomenda no Domino 12 e posteriores.

Gerar um CSR no IBM HTTP Server

Se já gerou o seu CSR, avance para como instalar um certificado SSL no IBM HTTP Server.

Pode criar o pedido de duas formas no IHS: através da interface gráfica IKEYMAN (o clássico utilitário de apontar e clicar), ou com o gskcapicmd na linha de comandos. Ambos escrevem a chave privada na mesma base de dados de chaves CMS e produzem um pedido PKCS #10 como um ficheiro .arm que submete à sua Autoridade Certificadora. Escolha a interface gráfica num computador de secretária ou num servidor com ecrã; escolha a CLI numa máquina sem interface gráfica ou quando quiser um script repetível.

Pré-requisitos: o IBM HTTP Server está instalado, o GSKit está no sistema (vem incluído no pacote IHS), e o diretório bin do IHS está no seu PATH ou conhece o seu caminho completo (normalmente /opt/IBM/HTTPServer/bin/ em Linux/AIX, ou C:Program FilesIBMHTTPServerbin em Windows). Também precisa de um diretório de trabalho onde possa escrever a nova base de dados de chaves e o ficheiro CSR, e de um local para registar a palavra-passe da base de dados de chaves.

Método 1. Gerar um CSR com o IKEYMAN (interface gráfica)

Passo 1. Criar uma nova base de dados de chaves CMS (.kdb)

• Inicie o IKEYMAN. No Windows, abra Iniciar > IBM HTTP Server > Start Key Management Utility. No Linux, AIX, ou outro UNIX, execute ikeyman a partir do diretório bin do IHS (por exemplo /opt/IBM/HTTPServer/bin/ikeyman); precisa de um ambiente gráfico X11 funcional.
• No menu, escolha Key Database File > New.
• Na lista pendente Key database type, selecione CMS. Este é o formato que o IBM HTTP Server lê.
• Em File Name, indique um nome para a nova base de dados (por exemplo key.kdb).
• Em Location, aponte para uma pasta que consiga encontrar novamente (por exemplo /opt/IBM/HTTPServer/ssl/ em Linux, ou C:IBMHTTPServerssl em Windows). Clique em OK.
• Defina uma palavra-passe forte, e depois assinale Stash password to a file para que o IKEYMAN escreva um ficheiro stash .sth correspondente junto ao .kdb. O IHS lê o stash no arranque para que não tenha de escrever a palavra-passe cada vez que o servidor arranca. Clique em OK.

O IKEYMAN cria dois ficheiros nessa pasta: a própria base de dados (key.kdb) e o stash (key.sth). Trate ambos como confidenciais. Mantenha as suas permissões de ficheiro restritas (legíveis apenas pelo utilizador IHS) e faça cópias de segurança para um local seguro, porque não conseguirá recuperar a chave privada sem eles.

Passo 2. Criar o pedido de certificado

• Com a nova base de dados aberta, encontre a lista pendente Key database content e altere-a para Personal Certificate Requests.
• Clique em New. Abre-se a caixa de diálogo Create New Key and Certificate Request.

Preencha os campos apenas com caracteres ASCII padrão; letras não latinas invalidam o pedido:

• Key Label: um identificador curto para este certificado dentro da base de dados de chaves, por exemplo www.example.com. Referencia esta etiqueta mais tarde no httpd.conf com a diretiva SSLServerCert.
• Key Size: selecione 2048. Este é o mínimo atual aceite por todas as CAs públicas. Escolha 3072 ou 4096 apenas se a sua política exigir uma chave maior; a contrapartida é um handshake TLS ligeiramente mais lento.
• Signature Algorithm: escolha SHA256WithRSA (ou mais forte, como SHA384WithRSA). Evite qualquer algoritmo com SHA-1; as CAs públicas não emitirão certificados com base nele.
• Common Name: o nome de domínio totalmente qualificado que pretende proteger, por exemplo www.example.com. Para um certificado wildcard, coloque um asterisco antes do domínio principal, por exemplo *.example.com.
• Organization: o nome legal completo da sua empresa, exatamente como está registado. Obrigatório para certificados OV e EV; ignorado para DV.
• Organizational Unit: este atributo está descontinuado para certificados públicos (o CA/Browser Forum eliminou-o gradualmente). Deixe em branco ou insira uma etiqueta curta como IT.
• Locality: o nome completo da cidade (por exemplo Seattle, não SEA).
• State/Province: o nome completo do estado ou província (por exemplo Washington, não WA).
• Country: o código ISO de duas letras do país, por exemplo US, GB, ou DE.
• Subject Alternative Names (SAN): adicione todos os nomes de anfitrião que devem aparecer no certificado, incluindo o valor que colocou em Common Name. Os navegadores modernos ignoram o Common Name e validam apenas com base na lista SAN, pelo que um certificado com múltiplos nomes precisa de entradas aqui.
• Enter the name of a file in which to store the certificate request: um caminho e nome terminado em .arm, por exemplo /opt/IBM/HTTPServer/ssl/www_example_com.arm. Guarde-o na mesma pasta que a base de dados de chaves para que os dois fiquem juntos.

Clique em OK. O IKEYMAN gera o par de chaves dentro da base de dados de chaves, armazena o pedido como uma entrada pendente, e escreve o CSR PKCS #10 no ficheiro .arm que nomeou.

Passo 3. Copiar o CSR e submetê-lo à CA

Abra o ficheiro .arm em qualquer editor de texto (Notepad, vi, nano). Verá um bloco como este:

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

Selecione todo o bloco, incluindo as linhas BEGIN e END, copie-o, e cole-o no campo CSR do seu formulário de encomenda. A chave privada permanece na base de dados de chaves no servidor; apenas o texto do CSR sai da máquina.

Método 2. Gerar um CSR com gskcapicmd (CLI)

O utilitário gskcapicmd (por vezes listado como gskcmd para o wrapper Java, ou como gsk8capicmd_64 em instalações GSKit de 64 bits) faz o mesmo trabalho que o IKEYMAN sem uma sessão gráfica. Execute-o a partir do diretório bin do IHS.

Passo 1. Criar a base de dados de chaves CMS e o ficheiro stash

Escolha uma pasta para a base de dados de chaves, e depois execute:

gskcapicmd -keydb -create 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -type cms 
  -stash

Explicação dos argumentos:

• -db: o caminho completo para o novo ficheiro .kdb.
• -pw: a palavra-passe que protege a base de dados de chaves.
• -type cms: o formato que o IHS lê.
• -stash: escreve um ficheiro stash .sth correspondente junto à base de dados para que o IHS o possa ler sem pedir confirmação no arranque.

Na linha de comandos, a palavra-passe fica visível em listas de processos e no histórico da shell. Depois de a base de dados existir, altere a palavra-passe para uma que não fique registada no histórico com gskcapicmd -keydb -changepw, ou passe a palavra-passe através de uma variável de ambiente e depois remova-a.

Passo 2. Criar o pedido de certificado

Gere o par de chaves e o CSR PKCS #10 num só passo, com entradas SAN para todos os nomes de anfitrião que pretende no certificado:

gskcapicmd -certreq -create 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -label www.example.com 
  -dn "CN=www.example.com,O=Example Inc,L=Seattle,ST=Washington,C=US" 
  -size 2048 
  -sigalg SHA256WithRSA 
  -san_dnsname "www.example.com,example.com" 
  -file /opt/IBM/HTTPServer/ssl/www_example_com.arm

Explicação dos argumentos:

• -label: o identificador deste certificado dentro da base de dados de chaves. Referencie-o mais tarde a partir do httpd.conf com a diretiva SSLServerCert.
• -dn: o Distinguished Name, escrito como uma única cadeia com atributos separados por vírgulas. Use CN= para o FQDN e o código ISO de duas letras em C=.
• -size: 2048 é o mínimo. Use 3072 ou 4096 apenas se a sua política o exigir.
• -sigalg: SHA256WithRSA (ou SHA384WithRSA). Não use SHA-1.
• -san_dnsname: uma lista separada por vírgulas de todos os nomes de anfitrião que devem aparecer no certificado. Inclua o valor do Common Name nesta lista. Os navegadores e a maioria das bibliotecas TLS validam apenas o SAN, não o CN.
• -file: o caminho onde o gskcapicmd escreve o ficheiro CSR .arm.

Se precisar de uma chave ECDSA em vez de RSA, substitua -sigalg SHA256WithRSA por -sigalg SHA256WithECDSA e altere -size para corresponder à curva pretendida (-size 256 para P-256, -size 384 para P-384). As curvas suportadas são secp256r1 (P-256), secp384r1 (P-384), e secp521r1 (P-521). O suporte para ECDSA no IHS só está totalmente disponível através do gskcapicmd; o IKEYMAN não permite escolher ECDSA em versões mais antigas do IHS. Para ECDSA numa versão específica do IHS, siga as orientações de gestão de certificados da IBM.

Passo 3. Listar e verificar o pedido

Confirme que o pedido foi adicionado à base de dados de chaves:

gskcapicmd -certreq -list 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password

Para reler o CSR e verificar o Common Name, as entradas SAN, o tamanho da chave, e o algoritmo de assinatura:

gskcapicmd -certreq -details 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -label www.example.com

Depois abra o ficheiro .arm num editor de texto, copie o bloco completo de BEGIN NEW CERTIFICATE REQUEST até END NEW CERTIFICATE REQUEST, e submeta-o no formulário de encomenda da sua CA.

Verificar o CSR antes de o submeter (opcional)

Se tiver o OpenSSL instalado, execute isto na mesma máquina para confirmar o assunto, a lista SAN, e o tamanho da chave:

openssl req -noout -text -in www_example_com.arm

Prefere uma ferramenta online? Cole o conteúdo do pedido no CSR Decoder da SSL Dragon para ler novamente os mesmos detalhes. Confirme que o Common Name corresponde ao nome de anfitrião que os clientes utilizarão e que todos os nomes de anfitrião necessários aparecem em Subject Alternative Name.

Depois de a CA emitir o seu certificado

O certificado assinado tem de ser importado de volta para a mesma base de dados de chaves que produziu o CSR, contra a mesma etiqueta. Receba-o com a CLI:

gskcapicmd -cert -receive 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -file www_example_com.crt

Ou faça o mesmo no IKEYMAN em Personal Certificates > Receive. Adicione primeiro os certificados raiz e intermédio como certificados de assinante, depois atualize o httpd.conf com as diretivas KeyFile e SSLServerCert e reinicie o IHS. O procedimento completo está descrito em como instalar um certificado SSL no IBM HTTP Server.

Gerar um CSR no HCL Domino

Nota: o IBM Domino é agora o HCL Domino. A HCL concluiu a aquisição do portefólio de colaboração da IBM (incluindo Notes/Domino) a 1 de julho de 2019. No Domino 12 e posteriores, a HCL recomenda a tarefa Certificate Manager (com certstore.nsf e documentos TLS Credentials) para todo o trabalho TLS novo. A clássica base de dados Server Certificate Administration (CERTSRV.NSF) ainda funciona para instalações legadas e está documentada abaixo, mas as implementações novas devem usar o Certificate Manager.

Método A. Criar um CSR com o Certificate Manager (Domino 12+ / 14.x)

• Adicione a tarefa CertMgr no seu servidor designado como Certificate Manager para que crie o certstore.nsf. Em cada servidor Domino que precise de ler chaves TLS, execute também o CertMgr para que a base de dados replique.
• Abra o certstore.nsf, vá a TLS Credentials, e clique em Add TLS Credentials.
• Host names: introduza o FQDN exato que os clientes utilizarão, e adicione todos os nomes de anfitrião adicionais como Subject Alternative Name.
• Servers with access: selecione os servidores Domino que devem poder ler a chave privada.
• Certificate Provider: escolha Manual para qualquer CA de terceiros. (Escolha Let’s Encrypt apenas se quiser que o CertMgr obtenha automaticamente um certificado gratuito emitido via ACME.)
• Key type: escolha RSA ou ECDSA.
• RSA: selecione 2048 bits (ou maior se a sua política o exigir).
• ECDSA: escolha uma curva (P-256 ou P-384; P-384 é a predefinição listada).
• Clique em Submit Request. O CertMgr gera o par de chaves, assina o CSR, e o documento passa para Status = Waiting.
• Abra o documento, copie o valor de Certificate signing request (CSR) (ou use a ação Copy CSR que aparece após o processamento), e cole o bloco PEM no formulário de encomenda da sua CA.

A chave privada permanece dentro do certstore.nsf, encriptada para os servidores que autorizou. Nunca a exporta. Quando a CA emitir o seu certificado, cole o certificado assinado (mais a cadeia emissora) de volta no mesmo documento TLS Credentials e o CertMgr instala-o automaticamente. A referência completa está na documentação do Certificate Manager da HCL.

Método B. Server Certificate Administration clássico (Domino legado)

Use este método apenas em versões do Domino que ainda dependam de ficheiros key ring (.kyr + .sth). A HCL marca-o como legado no Domino 12 e posteriores.

• No cliente Domino Administrator, abra Server Certificate Administration.
• Escolha Create Key Ring. Introduza um nome para o key ring e uma palavra-passe forte.
• Key Size: selecione 2048 bits.
• Preencha o Distinguished Name:
• Common Name: o FQDN que pretende proteger, por exemplo www.example.com.
• Organization: o nome legal completo da sua empresa.
• Organizational Unit: deixe em branco ou introduza uma etiqueta curta como IT (o atributo está descontinuado para certificados públicos).
• City or Locality: o nome completo da cidade, por exemplo Seattle.
• State or Province: o nome completo do estado, por exemplo Washington.
• Country: o código ISO de duas letras, por exemplo US.
• Reveja os detalhes e clique em Continue. O Domino cria o ficheiro key ring.
• Escolha Create Certificate Request. Em Method, escolha Paste into form on CA’s site. O Domino mostra o texto do CSR.
• Copie todo o bloco do CSR (incluindo as linhas BEGIN e END) e cole-o no formulário de encomenda da sua CA.

Os ficheiros key ring clássicos não suportam entradas SAN através desta caixa de diálogo. Se precisar de um certificado com múltiplos nomes, mude para o Certificate Manager (Método A) ou gere o CSR fora do servidor.

Perguntas Frequentes