Como Gerar um CSR no Node.js

Este tutorial mostra como gerar um CSR para uma aplicação Node.js. O Node.js não tem uma ferramenta integrada de geração de CSR, por isso deve criar a chave privada e o Certificate Signing Request com o OpenSSL na máquina que irá executar o Node, submeter o CSR à sua Autoridade de Certificação e, em seguida, carregar o certificado emitido na sua aplicação com fs.readFileSync() e https.createServer().

Os passos abaixo funcionam em qualquer sistema operativo que inclua o OpenSSL, o que abrange todas as distribuições atuais de Linux, macOS e Windows (através dos binários oficiais do OpenSSL ou do Git Bash). As versões modernas do OpenSSL assinam os pedidos com SHA-256 por predefinição, portanto não é necessário adicionar uma flag de digest.

Passo 1: Certifique-se de que o OpenSSL está instalado

Verifique se o OpenSSL está disponível na máquina que irá executar a sua aplicação Node.js:

openssl version

Deverá ver uma linha como OpenSSL 3.0.x ou mais recente. Se o comando não for encontrado, instale-o para a sua plataforma:

• Debian, Ubuntu: sudo apt update && sudo apt install openssl
• RHEL, AlmaLinux, Rocky Linux, Amazon Linux: sudo dnf install openssl (ou sudo yum install openssl em versões mais antigas)
• macOS: o OpenSSL (LibreSSL em algumas versões, OpenSSL 3 se instalado via Homebrew) já está presente no Terminal. Para instalar a versão oficial: brew install openssl@3.
• Windows: instale os binários oficiais do OpenSSL, ou utilize o Git Bash, que já vem com o OpenSSL pré-instalado.

Passo 2: Gere a chave privada e o CSR

Gere a chave e o CSR na máquina que irá executar o Node.js. A chave privada é criada junto com o CSR e deve permanecer nessa máquina. Executar estes comandos noutro local e depois copiar a chave anula o propósito de ter uma chave privada.

Execute o seguinte comando. Este cria uma chave privada RSA de 2048 bits e um CSR correspondente num único passo, com o assunto e os Subject Alternative Names (SANs) fornecidos diretamente para que o OpenSSL não pare para fazer perguntas:

openssl req -new -newkey rsa:2048 -nodes 
-keyout yourdomain.key 
-out yourdomain.csr 
-subj "/C=US/ST=YourState/L=YourCity/O=YourCompany/CN=yourdomain.com" 
-addext "subjectAltName=DNS:yourdomain.com,DNS:www.yourdomain.com"

O que faz cada parte:

• -newkey rsa:2048 gera uma nova chave RSA de 2048 bits. 2048 bits é o mínimo atual aceite pelas CAs públicas; pode usar rsa:4096 para uma chave maior, ou optar por ECDSA (ver abaixo).
• -nodes deixa a chave privada sem encriptação, para que o Node.js a possa ler no arranque sem pedir uma frase-passe. O módulo https do Node suporta uma opção passphrase para uma chave encriptada, mas a frase-passe ainda tem de vir de algum sítio na máquina (um ficheiro de configuração, uma variável de ambiente ou um gestor de segredos).
• -keyout e -out nomeiam os ficheiros da chave privada e do CSR.
• -subj fornece o assunto do certificado. Coloque aqui o nome real da sua empresa, o estado e a cidade, não os valores de exemplo. CN (Common Name) é o seu domínio principal.
• -addext “subjectAltName=…” lista todos os nomes de anfitrião que o certificado deve cobrir. As CAs públicas validam com base na lista de SAN, por isso inclua também aqui o Common Name. A flag -addext requer OpenSSL 1.1.1 ou mais recente, versão que qualquer sistema operativo atual já inclui.

Substitua yourdomain.com pelo seu domínio real em todas as ocorrências. Para cobrir nomes de anfitrião adicionais, adicione-os à lista de SAN separados por vírgulas, por exemplo DNS:api.yourdomain.com. Para um wildcard, inclua tanto o wildcard como o domínio simples: DNS:*.yourdomain.com,DNS:yourdomain.com.

Se preferir uma chave ECDSA (mais pequena e mais rápida, com P-256 amplamente suportado), gere a chave e o CSR desta forma:

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -pkeyopt ec_param_enc:named_curve -nodes 
-keyout yourdomain.key 
-out yourdomain.csr 
-subj "/C=US/ST=YourState/L=YourCity/O=YourCompany/CN=yourdomain.com" 
-addext "subjectAltName=DNS:yourdomain.com,DNS:www.yourdomain.com"

Modo interativo (sem -subj)

Se preferir que o OpenSSL lhe peça cada campo individualmente, retire a flag -subj:

openssl req -new -newkey rsa:2048 -nodes 
-keyout yourdomain.key -out yourdomain.csr 
-addext "subjectAltName=DNS:yourdomain.com,DNS:www.yourdomain.com"

O OpenSSL irá solicitar os seguintes detalhes:

