{"id":70,"date":"2026-06-12T16:59:40","date_gmt":"2026-06-12T16:59:40","guid":{"rendered":"https:\/\/shattered.io\/pt\/2026\/06\/12\/mtls-node-js-tls-13\/"},"modified":"2026-06-12T17:01:02","modified_gmt":"2026-06-12T17:01:02","slug":"mtls-node-js-tls-13","status":"publish","type":"post","link":"https:\/\/shattered.io\/pt\/2026\/06\/12\/mtls-node-js-tls-13\/","title":{"rendered":"mTLS em Node.js: TLS 1.3 em 12 Passos [2026]"},"content":{"rendered":"\n

O modelo de seguran\u00e7a “confia na rede interna” morreu. Em 2026, qualquer servi\u00e7o que aceite liga\u00e7\u00f5es sem provar quem est\u00e1 do outro lado \u00e9 um alvo. O mTLS em Node.js<\/strong> resolve isto ao exigir que cliente e servidor apresentem certificados v\u00e1lidos antes de trocar um \u00fanico byte de dados aplicacionais. N\u00e3o \u00e9 um cadeado decorativo, \u00e9 autentica\u00e7\u00e3o criptogr\u00e1fica nas duas dire\u00e7\u00f5es.<\/p>\n\n\n\n

Este tutorial leva-te do zero a um sistema mTLS completo e funcional, com TLS 1.3, em 12 passos. Vais criar a tua pr\u00f3pria Autoridade Certificadora, emitir certificados de servidor e de cliente, construir um servidor Node.js que recusa qualquer cliente n\u00e3o autenticado, escrever um cliente que apresenta o seu certificado, e mapear a identidade do certificado para permiss\u00f5es reais da aplica\u00e7\u00e3o. No fim tens um projeto que podes adaptar para APIs internas, comunica\u00e7\u00e3o entre microsservi\u00e7os ou acesso a sistemas sens\u00edveis.<\/p>\n\n\n\n

Tempo estimado: 45 a 60 minutos. Todo o c\u00f3digo usa apenas m\u00f3dulos nativos do Node.js (node:tls<\/code>, node:https<\/code>, node:crypto<\/code>) e a ferramenta openssl<\/code>. Sem depend\u00eancias externas pesadas, sem frameworks criptogr\u00e1ficos opacos.<\/p>\n\n\n\n

mTLS em Node.js: porque \u00e9 o padr\u00e3o zero-trust em 2026<\/h2>\n\n\n\n

O TLS normal (o que protege o HTTPS que usas todos os dias) autentica apenas o servidor. O teu navegador verifica que banco.pt<\/code> \u00e9 mesmo o banco, mas o banco n\u00e3o tem como saber, ao n\u00edvel do TLS, quem \u00e9s tu. A autentica\u00e7\u00e3o do utilizador acontece depois, com palavra-passe ou token, j\u00e1 dentro da sess\u00e3o cifrada.<\/p>\n\n\n\n

O TLS m\u00fatuo, ou mTLS, fecha esse buraco. Ambos os lados apresentam um certificado e ambos verificam o certificado do outro contra uma Autoridade Certificadora (CA) de confian\u00e7a. Se o cliente n\u00e3o tiver um certificado v\u00e1lido emitido pela CA esperada, a liga\u00e7\u00e3o cai durante o handshake. Nenhum pedido chega sequer ao c\u00f3digo da aplica\u00e7\u00e3o. Isto torna o mTLS a base pr\u00e1tica da arquitetura zero-trust, onde nada \u00e9 confi\u00e1vel s\u00f3 por estar “dentro” da rede.<\/p>\n\n\n\n

Em 2026, tr\u00eas for\u00e7as empurram o mTLS para a corrente principal. Primeiro, a velocidade dos ataques: quando um intruso entra na rede, mover-se lateralmente entre servi\u00e7os que confiam cegamente uns nos outros \u00e9 trivial, e o mTLS bloqueia esse movimento. Segundo, as malhas de servi\u00e7o (service meshes) como o Istio e o Linkerd usam mTLS por omiss\u00e3o, normalizando o padr\u00e3o. Terceiro, regula\u00e7\u00e3o como a NIS2 pressiona organiza\u00e7\u00f5es em Portugal e na UE a demonstrar controlo de acesso forte entre sistemas. O mTLS d\u00e1 uma resposta audit\u00e1vel.<\/p>\n\n\n\n

O Node.js \u00e9 uma escolha natural para implementar mTLS porque o suporte est\u00e1 embutido. O m\u00f3dulo node:tls<\/code> exp\u00f5e diretamente as op\u00e7\u00f5es que precisas: requestCert<\/code>, rejectUnauthorized<\/code>, ca<\/code>, minVersion<\/code>. N\u00e3o precisas de um proxy reverso a fazer o trabalho, embora possas combinar os dois. Segundo a documenta\u00e7\u00e3o oficial do m\u00f3dulo TLS<\/a>, estas primitivas dependem do OpenSSL inclu\u00eddo na build do Node, por isso o comportamento exato dos algoritmos segue as capacidades do OpenSSL da tua plataforma.<\/p>\n\n\n\n

O que vais construir: arquitetura do projeto mTLS<\/h2>\n\n\n\n

Antes de escrever c\u00f3digo, conv\u00e9m ver o mapa. O projeto tem quatro pe\u00e7as que trabalham juntas. A CA raiz \u00e9 a \u00e2ncora de confian\u00e7a: assina os outros certificados e ambos os lados confiam nela. O certificado do servidor identifica o servidor. O certificado do cliente identifica cada cliente autorizado. O servidor e o cliente Node.js trocam e verificam tudo isto durante o handshake TLS 1.3.<\/p>\n\n\n\n

Componente<\/th>Ficheiro<\/th>Fun\u00e7\u00e3o<\/th>Quem confia nele<\/th><\/tr><\/thead>
CA raiz<\/td>ca-cert.pem<\/code><\/td>Assina e valida todos os certificados<\/td>Servidor e cliente<\/td><\/tr>
Chave da CA<\/td>ca-key.pem<\/code><\/td>Assina novos certificados (segredo m\u00e1ximo)<\/td>Apenas o operador<\/td><\/tr>
Certificado do servidor<\/td>server-cert.pem<\/code><\/td>Prova a identidade do servidor<\/td>Cliente<\/td><\/tr>
Certificado do cliente<\/td>client-cert.pem<\/code><\/td>Prova a identidade do cliente<\/td>Servidor<\/td><\/tr>
Servidor Node<\/td>server.js<\/code><\/td>Exige e valida o certificado do cliente<\/td>(servi\u00e7o)<\/td><\/tr>
Cliente Node<\/td>client.js<\/code><\/td>Apresenta o seu certificado ao servidor<\/td>(servi\u00e7o)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

O fluxo \u00e9 direto. O cliente liga-se ao servidor e envia o seu certificado. O servidor verifica esse certificado contra a CA raiz. Em paralelo, o cliente verifica o certificado do servidor contra a mesma CA. Se ambas as verifica\u00e7\u00f5es passarem, o t\u00fanel TLS 1.3 abre e a aplica\u00e7\u00e3o corre. Se qualquer uma falhar, a liga\u00e7\u00e3o termina antes de qualquer pedido HTTP. \u00c9 exatamente este comportamento “falha fechada” que torna o mTLS em Node.js t\u00e3o robusto.<\/p>\n\n\n\n

Pr\u00e9-requisitos e vers\u00f5es necess\u00e1rias<\/h2>\n\n\n\n

Este tutorial assume uma base de runtime atual e suportada. As linhas LTS do Node.js receberam corre\u00e7\u00f5es de seguran\u00e7a relevantes para TLS na ronda de janeiro de 2026, incluindo melhorias no parsing de certificados, por isso usa uma vers\u00e3o LTS atualizada e n\u00e3o uma build antiga esquecida no port\u00e1til. Consulta o calend\u00e1rio oficial de vers\u00f5es do Node.js<\/a> para confirmar qual a LTS ativa.<\/p>\n\n\n\n

Ferramenta<\/th>Vers\u00e3o recomendada<\/th>Como verificar<\/th>Notas<\/th><\/tr><\/thead>
Node.js<\/td>24 LTS (ou 22 LTS)<\/td>node --version<\/code><\/td>Usa sempre uma linha LTS suportada<\/td><\/tr>
npm<\/td>Inclu\u00eddo no Node<\/td>npm --version<\/code><\/td>S\u00f3 para inicializar o projeto<\/td><\/tr>
OpenSSL<\/td>3.x<\/td>openssl version<\/code><\/td>Gera CA e certificados<\/td><\/tr>
curl<\/td>Recente com TLS 1.3<\/td>curl --version<\/code><\/td>Opcional, para testes<\/td><\/tr>
Sistema operativo<\/td>Linux, macOS ou WSL2<\/td>(qualquer)<\/td>Os comandos assumem shell POSIX<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Confirma tudo antes de avan\u00e7ar. Abre o terminal e corre as tr\u00eas verifica\u00e7\u00f5es principais:<\/p>\n\n\n\n

node --version\n# Esperado: v24.x.x ou v22.x.x\n\nopenssl version\n# Esperado: OpenSSL 3.x.x\n\nnpm --version\n# Qualquer versao recente incluida no Node serve<\/code><\/pre>\n\n\n\n
Se o node --version<\/code> mostrar uma vers\u00e3o antiga (18 ou inferior), atualiza antes de continuar. As op\u00e7\u00f5es de TLS 1.3 e o comportamento de valida\u00e7\u00e3o de certificados s\u00e3o mais previs\u00edveis nas linhas recentes. Conhecimentos \u00fateis mas n\u00e3o obrigat\u00f3rios: saber o que \u00e9 uma chave p\u00fablica e o conceito de cadeia de confian\u00e7a. Se precisares de uma revis\u00e3o, o nosso artigo sobre HTTPS e TLS<\/a> explica o cadeado e o handshake em linguagem simples.<\/p>\n\n\n\n
Passo 1 e 2: inicializar o projeto e criar a CA raiz<\/h2>\n\n\n\n
Come\u00e7a por criar a estrutura. Vamos manter os certificados numa pasta certs<\/code> separada do c\u00f3digo, um h\u00e1bito que evita commits acidentais de chaves privadas para o Git.<\/p>\n\n\n\n
mkdir mtls-node && cd mtls-node\nnpm init -y\nmkdir certs\necho \"certs\/\" > .gitignore\necho \"node_modules\/\" >> .gitignore<\/code><\/pre>\n\n\n\n
Agora cria a Autoridade Certificadora raiz. A CA \u00e9 o cora\u00e7\u00e3o da confian\u00e7a: a sua chave privada assina todos os outros certificados, e o seu certificado p\u00fablico \u00e9 o que servidor e cliente usam para verificar tudo. Gera primeiro a chave privada da CA com uma curva el\u00edptica moderna.<\/p>\n\n\n\n
# Chave privada da CA (curva eliptica P-256, moderna e rapida)\nopenssl ecparam -name prime256v1 -genkey -noout -out certs\/ca-key.pem\n\n# Certificado raiz autoassinado, valido 10 anos\nopenssl req -new -x509 -sha256 -days 3650 \\\n  -key certs\/ca-key.pem \\\n  -out certs\/ca-cert.pem \\\n  -subj \"\/C=PT\/O=Exemplo Lda\/CN=mTLS Demo Root CA\"<\/code><\/pre>\n\n\n\n
Repara em duas escolhas. Usamos prime256v1<\/code> (tamb\u00e9m conhecida por P-256) em vez de RSA porque as chaves el\u00edpticas s\u00e3o mais pequenas e r\u00e1pidas para o mesmo n\u00edvel de seguran\u00e7a. A documenta\u00e7\u00e3o do Node recomenda curvas de pelo menos 224 bits para ECDSA, e a P-256 fica confortavelmente acima disso. Usamos -sha256<\/code> porque o SHA-1 e o MD5 j\u00e1 n\u00e3o s\u00e3o aceit\u00e1veis para assinaturas, um ponto que tanto a documenta\u00e7\u00e3o do Node como a hist\u00f3ria da colis\u00e3o SHAttered do SHA-1<\/a> deixam claro.<\/p>\n\n\n\n
A chave ca-key.pem<\/code> \u00e9 o segredo mais valioso de todo o sistema. Quem a tiver pode emitir certificados que o teu servidor vai aceitar. Em produ\u00e7\u00e3o, esta chave fica num m\u00f3dulo de hardware (HSM) ou num cofre de segredos, nunca no disco de um servidor de aplica\u00e7\u00e3o.<\/p>\n\n\n\n
Passo 3 e 4: emitir os certificados de servidor e de cliente<\/h2>\n\n\n\n
Com a CA pronta, emitimos dois certificados assinados por ela. Cada um precisa de tr\u00eas passos: gerar a chave privada, criar um pedido de assinatura (CSR) e assin\u00e1-lo com a CA. Come\u00e7a pelo servidor.<\/p>\n\n\n\n
# 1. Chave privada do servidor\nopenssl ecparam -name prime256v1 -genkey -noout -out certs\/server-key.pem\n\n# 2. Pedido de assinatura (CSR), CN = localhost para testes\nopenssl req -new -sha256 \\\n  -key certs\/server-key.pem \\\n  -out certs\/server.csr \\\n  -subj \"\/C=PT\/O=Exemplo Lda\/CN=localhost\"\n\n# 3. Assinar com a CA, com SAN para localhost (obrigatorio em clientes modernos)\nopenssl x509 -req -sha256 -days 365 \\\n  -in certs\/server.csr \\\n  -CA certs\/ca-cert.pem -CAkey certs\/ca-key.pem -CAcreateserial \\\n  -out certs\/server-cert.pem \\\n  -extfile <(printf \"subjectAltName=DNS:localhost,IP:127.0.0.1\")<\/code><\/pre>\n\n\n\n
O Subject Alternative Name (SAN) \u00e9 cr\u00edtico. Clientes TLS modernos, incluindo o Node.js, ignoram o campo CN e validam o nome do host contra o SAN. Se esqueceres o SAN, o cliente recusa o certificado com um erro de hostname, mesmo que tudo o resto esteja correto. Esta \u00e9 uma das armadilhas mais comuns e voltamos a ela mais \u00e0 frente.<\/p>\n\n\n\n
Agora o certificado do cliente. O processo \u00e9 igual, mas o nome comum (CN) identifica o cliente, n\u00e3o um host. Vamos usar esse CN mais tarde para decidir permiss\u00f5es. Pensa no CN como o “nome de utilizador” criptogr\u00e1fico do cliente.<\/p>\n\n\n\n
# 1. Chave privada do cliente\nopenssl ecparam -name prime256v1 -genkey -noout -out certs\/client-key.pem\n\n# 2. CSR, CN identifica o cliente (vamos usa-lo para autorizacao)\nopenssl req -new -sha256 \\\n  -key certs\/client-key.pem \\\n  -out certs\/client.csr \\\n  -subj \"\/C=PT\/O=Exemplo Lda\/CN=servico-faturacao\"\n\n# 3. Assinar com a CA\nopenssl x509 -req -sha256 -days 365 \\\n  -in certs\/client.csr \\\n  -CA certs\/ca-cert.pem -CAkey certs\/ca-key.pem -CAcreateserial \\\n  -out certs\/client-cert.pem<\/code><\/pre>\n\n\n\n
Confirma que tudo foi assinado corretamente inspecionando um certificado. O comando seguinte mostra o emissor (deve ser a tua CA), o sujeito e o per\u00edodo de validade. Consulta a p\u00e1gina de manual do openssl-req<\/a> para todas as op\u00e7\u00f5es dispon\u00edveis.<\/p>\n\n\n\n
openssl x509 -in certs\/client-cert.pem -noout -subject -issuer -dates\n\n# Saida esperada:\n# subject=C=PT, O=Exemplo Lda, CN=servico-faturacao\n# issuer=C=PT, O=Exemplo Lda, CN=mTLS Demo Root CA\n# notBefore=Mar  3 10:00:00 2026 GMT\n# notAfter=Mar  3 10:00:00 2027 GMT<\/code><\/pre>\n\n\n\n
Passo 5: o servidor TLS 1.3 em Node.js<\/h2>\n\n\n\n
Chegou o c\u00f3digo. Cria um ficheiro server.js<\/code>. Come\u00e7amos com um servidor HTTPS que carrega a sua chave e certificado, mas ainda sem exigir o certificado do cliente. Vamos adicionar a exig\u00eancia no passo seguinte, para veres a diferen\u00e7a.<\/p>\n\n\n\n
\/\/ server.js\nimport https from 'node:https';\nimport fs from 'node:fs';\n\nconst options = {\n  key: fs.readFileSync('certs\/server-key.pem'),\n  cert: fs.readFileSync('certs\/server-cert.pem'),\n  ca: fs.readFileSync('certs\/ca-cert.pem'),\n\n  \/\/ Forcar TLS 1.3, sem fallback para versoes antigas\n  minVersion: 'TLSv1.3',\n  maxVersion: 'TLSv1.3',\n};\n\nconst server = https.createServer(options, (req, res) => {\n  res.writeHead(200, { 'Content-Type': 'application\/json' });\n  res.end(JSON.stringify({ mensagem: 'Ligacao TLS 1.3 estabelecida' }));\n});\n\nserver.listen(8443, () => {\n  console.log('Servidor mTLS a escutar em https:\/\/localhost:8443');\n});<\/code><\/pre>\n\n\n\n
As linhas minVersion<\/code> e maxVersion<\/code> a ‘TLSv1.3’ s\u00e3o a tua primeira linha de defesa. Elas dizem ao Node para recusar qualquer liga\u00e7\u00e3o que n\u00e3o fale TLS 1.3. Isto elimina de uma vez toda uma classe de ataques contra vers\u00f5es antigas do protocolo (TLS 1.0, 1.1 e os pontos fracos do 1.2 mal configurado). O TLS 1.3, definido no RFC 8446<\/a>, removeu cipher suites inseguras e simplificou o handshake.<\/p>\n\n\n\n
Repara tamb\u00e9m que o ficheiro usa import<\/code> em vez de require<\/code>. O ecossistema Node de 2026 \u00e9 cada vez mais ESM-first. Para isto funcionar, adiciona \"type\": \"module\"<\/code> ao teu package.json<\/code>. Arranca o servidor com node server.js<\/code> e confirma que v\u00eas a mensagem de escuta.<\/p>\n\n\n\n
Passo 6: exigir e validar o certificado do cliente<\/h2>\n\n\n\n
Agora transformamos um servidor HTTPS normal num servidor mTLS. Duas op\u00e7\u00f5es fazem a magia: requestCert<\/code> pede o certificado ao cliente, e rejectUnauthorized<\/code> recusa a liga\u00e7\u00e3o se esse certificado n\u00e3o for v\u00e1lido contra a CA. Atualiza o objeto options<\/code>.<\/p>\n\n\n\n
const options = {\n  key: fs.readFileSync('certs\/server-key.pem'),\n  cert: fs.readFileSync('certs\/server-cert.pem'),\n  ca: fs.readFileSync('certs\/ca-cert.pem'),\n\n  minVersion: 'TLSv1.3',\n  maxVersion: 'TLSv1.3',\n\n  \/\/ O coracao do mTLS:\n  requestCert: true,        \/\/ pede o certificado ao cliente\n  rejectUnauthorized: true, \/\/ recusa se o certificado nao for valido\n};<\/code><\/pre>\n\n\n\n
Com rejectUnauthorized: true<\/code>, qualquer cliente sem um certificado assinado pela tua CA \u00e9 rejeitado durante o handshake. O callback do servidor nunca chega a correr para esses clientes. Esta \u00e9 a propriedade “falha fechada” do mTLS bem feito: a seguran\u00e7a n\u00e3o depende de o teu c\u00f3digo de aplica\u00e7\u00e3o lembrar-se de verificar nada.<\/p>\n\n\n\n
Inspecionar o certificado do cliente autenticado<\/h3>\n\n\n\n
Quando um cliente v\u00e1lido se liga, queres saber quem \u00e9. O Node exp\u00f5e o certificado do par atrav\u00e9s de req.socket.getPeerCertificate()<\/code> e o estado de valida\u00e7\u00e3o atrav\u00e9s de req.socket.authorized<\/code>. Vamos usar isto para registar a identidade de cada pedido.<\/p>\n\n\n\n
const server = https.createServer(options, (req, res) => {\n  const cert = req.socket.getPeerCertificate();\n  const autorizado = req.socket.authorized;\n\n  \/\/ Com rejectUnauthorized:true so chegamos aqui se autorizado for true,\n  \/\/ mas verificamos na mesma por defesa em profundidade.\n  if (!autorizado || !cert || !cert.subject) {\n    res.writeHead(401);\n    res.end(JSON.stringify({ erro: 'Certificado de cliente em falta ou invalido' }));\n    return;\n  }\n\n  const cliente = cert.subject.CN;\n  console.log(`Pedido autenticado de: ${cliente}`);\n\n  res.writeHead(200, { 'Content-Type': 'application\/json' });\n  res.end(JSON.stringify({ mensagem: `Ola, ${cliente}`, autenticado: true }));\n});<\/code><\/pre>\n\n\n\n
O campo cert.subject.CN<\/code> cont\u00e9m o “servico-faturacao” que definimos quando emitimos o certificado do cliente. A partir daqui, a identidade do cliente \u00e9 um facto criptogr\u00e1fico, n\u00e3o uma afirma\u00e7\u00e3o que ele faz num cabe\u00e7alho HTTP que poderia falsificar.<\/p>\n\n\n\n
Passo 7: mapear identidade e autoriza\u00e7\u00e3o ao n\u00edvel da aplica\u00e7\u00e3o<\/h2>\n\n\n\n
Aqui est\u00e1 o erro conceptual mais perigoso do mTLS: pensar que autentica\u00e7\u00e3o \u00e9 o mesmo que autoriza\u00e7\u00e3o. N\u00e3o \u00e9. O mTLS prova quem<\/em> \u00e9 o cliente. Mas decidir o que<\/em> esse cliente pode fazer \u00e9 trabalho da tua aplica\u00e7\u00e3o. Um certificado v\u00e1lido n\u00e3o deve dar acesso a tudo automaticamente.<\/p>\n\n\n\n
A documenta\u00e7\u00e3o do Node refor\u00e7a este ponto: o certificado identifica o cliente, mas o servidor ainda deve mapear essa identidade para permiss\u00f5es, escopos ou pol\u00edticas internas. Vamos construir uma tabela simples de autoriza\u00e7\u00e3o que mapeia o CN do certificado para um papel.<\/p>\n\n\n\n
\/\/ Mapa de autorizacao: CN do certificado -> permissoes\nconst POLITICAS = {\n  'servico-faturacao': { papel: 'escrita', rotas: ['\/faturas'] },\n  'servico-relatorios': { papel: 'leitura', rotas: ['\/faturas', '\/relatorios'] },\n};\n\nfunction autorizar(cn, rota) {\n  const politica = POLITICAS[cn];\n  if (!politica) return false;\n  return politica.rotas.includes(rota);\n}\n\n\/\/ Dentro do handler:\nconst cliente = cert.subject.CN;\nconst rota = new URL(req.url, 'https:\/\/localhost').pathname;\n\nif (!autorizar(cliente, rota)) {\n  res.writeHead(403);\n  res.end(JSON.stringify({ erro: `Cliente ${cliente} sem acesso a ${rota}` }));\n  return;\n}<\/code><\/pre>\n\n\n\n
Este padr\u00e3o separa de forma limpa as duas responsabilidades. O TLS trata da autentica\u00e7\u00e3o (“este \u00e9 mesmo o servico-faturacao”). A fun\u00e7\u00e3o autorizar<\/code> trata do controlo de acesso (“o servico-faturacao pode escrever em \/faturas, mas n\u00e3o pode ver relat\u00f3rios”). \u00c9 a mesma filosofia de princ\u00edpio do menor privil\u00e9gio que aplicamos em autentica\u00e7\u00e3o SSH com chaves Ed25519<\/a>: a identidade forte \u00e9 o in\u00edcio, n\u00e3o o fim, do controlo de acesso.<\/p>\n\n\n\n
Passo 8: o cliente mTLS em Node.js<\/h2>\n\n\n\n
Um servidor que exige certificados de cliente \u00e9 in\u00fatil sem um cliente que os apresente. Cria client.js<\/code>. O cliente carrega a sua pr\u00f3pria chave e certificado e, crucialmente, a CA, para poder verificar o certificado do servidor.<\/p>\n\n\n\n
\/\/ client.js\nimport https from 'node:https';\nimport fs from 'node:fs';\n\nconst options = {\n  hostname: 'localhost',\n  port: 8443,\n  path: '\/faturas',\n  method: 'GET',\n\n  \/\/ O cliente apresenta o SEU certificado\n  key: fs.readFileSync('certs\/client-key.pem'),\n  cert: fs.readFileSync('certs\/client-cert.pem'),\n\n  \/\/ E verifica o certificado do servidor contra a CA\n  ca: fs.readFileSync('certs\/ca-cert.pem'),\n\n  minVersion: 'TLSv1.3',\n};\n\nconst req = https.request(options, (res) => {\n  let dados = '';\n  res.on('data', (c) => (dados += c));\n  res.on('end', () => {\n    console.log('Estado:', res.statusCode);\n    console.log('Resposta:', dados);\n  });\n});\n\nreq.on('error', (e) => console.error('Erro de ligacao:', e.message));\nreq.end();<\/code><\/pre>\n\n\n\n
Corre o servidor numa janela (node server.js<\/code>) e o cliente noutra (node client.js<\/code>). Se tudo estiver bem, v\u00eas uma resposta 200 com a mensagem de sauda\u00e7\u00e3o. Para provar que o mTLS funciona, tenta ligar-te sem certificado, por exemplo com curl https:\/\/localhost:8443\/faturas -k<\/code>. A liga\u00e7\u00e3o \u00e9 recusada porque o curl, sem certificado de cliente, falha o handshake. Esse \u00e9 o sistema a fazer o seu trabalho.<\/p>\n\n\n\n
Passo 9: for\u00e7ar TLS 1.3 e cipher suites seguras<\/h2>\n\n\n\n
J\u00e1 for\u00e7\u00e1mos TLS 1.3 com minVersion<\/code>. Vale a pena perceber o que isso te d\u00e1. O TLS 1.3 s\u00f3 permite cinco cipher suites, todas com sigilo perfeito futuro (forward secrecy) e cifra autenticada. N\u00e3o h\u00e1 como negociar uma combina\u00e7\u00e3o fraca por engano, ao contr\u00e1rio do TLS 1.2 onde a configura\u00e7\u00e3o errada abre buracos.<\/p>\n\n\n\n
Cipher suite TLS 1.3<\/th>Cifra<\/th>Hash<\/th>Recomenda\u00e7\u00e3o<\/th><\/tr><\/thead>
TLS_AES_256_GCM_SHA384<\/td>AES-256-GCM<\/td>SHA-384<\/td>Preferida para dados sens\u00edveis<\/td><\/tr>
TLS_CHACHA20_POLY1305_SHA256<\/td>ChaCha20-Poly1305<\/td>SHA-256<\/td>\u00d3tima em hardware sem AES-NI<\/td><\/tr>
TLS_AES_128_GCM_SHA256<\/td>AES-128-GCM<\/td>SHA-256<\/td>S\u00f3lida e r\u00e1pida<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Se quiseres restringir explicitamente as cipher suites de TLS 1.3, podes passar a op\u00e7\u00e3o ciphers<\/code>. Na maioria dos casos, deixar o Node usar a ordem por omiss\u00e3o do OpenSSL \u00e9 a escolha certa, porque essa ordem j\u00e1 prioriza as op\u00e7\u00f5es fortes. S\u00f3 restrinjas se tiveres um requisito de conformidade espec\u00edfico.<\/p>\n\n\n\n
\/\/ Restringir cipher suites de TLS 1.3 (opcional)\nconst options = {\n  \/\/ ... resto da configuracao ...\n  minVersion: 'TLSv1.3',\n  ciphers: [\n    'TLS_AES_256_GCM_SHA384',\n    'TLS_CHACHA20_POLY1305_SHA256',\n  ].join(':'),\n};<\/code><\/pre>\n\n\n\n
A OWASP mant\u00e9m recomenda\u00e7\u00f5es atualizadas sobre configura\u00e7\u00e3o de TLS. Se vais para produ\u00e7\u00e3o, vale a pena passar pela folha de dicas de TLS da OWASP<\/a> antes de fixar a tua configura\u00e7\u00e3o final.<\/p>\n\n\n\n
Passo 10 e 11: rota\u00e7\u00e3o, expira\u00e7\u00e3o e revoga\u00e7\u00e3o de certificados<\/h2>\n\n\n\n
Certificados expiram, e \u00e9 bom que assim seja. Um certificado de cliente v\u00e1lido 365 dias limita o dano se uma chave for comprometida sem ser detetada. Mas isto cria uma obriga\u00e7\u00e3o operacional: tens de rodar os certificados antes de expirarem, ou os teus servi\u00e7os param de comunicar \u00e0 meia-noite de uma data qualquer.<\/p>\n\n\n\n
A rota\u00e7\u00e3o \u00e9 simplesmente repetir o passo de emiss\u00e3o com uma nova chave e novo certificado, depois recarregar no servi\u00e7o. Automatiza a verifica\u00e7\u00e3o de expira\u00e7\u00e3o para nunca seres apanhado de surpresa.<\/p>\n\n\n\n
# Verificar se um certificado expira nos proximos 30 dias\nopenssl x509 -in certs\/client-cert.pem -noout -checkend 2592000\n# Codigo de saida 0 = ainda valido por mais de 30 dias\n# Codigo de saida 1 = expira dentro de 30 dias, RODAR JA\n\n# Ver a data exata de expiracao\nopenssl x509 -in certs\/client-cert.pem -noout -enddate<\/code><\/pre>\n\n\n\n
A revoga\u00e7\u00e3o resolve o problema oposto: e se um certificado ainda v\u00e1lido for comprometido e precisares de o invalidar j\u00e1? Para sistemas pequenos, a abordagem mais simples \u00e9 manter uma lista de allow no c\u00f3digo (como o nosso mapa POLITICAS<\/code>): remove o CN comprometido e ele perde acesso imediatamente, mesmo com certificado tecnicamente v\u00e1lido. Para sistemas maiores, usa uma Lista de Revoga\u00e7\u00e3o de Certificados (CRL) ou OCSP, que o Node consegue verificar com configura\u00e7\u00e3o adicional.<\/p>\n\n\n\n
Passo 12: testar com OpenSSL, curl e automa\u00e7\u00e3o<\/h2>\n\n\n\n
Confiar sem testar \u00e9 neglig\u00eancia. A ferramenta openssl s_client<\/code> deixa-te simular um cliente mTLS e ver o handshake completo, incluindo a vers\u00e3o de protocolo negociada e a cipher suite escolhida.<\/p>\n\n\n\n
# Ligar com certificado de cliente e inspecionar o handshake\nopenssl s_client -connect localhost:8443 \\\n  -cert certs\/client-cert.pem \\\n  -key certs\/client-key.pem \\\n  -CAfile certs\/ca-cert.pem \\\n  -tls1_3\n\n# Procura na saida:\n# Protocol  : TLSv1.3\n# Cipher    : TLS_AES_256_GCM_SHA384\n# Verify return code: 0 (ok)<\/code><\/pre>\n\n\n\n
O curl<\/code> faz um teste mais pr\u00f3ximo do mundo real. Com os certificados certos, deve devolver 200. Sem eles, deve falhar.<\/p>\n\n\n\n
# Pedido autenticado correto\ncurl --cert certs\/client-cert.pem \\\n     --key certs\/client-key.pem \\\n     --cacert certs\/ca-cert.pem \\\n     https:\/\/localhost:8443\/faturas\n# Esperado: {\"mensagem\":\"Ola, servico-faturacao\", ...}\n\n# Sem certificado de cliente (deve FALHAR)\ncurl --cacert certs\/ca-cert.pem https:\/\/localhost:8443\/faturas\n# Esperado: erro de handshake TLS, ligacao recusada<\/code><\/pre>\n\n\n\n
Esta dualidade (sucesso com certificado, falha sem ele) \u00e9 o teste mais importante de todos. Se o segundo comando devolver dados em vez de um erro, a tua configura\u00e7\u00e3o mTLS est\u00e1 partida e qualquer um pode aceder. Inclui ambos os testes num script de CI para apanhar regress\u00f5es antes de chegarem a produ\u00e7\u00e3o.<\/p>\n\n\n\n
Erros comuns e armadilhas no mTLS em Node.js<\/h2>\n\n\n\n
O mTLS falha quase sempre pelas mesmas raz\u00f5es. Conhecer estas armadilhas poupa-te horas de depura\u00e7\u00e3o frustrante. A tabela resume as mais frequentes.<\/p>\n\n\n\n
Armadilha<\/th>Sintoma<\/th>Solu\u00e7\u00e3o<\/th><\/tr><\/thead>
Falta de SAN no certificado do servidor<\/td>Erro de hostname no cliente<\/td>Adicionar subjectAltName<\/code> com o nome ou IP<\/td><\/tr>
rejectUnauthorized: false<\/code> esquecido<\/td>Clientes inv\u00e1lidos s\u00e3o aceites<\/td>Garantir true<\/code> em produ\u00e7\u00e3o<\/td><\/tr>
CA em falta no cliente<\/td>Cliente recusa o servidor (self-signed)<\/td>Carregar ca-cert.pem<\/code> no cliente<\/td><\/tr>
Chave privada com permiss\u00f5es abertas<\/td>Risco de fuga de chave<\/td>chmod 600<\/code> nas chaves .pem<\/code><\/td><\/tr>
Certificado expirado<\/td>Liga\u00e7\u00f5es param de repente<\/td>Monitorizar com -checkend<\/code><\/td><\/tr>
Confundir autentica\u00e7\u00e3o com autoriza\u00e7\u00e3o<\/td>Qualquer cert v\u00e1lido acede a tudo<\/td>Mapear CN para permiss\u00f5es<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
A pior de todas, e a mais comum em tutoriais apressados pela internet, \u00e9 rejectUnauthorized: false<\/code>. As pessoas adicionam essa linha para “fazer funcionar” durante o desenvolvimento e esquecem-se de a remover. O resultado \u00e9 um servidor que pede certificados mas aceita qualquer um, incluindo certificados autoassinados por um atacante. \u00c9 seguran\u00e7a teatral: parece mTLS, mas n\u00e3o protege nada. Trata qualquer rejectUnauthorized: false<\/code> num code review como um bug cr\u00edtico.<\/p>\n\n\n\n
Resolu\u00e7\u00e3o de problemas: 8 erros e como os corrigir<\/h2>\n\n\n\n
Quando o handshake falha, o Node devolve c\u00f3digos de erro espec\u00edficos. Esta tabela mapeia os mais comuns para a sua causa e corre\u00e7\u00e3o.<\/p>\n\n\n\n
C\u00f3digo de erro<\/th>Causa prov\u00e1vel<\/th>Corre\u00e7\u00e3o<\/th><\/tr><\/thead>
UNABLE_TO_VERIFY_LEAF_SIGNATURE<\/code><\/td>Cliente n\u00e3o tem a CA carregada<\/td>Passar ca<\/code> nas op\u00e7\u00f5es do cliente<\/td><\/tr>
ERR_TLS_CERT_ALTNAME_INVALID<\/code><\/td>SAN n\u00e3o corresponde ao hostname<\/td>Reemitir cert com SAN correto<\/td><\/tr>
CERT_HAS_EXPIRED<\/code><\/td>Certificado fora de validade<\/td>Rodar o certificado<\/td><\/tr>
DEPTH_ZERO_SELF_SIGNED_CERT<\/code><\/td>Cert n\u00e3o assinado pela CA esperada<\/td>Reemitir assinado pela CA correta<\/td><\/tr>
ECONNRESET<\/code> no handshake<\/td>Cliente sem certificado e servidor exige<\/td>Adicionar cert<\/code> e key<\/code> ao cliente<\/td><\/tr>
ERR_SSL_WRONG_VERSION_NUMBER<\/code><\/td>Cliente tenta HTTP em porta TLS<\/td>Usar https:\/\/<\/code>, n\u00e3o http:\/\/<\/code><\/td><\/tr>
ERR_TLS_HANDSHAKE_TIMEOUT<\/code><\/td>Vers\u00f5es de TLS incompat\u00edveis<\/td>Alinhar minVersion<\/code> nos dois lados<\/td><\/tr>
EACCES<\/code> ao ler chave<\/td>Permiss\u00f5es de ficheiro erradas<\/td>Corrigir dono e chmod<\/code> da chave<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Quando estiveres perdido, ativa o registo detalhado do Node com a vari\u00e1vel de ambiente NODE_DEBUG=tls node server.js<\/code>. Isto despeja cada passo do handshake, incluindo que certificados foram pedidos e porque a valida\u00e7\u00e3o falhou. \u00c9 verboso, mas mostra exatamente onde o processo quebra. Combina com openssl s_client<\/code> do lado do cliente para ver os dois \u00e2ngulos do mesmo handshake.<\/p>\n\n\n\n
Um detalhe sobre o UNABLE_TO_VERIFY_LEAF_SIGNATURE<\/code>: ele aparece quando o lado que valida n\u00e3o tem como construir a cadeia at\u00e9 uma CA de confian\u00e7a. Em mTLS, isto acontece tanto no cliente (sem a CA do servidor) como no servidor (sem a CA do cliente). Verifica sempre que a op\u00e7\u00e3o ca<\/code> est\u00e1 presente em ambos os lados e aponta para o mesmo ca-cert.pem<\/code>.<\/p>\n\n\n\n
Dicas avan\u00e7adas para mTLS em produ\u00e7\u00e3o<\/h2>\n\n\n\n
Sair do localhost para produ\u00e7\u00e3o muda algumas coisas. Estas pr\u00e1ticas separam um prot\u00f3tipo de um sistema que aguenta auditoria.<\/p>\n\n\n\n