• Country Name (C): o código de país ISO de duas letras da sua organização (por exemplo, US).
• State or Province Name (S): o nome completo do estado ou província onde a sua empresa está registada (por exemplo, California). Não abrevie.
• Locality Name (L): a cidade onde a sua empresa está registada (por exemplo, San Jose).
• Organization Name (O): o nome legal da sua empresa (por exemplo, GPI Holding LLC). Para um certificado DV (Domain Validated), deixe em branco e pressione Enter.
• Organizational Unit Name (OU): obsoleto desde setembro de 2022 e ignorado pelas CAs públicas. Deixe em branco.
• Common Name (CN): o nome de domínio totalmente qualificado (FQDN) que está a proteger, por exemplo yourdomain.com. Para um wildcard, use *.yourdomain.com.
• Email Address: opcional. Deixe em branco.
• A challenge password: obsoleto. Deixe em branco.

Passo 3: Localize e proteja os seus ficheiros

Liste o diretório atual para confirmar que ambos os ficheiros foram criados:

ls

Deverá ver dois novos ficheiros:

• yourdomain.key: a sua chave privada. Mantenha-a no servidor, faça cópias de segurança de forma segura e nunca a envie a ninguém, incluindo à Autoridade de Certificação. Quem detiver a chave pode fazer-se passar pelo seu site.
• yourdomain.csr: o seu Certificate Signing Request. Este é o ficheiro que submete ao fornecedor de SSL.

No Linux ou macOS, defina permissões estritas na chave privada imediatamente, para que apenas o utilizador que executa o Node.js a possa ler:

chmod 600 yourdomain.key

Se o Node.js for executado sob uma conta de serviço dedicada (por exemplo, node ou www-data), defina também o proprietário para que o processo possa ler a chave:

sudo chown node:node yourdomain.key

Passo 4: Verifique o CSR (opcional, mas recomendado)

Antes de o submeter, verifique se o CSR contém o assunto e os SANs corretos e se a sua assinatura é válida. Isto decodifica o pedido localmente com o OpenSSL:

openssl req -noout -text -verify -in yourdomain.csr

Confirme que a linha Subject apresenta os seus dados, que X509v3 Subject Alternative Name lista todos os nomes de anfitrião esperados e que a verificação da assinatura imprime verify OK. O algoritmo de assinatura deverá ser sha256WithRSAEncryption (ou ecdsa-with-SHA256 para uma chave ECDSA). Se preferir não usar a linha de comandos, cole o CSR no nosso descodificador de CSR online para ler os mesmos campos num navegador.

Passo 5: Submeta o seu CSR

Para copiar o CSR para a sua encomenda, imprima o seu conteúdo:

cat yourdomain.csr

Verá um bloco de texto semelhante a este:

-----BEGIN CERTIFICATE REQUEST-----
MIIBozCB... (a long string of characters)
-----END CERTIFICATE REQUEST-----

Copie o bloco completo, incluindo as linhas —–BEGIN CERTIFICATE REQUEST—– e —–END CERTIFICATE REQUEST—– (cada marcador tem cinco hífenes de cada lado). Esse bloco completo é o seu CSR. Cole-o no formulário de encomenda durante a sua compra, e mantenha a chave privada correspondente no servidor.

Se preferir não usar a linha de comandos, também pode construir o pedido com o nosso Gerador de CSR online. Note que este gera a chave privada no seu navegador, por isso guarde essa chave você mesmo e transfira-a para o servidor Node.js.

O que acontece depois de a CA emitir o certificado

Depois de a CA validar o CSR e emitir o certificado, receberá normalmente o certificado do servidor (um ficheiro .crt com o nome do seu domínio), juntamente com um ou mais certificados intermédios, por vezes agrupados num ficheiro .ca-bundle. O Node.js carrega estes ficheiros em JavaScript: concatene o certificado do servidor e os intermédios num único ficheiro fullchain.crt, depois leia-o com fs.readFileSync() e passe-o a https.createServer():

const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync('/path/to/yourdomain.key'),
  cert: fs.readFileSync('/path/to/fullchain.crt'),
  minVersion: 'TLSv1.2'
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('Welcome to a Node.js HTTPS servern');
}).listen(443);

Este padrão de fullchain é o que a maioria das configurações em produção utiliza. O tutorial completo (incluindo um exemplo com módulos ES, uma abordagem alternativa com um array ca:, e um exemplo com Express) está descrito no nosso tutorial de instalação de SSL no Node.js.

Uma nota sobre implementações em produção. Em 2026, a maioria das aplicações Node.js que lidam com tráfego público funciona atrás de um proxy inverso ou de um balanceador de carga na cloud (NGINX, HAProxy, Caddy, AWS ALB, Cloudflare, Fastly) que termina o TLS na periferia e reencaminha HTTP simples ou HTTP/2 para o Node numa porta local elevada. Nesse padrão, o certificado (e o CSR que gerou acima) fica no proxy ou no balanceador de carga, e não no próprio processo Node. Permitir que o Node.js termine o TLS diretamente é perfeitamente aceitável para desenvolvimento, serviços internos e implementações de pequena escala; para uma aplicação de produção pública, terminar o TLS na periferia é o formato mais comum.