TLS (SSL)

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código-Fonte: lib/tls.js

O módulo node:tls fornece uma implementação dos protocolos Transport Layer Security (TLS) e Secure Socket Layer (SSL) que é construído sobre o OpenSSL. O módulo pode ser acessado usando:

ESM

import tls from 'node:tls'

CJS

const tls = require('node:tls')

Determinando se o suporte criptográfico não está disponível

É possível que o Node.js seja compilado sem incluir suporte para o módulo node:crypto. Nesses casos, tentar importar de tls ou chamar require('node:tls') resultará em um erro sendo lançado.

Quando se usa CommonJS, o erro lançado pode ser capturado usando try/catch:

let tls
try {
  tls = require('node:tls')
} catch (err) {
  console.error('O suporte tls está desativado!')
}

Quando se usa a palavra-chave import ESM léxica, o erro só pode ser capturado se um manipulador para process.on('uncaughtException') for registrado antes de qualquer tentativa de carregar o módulo ser feita (usando, por exemplo, um módulo de pré-carregamento).

Ao usar ESM, se houver a chance de que o código possa ser executado em uma compilação do Node.js onde o suporte criptográfico não está habilitado, considere usar a função import() em vez da palavra-chave import léxica:

let tls
try {
  tls = await import('node:tls')
} catch (err) {
  console.error('O suporte tls está desativado!')
}

Conceitos TLS/SSL

TLS/SSL é um conjunto de protocolos que dependem de uma infraestrutura de chave pública (PKI) para habilitar a comunicação segura entre um cliente e um servidor. Para a maioria dos casos comuns, cada servidor deve ter uma chave privada.

As chaves privadas podem ser geradas de várias maneiras. O exemplo abaixo ilustra o uso da interface de linha de comando OpenSSL para gerar uma chave privada RSA de 2048 bits:

openssl genrsa -out ryans-key.pem 2048

Com TLS/SSL, todos os servidores (e alguns clientes) devem ter um certificado. Os certificados são chaves públicas que correspondem a uma chave privada e que são assinadas digitalmente por uma Autoridade de Certificação ou pelo proprietário da chave privada (esses certificados são referidos como "autoassinados"). A primeira etapa para obter um certificado é criar um arquivo de Solicitação de Assinatura de Certificado (CSR).

A interface de linha de comando OpenSSL pode ser usada para gerar um CSR para uma chave privada:

openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem

Depois que o arquivo CSR for gerado, ele pode ser enviado a uma Autoridade de Certificação para assinatura ou usado para gerar um certificado autoassinado.

A criação de um certificado autoassinado usando a interface de linha de comando OpenSSL é ilustrada no exemplo abaixo:

openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem

Depois que o certificado for gerado, ele pode ser usado para gerar um arquivo .pfx ou .p12:

openssl pkcs12 -export -in ryans-cert.pem -inkey ryans-key.pem \
      -certfile ca-cert.pem -out ryans.pfx

Onde:

• in: é o certificado assinado
• inkey: é a chave privada associada
• certfile: é uma concatenação de todos os certificados da Autoridade de Certificação (CA) em um único arquivo, por exemplo, cat ca1-cert.pem ca2-cert.pem \> ca-cert.pem

Sigilo avançado perfeito

O termo sigilo avançado ou sigilo avançado perfeito descreve uma característica dos métodos de concordância de chaves (ou seja, troca de chaves). Ou seja, as chaves do servidor e do cliente são usadas para negociar novas chaves temporárias que são usadas especificamente e apenas para a sessão de comunicação atual. Na prática, isso significa que, mesmo que a chave privada do servidor seja comprometida, a comunicação só pode ser descriptografada por espiões se o atacante conseguir obter o par de chaves gerado especificamente para a sessão.

O sigilo avançado perfeito é alcançado gerando aleatoriamente um par de chaves para a concordância de chaves em cada handshake TLS/SSL (ao contrário de usar a mesma chave para todas as sessões). Os métodos que implementam essa técnica são chamados de "efêmeros".

Atualmente, dois métodos são comumente usados para alcançar o sigilo avançado perfeito (observe o caractere "E" anexado às abreviações tradicionais):

• ECDHE: Uma versão efêmera do protocolo de concordância de chaves Diffie-Hellman de curva elíptica.
• DHE: Uma versão efêmera do protocolo de concordância de chaves Diffie-Hellman.

O sigilo avançado perfeito usando ECDHE é ativado por padrão. A opção ecdhCurve pode ser usada ao criar um servidor TLS para personalizar a lista de curvas ECDH suportadas a serem usadas. Veja tls.createServer() para mais informações.

DHE é desativado por padrão, mas pode ser ativado junto com ECDHE definindo a opção dhparam como 'auto'. Parâmetros DHE personalizados também são suportados, mas são desencorajados em favor de parâmetros bem conhecidos selecionados automaticamente.

O sigilo avançado perfeito era opcional até o TLSv1.2. A partir do TLSv1.3, (EC)DHE é sempre usado (com exceção de conexões apenas PSK).

ALPN e SNI

ALPN (Application-Layer Protocol Negotiation Extension) e SNI (Server Name Indication) são extensões de handshake TLS:

• ALPN: Permite o uso de um servidor TLS para vários protocolos (HTTP, HTTP/2)
• SNI: Permite o uso de um servidor TLS para vários nomes de host com certificados diferentes.

Chaves pré-compartilhadas

O suporte TLS-PSK está disponível como alternativa à autenticação normal baseada em certificados. Ele usa uma chave pré-compartilhada em vez de certificados para autenticar uma conexão TLS, fornecendo autenticação mútua. TLS-PSK e infraestrutura de chave pública não são mutuamente exclusivos. Clientes e servidores podem acomodar ambos, escolhendo um deles durante a etapa normal de negociação de cifra.

TLS-PSK só é uma boa escolha quando existem meios para compartilhar com segurança uma chave com cada máquina de conexão, portanto, não substitui a infraestrutura de chave pública (PKI) para a maioria dos usos de TLS. A implementação TLS-PSK em OpenSSL apresentou muitas falhas de segurança nos últimos anos, principalmente porque é usada apenas por uma minoria de aplicativos. Considere todas as soluções alternativas antes de mudar para cifras PSK. Ao gerar PSK, é de extrema importância usar entropia suficiente, como discutido em RFC 4086. Derivar um segredo compartilhado de uma senha ou outras fontes de baixa entropia não é seguro.

As cifras PSK são desabilitadas por padrão, e o uso de TLS-PSK requer, portanto, a especificação explícita de um conjunto de cifras com a opção ciphers. A lista de cifras disponíveis pode ser recuperada via openssl ciphers -v 'PSK'. Todas as cifras TLS 1.3 são elegíveis para PSK e podem ser recuperadas via openssl ciphers -v -s -tls1_3 -psk. Na conexão do cliente, um checkServerIdentity personalizado deve ser passado porque o padrão falhará na ausência de um certificado.

De acordo com a RFC 4279, identidades PSK de até 128 bytes de comprimento e PSKs de até 64 bytes de comprimento devem ser suportadas. A partir do OpenSSL 1.1.0, o tamanho máximo de identidade é de 128 bytes e o comprimento máximo de PSK é de 256 bytes.

A implementação atual não suporta callbacks PSK assíncronos devido às limitações da API OpenSSL subjacente.

Para usar TLS-PSK, o cliente e o servidor devem especificar a opção pskCallback, uma função que retorna o PSK a ser usado (que deve ser compatível com o digest da cifra selecionada).

Será chamado primeiro no cliente:

• dica: <string> mensagem opcional enviada do servidor para ajudar o cliente a decidir qual identidade usar durante a negociação. Sempre null se TLS 1.3 for usado.
• Retorna: <Object> na forma { psk: \<Buffer|TypedArray|DataView\>, identity: \<string\> } ou null.

Então no servidor:

• socket: <tls.TLSSocket> a instância do socket do servidor, equivalente a this.
• identity: <string> parâmetro de identidade enviado do cliente.
• Retorna: <Buffer> | <TypedArray> | <DataView> o PSK (ou null).

Um valor de retorno de null interrompe o processo de negociação e envia uma mensagem de alerta unknown_psk_identity para a outra parte. Se o servidor desejar ocultar o fato de que a identidade PSK não era conhecida, o callback deve fornecer alguns dados aleatórios como psk para fazer a conexão falhar com decrypt_error antes que a negociação seja concluída.

Mitigação de ataque de renegociação iniciada pelo cliente

O protocolo TLS permite que os clientes renegociem certos aspectos da sessão TLS. Infelizmente, a renegociação de sessão requer uma quantidade desproporcional de recursos do lado do servidor, tornando-a um vetor potencial para ataques de negação de serviço.

Para mitigar o risco, a renegociação é limitada a três vezes a cada dez minutos. Um evento 'error' é emitido na instância tls.TLSSocket quando este limite é excedido. Os limites são configuráveis:

• tls.CLIENT_RENEG_LIMIT <número> Especifica o número de solicitações de renegociação. Padrão: 3.
• tls.CLIENT_RENEG_WINDOW <número> Especifica a janela de tempo de renegociação em segundos. Padrão: 600 (10 minutos).

Os limites de renegociação padrão não devem ser modificados sem uma compreensão completa das implicações e riscos.

TLSv1.3 não suporta renegociação.

Retomada de sessão

Estabelecer uma sessão TLS pode ser relativamente lento. O processo pode ser acelerado salvando e reutilizando posteriormente o estado da sessão. Existem vários mecanismos para fazê-lo, discutidos aqui do mais antigo para o mais novo (e preferido).

Identificadores de sessão

Os servidores geram um ID exclusivo para novas conexões e o enviam para o cliente. Clientes e servidores salvam o estado da sessão. Ao reconectar, os clientes enviam o ID do estado da sessão salva e, se o servidor também tiver o estado para esse ID, ele pode concordar em usá-lo. Caso contrário, o servidor criará uma nova sessão. Consulte RFC 2246 para obter mais informações, páginas 23 e 30.

A retomada usando identificadores de sessão é suportada pela maioria dos navegadores da web ao fazer solicitações HTTPS.

Para Node.js, os clientes aguardam o evento 'session' para obter os dados da sessão e fornecer os dados à opção session de uma subsequente tls.connect() para reutilizar a sessão. Os servidores devem implementar manipuladores para os eventos 'newSession' e 'resumeSession' para salvar e restaurar os dados da sessão usando o ID da sessão como a chave de pesquisa para reutilizar as sessões. Para reutilizar sessões em balanceadores de carga ou trabalhadores de cluster, os servidores devem usar um cache de sessão compartilhado (como o Redis) em seus manipuladores de sessão.

Bilhetes de sessão

Os servidores criptografam todo o estado da sessão e o enviam ao cliente como um "bilhete". Ao reconectar, o estado é enviado ao servidor na conexão inicial. Este mecanismo evita a necessidade de um cache de sessão do lado do servidor. Se o servidor não usar o bilhete, por qualquer motivo (falha na descriptografia, está muito antigo, etc.), ele criará uma nova sessão e enviará um novo bilhete. Veja RFC 5077 para mais informações.

A retomada usando bilhetes de sessão está se tornando comumente suportada por muitos navegadores da web ao fazer solicitações HTTPS.

Para Node.js, os clientes usam as mesmas APIs para retomada com identificadores de sessão como para retomada com bilhetes de sessão. Para depuração, se tls.TLSSocket.getTLSTicket() retornar um valor, os dados da sessão contêm um bilhete, caso contrário, contêm o estado da sessão do lado do cliente.

Com TLSv1.3, esteja ciente de que vários bilhetes podem ser enviados pelo servidor, resultando em vários eventos 'session', veja 'session' para mais informações.

Servidores de processo único não precisam de implementação específica para usar bilhetes de sessão. Para usar bilhetes de sessão em reinicializações do servidor ou balanceadores de carga, todos os servidores devem ter as mesmas chaves de bilhete. Existem três chaves internas de 16 bytes, mas a API tls as expõe como um único buffer de 48 bytes por conveniência.

É possível obter as chaves do bilhete chamando server.getTicketKeys() em uma instância do servidor e, em seguida, distribuí-las, mas é mais razoável gerar com segurança 48 bytes de dados aleatórios seguros e defini-los com a opção ticketKeys de tls.createServer(). As chaves devem ser regeneradas regularmente e as chaves do servidor podem ser redefinidas com server.setTicketKeys().

As chaves do bilhete de sessão são chaves criptográficas e devem ser armazenadas com segurança. Com TLS 1.2 e versões anteriores, se forem comprometidas, todas as sessões que usaram bilhetes criptografados com elas podem ser descriptografadas. Elas não devem ser armazenadas em disco e devem ser regeneradas regularmente.

Se os clientes anunciarem suporte para bilhetes, o servidor os enviará. O servidor pode desabilitar bilhetes fornecendo require('node:constants').SSL_OP_NO_TICKET em secureOptions.

Tanto os identificadores de sessão quanto os bilhetes de sessão expiram, fazendo com que o servidor crie novas sessões. O tempo limite pode ser configurado com a opção sessionTimeout de tls.createServer().

Para todos os mecanismos, quando a retomada falha, os servidores criarão novas sessões. Como a falha na retomada da sessão não causa falhas na conexão TLS/HTTPS, é fácil não perceber um desempenho TLS desnecessariamente ruim. A CLI OpenSSL pode ser usada para verificar se os servidores estão retomando as sessões. Use a opção -reconnect para openssl s_client, por exemplo:

openssl s_client -connect localhost:443 -reconnect

Leia a saída de depuração. A primeira conexão deve dizer "New", por exemplo:

New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256

Conexões subsequentes devem dizer "Reused", por exemplo:

Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256

Modificando o conjunto de cifras TLS padrão

O Node.js é construído com um conjunto padrão de cifras TLS habilitadas e desabilitadas. Essa lista de cifras padrão pode ser configurada durante a construção do Node.js para permitir que as distribuições forneçam sua própria lista padrão.

O seguinte comando pode ser usado para mostrar o conjunto de cifras padrão:

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA

Este padrão pode ser substituído completamente usando a opção de linha de comando --tls-cipher-list (diretamente ou por meio da variável de ambiente NODE_OPTIONS). Por exemplo, o seguinte torna ECDHE-RSA-AES128-GCM-SHA256:!RC4 o conjunto de cifras TLS padrão:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js

Para verificar, use o seguinte comando para mostrar a lista de cifras definida, observe a diferença entre defaultCoreCipherList e defaultCipherList:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4

Ou seja, a lista defaultCoreCipherList é definida no momento da compilação e a defaultCipherList é definida em tempo de execução.

Para modificar os conjuntos de cifras padrão de dentro do tempo de execução, modifique a variável tls.DEFAULT_CIPHERS, isso deve ser feito antes de ouvir em quaisquer sockets, não afetará os sockets já abertos. Por exemplo:

// Remove cifras CBC obsoletas e cifras baseadas em troca de chave RSA, pois elas não fornecem sigilo avançado
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'

O padrão também pode ser substituído por cliente ou servidor usando a opção ciphers de tls.createSecureContext(), que também está disponível em tls.createServer(), tls.connect() e ao criar novos tls.TLSSockets.

A lista de cifras pode conter uma mistura de nomes de suítes de cifras TLSv1.3, aquelas que começam com 'TLS_', e especificações para suítes de cifras TLSv1.2 e anteriores. As cifras TLSv1.2 suportam um formato de especificação herdado, consulte a documentação do formato da lista de cifras OpenSSL formato da lista de cifras para detalhes, mas essas especificações não se aplicam a cifras TLSv1.3. As suítes TLSv1.3 só podem ser habilitadas incluindo seu nome completo na lista de cifras. Elas não podem, por exemplo, ser habilitadas ou desabilitadas usando a especificação herdada TLSv1.2 'EECDH' ou '!EECDH'.

Apesar da ordem relativa das suítes de cifras TLSv1.3 e TLSv1.2, o protocolo TLSv1.3 é significativamente mais seguro que o TLSv1.2 e sempre será escolhido em vez do TLSv1.2 se o handshake indicar que ele é compatível e se alguma suíte de cifras TLSv1.3 estiver habilitada.

O conjunto de cifras padrão incluído no Node.js foi cuidadosamente selecionado para refletir as melhores práticas de segurança atuais e a mitigação de riscos. Alterar o conjunto de cifras padrão pode ter um impacto significativo na segurança de um aplicativo. A opção --tls-cipher-list e a opção ciphers devem ser usadas apenas se absolutamente necessário.

O conjunto de cifras padrão prefere cifras GCM para a configuração de 'criptografia moderna' do Chrome e também prefere cifras ECDHE e DHE para sigilo avançado, oferecendo alguma compatibilidade com versões anteriores.

Clientes antigos que dependem de cifras RC4 ou DES baseadas em inseguras e obsoletas (como o Internet Explorer 6) não podem concluir o processo de handshake com a configuração padrão. Se esses clientes devem ser suportados, as recomendações TLS podem oferecer um conjunto de cifras compatível. Para mais detalhes sobre o formato, consulte a documentação do formato da lista de cifras OpenSSL formato da lista de cifras.

Existem apenas cinco suítes de cifras TLSv1.3:

• 'TLS_AES_256_GCM_SHA384'
• 'TLS_CHACHA20_POLY1305_SHA256'
• 'TLS_AES_128_GCM_SHA256'
• 'TLS_AES_128_CCM_SHA256'
• 'TLS_AES_128_CCM_8_SHA256'

As três primeiras são habilitadas por padrão. As duas suítes baseadas em CCM são suportadas pelo TLSv1.3 porque podem ser mais eficientes em sistemas com recursos limitados, mas não são habilitadas por padrão, pois oferecem menos segurança.

Nível de segurança do OpenSSL

A biblioteca OpenSSL impõe níveis de segurança para controlar o nível mínimo aceitável de segurança para operações criptográficas. Os níveis de segurança do OpenSSL variam de 0 a 5, com cada nível impondo requisitos de segurança mais rigorosos. O nível de segurança padrão é 1, que geralmente é adequado para a maioria dos aplicativos modernos. No entanto, alguns recursos e protocolos legados, como TLSv1, exigem um nível de segurança inferior (SECLEVEL=0) para funcionar corretamente. Para informações mais detalhadas, consulte a documentação do OpenSSL sobre níveis de segurança.

Definindo níveis de segurança

Para ajustar o nível de segurança em seu aplicativo Node.js, você pode incluir @SECLEVEL=X em uma string de cifra, onde X é o nível de segurança desejado. Por exemplo, para definir o nível de segurança como 0 enquanto usa a lista de cifras OpenSSL padrão, você pode usar:

ESM

import { createServer, connect } from 'node:tls'
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Cliente conectado com protocolo:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

CJS

const { createServer, connect } = require('node:tls')
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Cliente conectado com protocolo:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

Esta abordagem define o nível de segurança como 0, permitindo o uso de recursos legados enquanto ainda utiliza as cifras OpenSSL padrão.

Usando

Você também pode definir o nível de segurança e as cifras a partir da linha de comando usando --tls-cipher-list=DEFAULT@SECLEVEL=X, conforme descrito em Modificando o conjunto de cifras TLS padrão. No entanto, geralmente é desencorajado o uso da opção de linha de comando para definir cifras e é preferível configurar as cifras para contextos individuais dentro do código do seu aplicativo, pois essa abordagem fornece controle mais preciso e reduz o risco de reduzir globalmente o nível de segurança.

Códigos de erro de certificado X509

Várias funções podem falhar devido a erros de certificado relatados pelo OpenSSL. Nesse caso, a função fornece um <Erro> por meio de seu callback que possui a propriedade code, que pode assumir um dos seguintes valores:

• 'UNABLE_TO_GET_ISSUER_CERT': Impossível obter o certificado do emissor.
• 'UNABLE_TO_GET_CRL': Impossível obter a CRL do certificado.
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': Impossível descriptografar a assinatura do certificado.
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': Impossível descriptografar a assinatura da CRL.
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': Impossível decodificar a chave pública do emissor.
• 'CERT_SIGNATURE_FAILURE': Falha na assinatura do certificado.
• 'CRL_SIGNATURE_FAILURE': Falha na assinatura da CRL.
• 'CERT_NOT_YET_VALID': Certificado ainda não válido.
• 'CERT_HAS_EXPIRED': Certificado expirado.
• 'CRL_NOT_YET_VALID': CRL ainda não válida.
• 'CRL_HAS_EXPIRED': CRL expirada.
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD': Erro de formato no campo notBefore do certificado.
• 'ERROR_IN_CERT_NOT_AFTER_FIELD': Erro de formato no campo notAfter do certificado.
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD': Erro de formato no campo lastUpdate da CRL.
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': Erro de formato no campo nextUpdate da CRL.
• 'OUT_OF_MEM': Memória insuficiente.
• 'DEPTH_ZERO_SELF_SIGNED_CERT': Certificado autoassinado.
• 'SELF_SIGNED_CERT_IN_CHAIN': Certificado autoassinado na cadeia de certificados.
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': Impossível obter o certificado do emissor localmente.
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': Impossível verificar a assinatura do primeiro certificado.
• 'CERT_CHAIN_TOO_LONG': Cadeia de certificados muito longa.
• 'CERT_REVOKED': Certificado revogado.
• 'INVALID_CA': Certificado de CA inválido.
• 'PATH_LENGTH_EXCEEDED': Restrição de comprimento do caminho excedida.
• 'INVALID_PURPOSE': Finalidade de certificado não suportada.
• 'CERT_UNTRUSTED': Certificado não confiável.
• 'CERT_REJECTED': Certificado rejeitado.
• 'HOSTNAME_MISMATCH': Inconsistência de nome de host.

Classe: tls.CryptoStream

Adicionado em: v0.3.4

Depreciado desde: v0.11.3

[Estável: 0 - Depreciado]

Estável: 0 Estabilidade: 0 - Depreciado: Use tls.TLSSocket em vez disso.

A classe tls.CryptoStream representa um fluxo de dados criptografados. Esta classe está depreciada e não deve mais ser usada.

cryptoStream.bytesWritten

Adicionado em: v0.3.4

Depreciado desde: v0.11.3

A propriedade cryptoStream.bytesWritten retorna o número total de bytes escritos para o socket subjacente, incluindo os bytes necessários para a implementação do protocolo TLS.

Classe: tls.SecurePair

Adicionado em: v0.3.2

Depreciado desde: v0.11.3

[Estável: 0 - Depreciado]

Estável: 0 Estabilidade: 0 - Depreciado: Use tls.TLSSocket em vez disso.

Retornado por tls.createSecurePair().

Evento: 'secure'

Adicionado em: v0.3.2

Depreciado desde: v0.11.3

O evento 'secure' é emitido pelo objeto SecurePair assim que uma conexão segura for estabelecida.

Como na verificação do evento do servidor 'secureConnection', pair.cleartext.authorized deve ser inspecionado para confirmar se o certificado usado está devidamente autorizado.

Classe: tls.Server

Adicionado em: v0.3.2

• Extende: <net.Server>

Aceita conexões criptografadas usando TLS ou SSL.

Evento: 'connection'

Adicionado em: v0.3.2

• socket <stream.Duplex>

Este evento é emitido quando um novo fluxo TCP é estabelecido, antes do início do handshake TLS. socket é tipicamente um objeto do tipo net.Socket, mas não receberá eventos, ao contrário do socket criado a partir do evento 'connection' do net.Server. Normalmente, os usuários não desejarão acessar este evento.

Este evento também pode ser explicitamente emitido pelos usuários para injetar conexões no servidor TLS. Nesse caso, qualquer fluxo Duplex pode ser passado.

Evento: 'keylog'

Adicionado em: v12.3.0, v10.20.0

• line <Buffer> Linha de texto ASCII, no formato NSS SSLKEYLOGFILE.
• tlsSocket <tls.TLSSocket> A instância tls.TLSSocket na qual foi gerado.

O evento keylog é emitido quando o material de chave é gerado ou recebido por uma conexão a este servidor (tipicamente antes da conclusão do handshake, mas não necessariamente). Este material de chaveamento pode ser armazenado para depuração, pois permite que o tráfego TLS capturado seja descriptografado. Ele pode ser emitido várias vezes para cada socket.

Um caso de uso típico é anexar linhas recebidas a um arquivo de texto comum, que é posteriormente usado por software (como o Wireshark) para descriptografar o tráfego:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...') return // Somente registrar chaves para um IP específico
  logFile.write(line)
})

Evento: 'newSession'

[Histórico]

Versão	Alterações
v0.11.12	O argumento callback agora é suportado.
v0.9.2	Adicionada em: v0.9.2

O evento 'newSession' é emitido após a criação de uma nova sessão TLS. Isso pode ser usado para armazenar sessões em armazenamento externo. Os dados devem ser fornecidos para o callback 'resumeSession'.

O callback do listener recebe três argumentos quando chamado:

• sessionId <Buffer> O identificador da sessão TLS
• sessionData <Buffer> Os dados da sessão TLS
• callback <Function> Uma função de callback que não recebe argumentos e que deve ser invocada para que os dados sejam enviados ou recebidos pela conexão segura.

A escuta deste evento terá efeito apenas em conexões estabelecidas após a adição do listener de eventos.

Evento: 'OCSPRequest'

Adicionado em: v0.11.13

O evento 'OCSPRequest' é emitido quando o cliente envia uma solicitação de status de certificado. O callback do listener recebe três argumentos quando chamado:

• certificate <Buffer> O certificado do servidor
• issuer <Buffer> O certificado do emissor
• callback <Function> Uma função de callback que deve ser invocada para fornecer os resultados da solicitação OCSP.

O certificado atual do servidor pode ser analisado para obter a URL do OCSP e o ID do certificado; após obter uma resposta OCSP, callback(null, resp) é então invocado, onde resp é uma instância Buffer contendo a resposta OCSP. certificate e issuer são representações DER Buffer dos certificados primário e do emissor. Estes podem ser usados para obter o ID do certificado OCSP e a URL do endpoint OCSP.

Alternativamente, callback(null, null) pode ser chamado, indicando que não houve resposta OCSP.

Chamar callback(err) resultará em uma chamada socket.destroy(err).

O fluxo típico de uma solicitação OCSP é o seguinte:

O issuer pode ser null se o certificado for autoassinado ou se o emissor não estiver na lista de certificados raiz. (Um emissor pode ser fornecido por meio da opção ca ao estabelecer a conexão TLS.)

A escuta deste evento terá efeito apenas em conexões estabelecidas após a adição do listener de eventos.

Um módulo npm como asn1.js pode ser usado para analisar os certificados.

Evento: 'resumeSession'

Adicionado em: v0.9.2

O evento 'resumeSession' é emitido quando o cliente solicita a retomada de uma sessão TLS anterior. O callback do listener recebe dois argumentos quando chamado:

• sessionId <Buffer> O identificador da sessão TLS
• callback <Function> Uma função de callback a ser chamada quando a sessão anterior foi recuperada: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

O listener de eventos deve realizar uma busca no armazenamento externo para os dados da sessão (sessionData) salvos pelo manipulador de eventos 'newSession' usando o sessionId fornecido. Se encontrado, chame callback(null, sessionData) para retomar a sessão. Se não encontrado, a sessão não pode ser retomada. callback() deve ser chamado sem sessionData para que o handshake possa continuar e uma nova sessão possa ser criada. É possível chamar callback(err) para encerrar a conexão de entrada e destruir o socket.

A escuta deste evento terá efeito apenas nas conexões estabelecidas após a adição do listener de eventos.

O seguinte ilustra a retomada de uma sessão TLS:

const tlsSessionStore = {}
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data
  cb()
})
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null)
})

Evento: 'secureConnection'

Adicionado em: v0.3.2

O evento 'secureConnection' é emitido após o processo de handshake para uma nova conexão ter sido concluído com sucesso. O callback do listener recebe um único argumento quando chamado:

• tlsSocket <tls.TLSSocket> O socket TLS estabelecido.

A propriedade tlsSocket.authorized é um booleano que indica se o cliente foi verificado por uma das Autoridades de Certificação fornecidas para o servidor. Se tlsSocket.authorized for false, então socket.authorizationError é definido para descrever como a autorização falhou. Dependendo das configurações do servidor TLS, conexões não autorizadas ainda podem ser aceitas.

A propriedade tlsSocket.alpnProtocol é uma string que contém o protocolo ALPN selecionado. Quando o ALPN não tem nenhum protocolo selecionado porque o cliente ou o servidor não enviou uma extensão ALPN, tlsSocket.alpnProtocol é igual a false.

A propriedade tlsSocket.servername é uma string contendo o nome do servidor solicitado via SNI.

Evento: 'tlsClientError'

Adicionado em: v6.0.0

O evento 'tlsClientError' é emitido quando ocorre um erro antes que uma conexão segura seja estabelecida. O callback do listener recebe dois argumentos quando chamado:

• exception <Error> O objeto Error descrevendo o erro.
• tlsSocket <tls.TLSSocket> A instância tls.TLSSocket de onde o erro se originou.

server.addContext(hostname, context)

Adicionado em: v0.5.3

• hostname <string> Um nome de host SNI ou curinga (por exemplo, '*').
• context <Object> | <tls.SecureContext> Um objeto contendo qualquer uma das propriedades possíveis dos argumentos options do tls.createSecureContext() (por exemplo, key, cert, ca, etc), ou um objeto de contexto TLS criado com tls.createSecureContext() em si.

O método server.addContext() adiciona um contexto seguro que será usado se o nome SNI da solicitação do cliente corresponder ao hostname fornecido (ou curinga).

Quando houver vários contextos correspondentes, o mais recentemente adicionado será usado.

server.address()

Adicionado em: v0.6.0

• Retorna: <Object>

Retorna o endereço vinculado, o nome da família de endereços e a porta do servidor conforme relatado pelo sistema operacional. Veja net.Server.address() para mais informações.

server.close([callback])

Adicionado em: v0.3.2

• callback <Function> Um callback do listener que será registrado para ouvir o evento 'close' da instância do servidor.
• Retorna: <tls.Server>

O método server.close() impede o servidor de aceitar novas conexões.

Esta função opera de forma assíncrona. O evento 'close' será emitido quando o servidor não tiver mais conexões abertas.

server.getTicketKeys()

Adicionado em: v3.0.0

• Retorna: <Buffer> Um buffer de 48 bytes contendo as chaves de ticket de sessão.

Retorna as chaves de ticket de sessão.

Veja Retomada de Sessão para mais informações.

server.listen()

Inicia o servidor ouvindo por conexões criptografadas. Este método é idêntico a server.listen() de net.Server.

server.setSecureContext(options)

Adicionado em: v11.0.0

• options <Object> Um objeto contendo quaisquer propriedades possíveis dos argumentos options de tls.createSecureContext() (e.g. key, cert, ca, etc).

O método server.setSecureContext() substitui o contexto seguro de um servidor existente. Conexões existentes com o servidor não são interrompidas.

server.setTicketKeys(keys)

Adicionado em: v3.0.0

• keys <Buffer> | <TypedArray> | <DataView> Um buffer de 48 bytes contendo as chaves de ticket de sessão.

Define as chaves de ticket de sessão.

Alterações nas chaves de ticket são eficazes apenas para conexões futuras do servidor. Conexões de servidor existentes ou atualmente pendentes usarão as chaves anteriores.

Veja Retomada de Sessão para mais informações.

Classe: tls.TLSSocket

Adicionado em: v0.11.4

• Estende: <net.Socket>

Realiza criptografia transparente de dados escritos e todas as negociações TLS necessárias.

Instâncias de tls.TLSSocket implementam a interface duplex Stream.

Métodos que retornam metadados de conexão TLS (e.g. tls.TLSSocket.getPeerCertificate()) somente retornarão dados enquanto a conexão estiver aberta.

new tls.TLSSocket(socket[, options])

[Histórico]

Versão	Alterações
v12.2.0	A opção enableTrace agora é suportada.
v5.0.0	Opções ALPN agora são suportadas.
v0.11.4	Adicionada em: v0.11.4

• socket <net.Socket> | <stream.Duplex> No lado do servidor, qualquer stream Duplex. No lado do cliente, qualquer instância de net.Socket (para suporte de stream Duplex genérico no lado do cliente, tls.connect() deve ser usado).
• options <Object>
  • enableTrace: Veja tls.createServer()
  • isServer: O protocolo SSL/TLS é assimétrico, TLSSockets deve saber se devem se comportar como um servidor ou um cliente. Se true, o socket TLS será instanciado como um servidor. Padrão: false.
  • server <net.Server> Uma instância net.Server.
  • requestCert: Se autenticar o peer remoto solicitando um certificado. Clientes sempre solicitam um certificado de servidor. Servidores (isServer é true) podem definir requestCert como true para solicitar um certificado de cliente.
  • rejectUnauthorized: Veja tls.createServer()
  • ALPNProtocols: Veja tls.createServer()
  • SNICallback: Veja tls.createServer()
  • session <Buffer> Uma instância Buffer contendo uma sessão TLS.
  • requestOCSP <boolean> Se true, especifica que a extensão de solicitação de status OCSP será adicionada ao client hello e um evento 'OCSPResponse' será emitido no socket antes de estabelecer uma comunicação segura.
  • secureContext: Objeto de contexto TLS criado com tls.createSecureContext(). Se um secureContext não for fornecido, um será criado passando o objeto options inteiro para tls.createSecureContext().
  • ...: opções tls.createSecureContext() que são usadas se a opção secureContext estiver ausente. Caso contrário, elas serão ignoradas.

Constrói um novo objeto tls.TLSSocket a partir de um socket TCP existente.

Evento: 'keylog'

Adicionado em: v12.3.0, v10.20.0

• line <Buffer> Linha de texto ASCII, no formato NSS SSLKEYLOGFILE.

O evento keylog é emitido em um tls.TLSSocket quando o material de chave é gerado ou recebido pelo socket. Esse material de chaveamento pode ser armazenado para depuração, pois permite que o tráfego TLS capturado seja descriptografado. Pode ser emitido várias vezes, antes ou depois da conclusão do handshake.

Um caso de uso típico é anexar linhas recebidas a um arquivo de texto comum, que é posteriormente usado por software (como o Wireshark) para descriptografar o tráfego:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
tlsSocket.on('keylog', line => logFile.write(line))

Evento: 'OCSPResponse'

Adicionado em: v0.11.13

O evento 'OCSPResponse' é emitido se a opção requestOCSP foi definida quando o tls.TLSSocket foi criado e uma resposta OCSP foi recebida. O callback do listener recebe um único argumento quando chamado:

• response <Buffer> A resposta OCSP do servidor

Normalmente, a response é um objeto assinado digitalmente da CA do servidor que contém informações sobre o status de revogação do certificado do servidor.

Evento: 'secureConnect'

Adicionado em: v0.11.4

O evento 'secureConnect' é emitido após o processo de handshake para uma nova conexão ter sido concluído com sucesso. O callback do listener será chamado independentemente de o certificado do servidor ter sido ou não autorizado. É responsabilidade do cliente verificar a propriedade tlsSocket.authorized para determinar se o certificado do servidor foi assinado por uma das CAs especificadas. Se tlsSocket.authorized === false, então o erro pode ser encontrado examinando a propriedade tlsSocket.authorizationError. Se ALPN foi usado, a propriedade tlsSocket.alpnProtocol pode ser verificada para determinar o protocolo negociado.

O evento 'secureConnect' não é emitido quando um <tls.TLSSocket> é criado usando o construtor new tls.TLSSocket().

Evento: 'session'

Adicionado em: v11.10.0

• session <Buffer>

O evento 'session' é emitido em um cliente tls.TLSSocket quando uma nova sessão ou ticket TLS está disponível. Isso pode ou não ser antes da conclusão da troca de mensagens, dependendo da versão do protocolo TLS negociada. O evento não é emitido no servidor, ou se uma nova sessão não foi criada, por exemplo, quando a conexão foi retomada. Para algumas versões do protocolo TLS, o evento pode ser emitido várias vezes, caso em que todas as sessões podem ser usadas para retomada.

No cliente, a session pode ser fornecida à opção session de tls.connect() para retomar a conexão.

Veja Retomada de Sessão para mais informações.

Para TLSv1.2 e abaixo, tls.TLSSocket.getSession() pode ser chamado assim que a troca de mensagens estiver concluída. Para TLSv1.3, apenas a retomada baseada em tickets é permitida pelo protocolo, vários tickets são enviados e os tickets não são enviados até que a troca de mensagens seja concluída. Portanto, é necessário aguardar o evento 'session' para obter uma sessão retomavel. As aplicações devem usar o evento 'session' em vez de getSession() para garantir que funcionarão para todas as versões TLS. As aplicações que esperam obter ou usar apenas uma sessão devem escutar este evento apenas uma vez:

tlsSocket.once('session', session => {
  // A sessão pode ser usada imediatamente ou mais tarde.
  tls.connect({
    session: session,
    // Outras opções de conexão...
  })
})

tlsSocket.address()

[Histórico]

Versão	Alterações
v18.4.0	A propriedade family agora retorna uma string em vez de um número.
v18.0.0	A propriedade family agora retorna um número em vez de uma string.
v0.11.4	Adicionada em: v0.11.4

• Retorna: <Object>

Retorna o address vinculado, o nome da family do endereço e a port do socket subjacente conforme relatado pelo sistema operacional: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError

Adicionado em: v0.11.4

Retorna o motivo pelo qual o certificado do peer não foi verificado. Esta propriedade é definida apenas quando tlsSocket.authorized === false.

tlsSocket.authorized

Adicionado em: v0.11.4

• <boolean>

Esta propriedade é true se o certificado do peer foi assinado por uma das CAs especificadas ao criar a instância tls.TLSSocket, caso contrário false.

tlsSocket.disableRenegotiation()

Adicionado em: v8.4.0

Desabilita a renegociação TLS para esta instância TLSSocket. Após a chamada, as tentativas de renegociação irão disparar um evento 'error' no TLSSocket.

tlsSocket.enableTrace()

Adicionado em: v12.2.0

Quando habilitado, informações de rastreio de pacotes TLS são escritas para stderr. Isso pode ser usado para depurar problemas de conexão TLS.

O formato da saída é idêntico à saída de openssl s_client -trace ou openssl s_server -trace. Embora seja produzido pela função SSL_trace() do OpenSSL, o formato não é documentado, pode mudar sem aviso prévio e não deve ser considerado confiável.

tlsSocket.encrypted

Adicionado em: v0.11.4

Sempre retorna true. Isso pode ser usado para distinguir sockets TLS de instâncias net.Socket regulares.

tlsSocket.exportKeyingMaterial(length, label[, context])

Adicionado em: v13.10.0, v12.17.0

• length <number> número de bytes a serem recuperados do material de chaveamento
• label <string> um rótulo específico do aplicativo, normalmente este será um valor do IANA Exporter Label Registry.
• context <Buffer> Opcionalmente, forneça um contexto.
• Retorna: <Buffer> bytes solicitados do material de chaveamento

O material de chaveamento é usado para validações para evitar diferentes tipos de ataques em protocolos de rede, por exemplo, nas especificações de IEEE 802.1X.

Exemplo

const keyingMaterial = tlsSocket.exportKeyingMaterial(128, 'client finished')

/*
 Exemplo de valor de retorno de keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/

Veja a documentação do OpenSSL SSL_export_keying_material para mais informações.

tlsSocket.getCertificate()

Adicionado em: v11.2.0

• Retorna: <Object>

Retorna um objeto representando o certificado local. O objeto retornado possui algumas propriedades correspondentes aos campos do certificado.

Veja tls.TLSSocket.getPeerCertificate() para um exemplo da estrutura do certificado.

Se não houver certificado local, será retornado um objeto vazio. Se o socket foi destruído, será retornado null.

tlsSocket.getCipher()

[Histórico]

Versão	Alterações
v13.4.0, v12.16.0	Retorna o nome do cifra IETF como standardName.
v12.0.0	Retorna a versão mínima da cifra, em vez de uma string fixa ('TLSv1/SSLv3').
v0.11.4	Adicionada em: v0.11.4

• Retorna: <Object>
  • name <string> Nome OpenSSL para o conjunto de cifras.
  • standardName <string> Nome IETF para o conjunto de cifras.
  • version <string> A versão mínima do protocolo TLS suportada por este conjunto de cifras. Para o protocolo negociado real, veja tls.TLSSocket.getProtocol().

Retorna um objeto contendo informações sobre o conjunto de cifras negociado.

Por exemplo, um protocolo TLSv1.2 com cifra AES256-SHA:

{
  "name": "AES256-SHA",
  "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
  "version": "SSLv3"
}

Veja SSL_CIPHER_get_name para mais informações.

tlsSocket.getEphemeralKeyInfo()

Adicionado em: v5.0.0

• Retorna: <Object>

Retorna um objeto representando o tipo, nome e tamanho do parâmetro de uma troca de chave efêmera em sigilo avançado perfeito em uma conexão de cliente. Retorna um objeto vazio quando a troca de chave não é efêmera. Como isso só é suportado em um socket de cliente; null é retornado se chamado em um socket de servidor. Os tipos suportados são 'DH' e 'ECDH'. A propriedade name está disponível apenas quando o tipo é 'ECDH'.

Por exemplo: { type: 'ECDH', name: 'prime256v1', size: 256 }.

tlsSocket.getFinished()

Adicionado em: v9.9.0

• Retorna: <Buffer> | <undefined> A última mensagem Finished que foi enviada para o socket como parte de um handshake SSL/TLS, ou undefined se nenhuma mensagem Finished foi enviada ainda.

Como as mensagens Finished são resumos de mensagem do handshake completo (com um total de 192 bits para TLS 1.0 e mais para SSL 3.0), elas podem ser usadas para procedimentos de autenticação externa quando a autenticação fornecida por SSL/TLS não é desejada ou não é suficiente.

Corresponde à rotina SSL_get_finished no OpenSSL e pode ser usada para implementar o tls-unique channel binding de RFC 5929.

tlsSocket.getPeerCertificate([detailed])

Adicionado em: v0.11.4

• detailed <boolean> Inclui a cadeia de certificados completa se true, caso contrário, inclui apenas o certificado do par.
• Retorna: <Object> Um objeto de certificado.

Retorna um objeto representando o certificado do par. Se o par não fornecer um certificado, um objeto vazio será retornado. Se o socket foi destruído, null será retornado.

Se a cadeia de certificados completa foi solicitada, cada certificado incluirá uma propriedade issuerCertificate contendo um objeto representando o certificado de seu emissor.

Objeto de certificado

[Histórico]

Versão	Alterações
v19.1.0, v18.13.0	Adicionar propriedade "ca".
v17.2.0, v16.14.0	Adicionar fingerprint512.
v11.4.0	Suporte a informações de chave pública de Curva Elíptica.

Um objeto de certificado possui propriedades correspondentes aos campos do certificado.

• ca <boolean> true se uma Autoridade de Certificação (CA), false caso contrário.
• raw <Buffer> Os dados do certificado X.509 codificados em DER.
• subject <Object> O assunto do certificado, descrito em termos de País (C), Estado ou Província (ST), Localidade (L), Organização (O), Unidade Organizacional (OU), e Nome Comum (CN). O Nome Comum é tipicamente um nome DNS com certificados TLS. Exemplo: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> O emissor do certificado, descrito nos mesmos termos que o subject.
• valid_from <string> A data e hora a partir da qual o certificado é válido.
• valid_to <string> A data e hora até a qual o certificado é válido.
• serialNumber <string> O número de série do certificado, como uma string hexadecimal. Exemplo: 'B9B0D332A1AA5635'.
• fingerprint <string> O resumo SHA-1 do certificado codificado em DER. É retornado como uma string hexadecimal separada por :. Exemplo: '2A:7A:C2:DD:...'.
• fingerprint256 <string> O resumo SHA-256 do certificado codificado em DER. É retornado como uma string hexadecimal separada por :. Exemplo: '2A:7A:C2:DD:...'.
• fingerprint512 <string> O resumo SHA-512 do certificado codificado em DER. É retornado como uma string hexadecimal separada por :. Exemplo: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (Opcional) O uso de chave estendido, um conjunto de OIDs.
• subjectaltname <string> (Opcional) Uma string contendo nomes concatenados para o assunto, uma alternativa aos nomes subject.
• infoAccess <Array> (Opcional) Uma matriz descrevendo o AuthorityInfoAccess, usado com OCSP.
• issuerCertificate <Object> (Opcional) O objeto de certificado do emissor. Para certificados autoassinados, esta pode ser uma referência circular.

O certificado pode conter informações sobre a chave pública, dependendo do tipo de chave.

Para chaves RSA, as seguintes propriedades podem ser definidas:

• bits <number> O tamanho em bits do RSA. Exemplo: 1024.
• exponent <string> O expoente RSA, como uma string em notação numérica hexadecimal. Exemplo: '0x010001'.
• modulus <string> O módulo RSA, como uma string hexadecimal. Exemplo: 'B56CE45CB7...'.
• pubkey <Buffer> A chave pública.

Para chaves EC, as seguintes propriedades podem ser definidas:

• pubkey <Buffer> A chave pública.
• bits <number> O tamanho da chave em bits. Exemplo: 256.
• asn1Curve <string> (Opcional) O nome ASN.1 do OID da curva elíptica. Curvas conhecidas são identificadas por um OID. Embora seja incomum, é possível que a curva seja identificada por suas propriedades matemáticas, caso em que não terá um OID. Exemplo: 'prime256v1'.
• nistCurve <string> (Opcional) O nome NIST para a curva elíptica, se tiver um (nem todas as curvas conhecidas receberam nomes pelo NIST). Exemplo: 'P-256'.

Exemplo de certificado:

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59D93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > }

tlsSocket.getPeerFinished()

Adicionado em: v9.9.0

• Retorna: <Buffer> | <undefined> A última mensagem Finished que é esperada ou que foi realmente recebida do socket como parte de um handshake SSL/TLS, ou undefined se não houver nenhuma mensagem Finished até o momento.

Como as mensagens Finished são digests de mensagem do handshake completo (com um total de 192 bits para TLS 1.0 e mais para SSL 3.0), elas podem ser usadas para procedimentos de autenticação externa quando a autenticação fornecida por SSL/TLS não é desejada ou não é suficiente.

Corresponde à rotina SSL_get_peer_finished no OpenSSL e pode ser usada para implementar o binding de canal tls-unique do RFC 5929.

tlsSocket.getPeerX509Certificate()

Adicionado em: v15.9.0

• Retorna: <X509Certificate>

Retorna o certificado do peer como um objeto <X509Certificate>.

Se não houver certificado de peer, ou se o socket foi destruído, undefined será retornado.

tlsSocket.getProtocol()

Adicionado em: v5.7.0

• Retorna: <string> | <null>

Retorna uma string contendo a versão do protocolo SSL/TLS negociada da conexão atual. O valor 'unknown' será retornado para sockets conectados que não concluíram o processo de handshake. O valor null será retornado para sockets de servidor ou sockets de cliente desconectados.

As versões do protocolo são:

• 'SSLv3'
• 'TLSv1'
• 'TLSv1.1'
• 'TLSv1.2'
• 'TLSv1.3'

Veja a documentação do OpenSSL SSL_get_version para mais informações.

tlsSocket.getSession()

Adicionado em: v0.11.4

• <Buffer>

Retorna os dados da sessão TLS ou undefined se nenhuma sessão foi negociada. No cliente, os dados podem ser fornecidos à opção session de tls.connect() para retomar a conexão. No servidor, pode ser útil para depuração.

Veja Retomada de Sessão para mais informações.

Nota: getSession() funciona apenas para TLSv1.2 e inferior. Para TLSv1.3, os aplicativos devem usar o evento 'session' (ele também funciona para TLSv1.2 e inferior).

tlsSocket.getSharedSigalgs()

Adicionado em: v12.11.0

• Retorna: <Array> Lista de algoritmos de assinatura compartilhados entre o servidor e o cliente, na ordem de preferência decrescente.

Veja SSL_get_shared_sigalgs para mais informações.

tlsSocket.getTLSTicket()

Adicionado em: v0.11.4

• <Buffer>

Para um cliente, retorna o ticket de sessão TLS se houver um disponível, ou undefined. Para um servidor, sempre retorna undefined.

Pode ser útil para depuração.

Veja Retomada de Sessão para mais informações.

tlsSocket.getX509Certificate()

Adicionado em: v15.9.0

• Retorna: <X509Certificate>

Retorna o certificado local como um objeto <X509Certificate>.

Se não houver nenhum certificado local, ou se o socket tiver sido destruído, undefined será retornado.

tlsSocket.isSessionReused()

Adicionado em: v0.5.6

• Retorna: <boolean> true se a sessão foi reutilizada, false caso contrário.

Veja Retomada de Sessão para mais informações.

tlsSocket.localAddress

Adicionado em: v0.11.4

• <string>

Retorna a representação em string do endereço IP local.

tlsSocket.localPort

Adicionado em: v0.11.4

• <integer>

Retorna a representação numérica da porta local.

tlsSocket.remoteAddress

Adicionado em: v0.11.4

• <string>

Retorna a representação em string do endereço IP remoto. Por exemplo, '74.125.127.100' ou '2001:4860:a005::68'.

tlsSocket.remoteFamily

Adicionado em: v0.11.4

• <string>

Retorna a representação em string da família de IP remoto. 'IPv4' ou 'IPv6'.

tlsSocket.remotePort

Adicionado em: v0.11.4

• <integer>

Retorna a representação numérica da porta remota. Por exemplo, 443.

tlsSocket.renegotiate(options, callback)

[Histórico]

Versão	Alterações
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v0.11.8	Adicionada em: v0.11.8

• options <Object>

  • rejectUnauthorized <boolean> Se não for false, o certificado do servidor é verificado contra a lista de AAs fornecidas. Um evento 'error' é emitido se a verificação falhar; err.code contém o código de erro OpenSSL. Padrão: true.
  • requestCert

• callback <Function> Se renegotiate() retornar true, o callback é anexado uma vez ao evento 'secure'. Se renegotiate() retornar false, callback será chamado no próximo tick com um erro, a menos que o tlsSocket tenha sido destruído, caso em que callback não será chamado.

• Retorna: <boolean> true se a renegociação foi iniciada, false caso contrário.

O método tlsSocket.renegotiate() inicia um processo de renegociação TLS. Após a conclusão, a função callback receberá um único argumento que é um Error (se a solicitação falhar) ou null.

Este método pode ser usado para solicitar o certificado de um par após a conexão segura ter sido estabelecida.

Ao executar como servidor, o socket será destruído com um erro após o tempo limite handshakeTimeout.

Para TLSv1.3, a renegociação não pode ser iniciada, pois não é suportada pelo protocolo.

tlsSocket.setKeyCert(context)

Adicionado em: v22.5.0, v20.17.0

• context <Object> | <tls.SecureContext> Um objeto contendo pelo menos as propriedades key e cert das options de tls.createSecureContext(), ou um objeto de contexto TLS criado com tls.createSecureContext() em si.

O método tlsSocket.setKeyCert() define a chave privada e o certificado a serem usados para o socket. Isso é principalmente útil se você deseja selecionar um certificado de servidor de um ALPNCallback de um servidor TLS.

tlsSocket.setMaxSendFragment(size)

Adicionado em: v0.11.11

• size <number> O tamanho máximo do fragmento TLS. O valor máximo é 16384. Padrão: 16384.
• Retorna: <boolean>

O método tlsSocket.setMaxSendFragment() define o tamanho máximo do fragmento TLS. Retorna true se a definição do limite foi bem-sucedida; false caso contrário.

Tamanhos de fragmento menores diminuem a latência de buffer no cliente: fragmentos maiores são armazenados em buffer pela camada TLS até que o fragmento inteiro seja recebido e sua integridade seja verificada; fragmentos grandes podem abranger várias viagens de ida e volta e seu processamento pode ser atrasado devido à perda ou reordenação de pacotes. No entanto, fragmentos menores adicionam bytes de enquadramento TLS extras e sobrecarga de CPU, o que pode diminuir a taxa de transferência geral do servidor.

tls.checkServerIdentity(hostname, cert)

[Histórico]

Versão	Alterações
v17.3.1, v16.13.2, v14.18.3, v12.22.9	O suporte para nomes alternativos de assunto uniformResourceIdentifier foi desabilitado em resposta ao CVE-2021-44531.
v0.8.4	Adicionado em: v0.8.4

• hostname <string> O nome do host ou endereço IP para verificar o certificado.
• cert <Object> Um objeto de certificado representando o certificado do par.
• Retorna: <Error> | <undefined>

Verifica se o certificado cert foi emitido para hostname.

Retorna o objeto <Error>, preenchendo-o com reason, host e cert em caso de falha. Em caso de sucesso, retorna <undefined>.

Esta função destina-se a ser usada em combinação com a opção checkServerIdentity que pode ser passada para tls.connect() e, como tal, opera em um objeto de certificado. Para outros fins, considere usar x509.checkHost() em vez disso.

Esta função pode ser sobrescrita fornecendo uma função alternativa como a opção options.checkServerIdentity que é passada para tls.connect(). A função de sobrescrita pode chamar tls.checkServerIdentity(), é claro, para aumentar as verificações feitas com verificação adicional.

Esta função só é chamada se o certificado passou em todas as outras verificações, como ter sido emitido por uma CA confiável (options.ca).

Versões anteriores do Node.js aceitavam incorretamente certificados para um determinado hostname se um nome alternativo de assunto uniformResourceIdentifier correspondente estivesse presente (consulte CVE-2021-44531). Aplicativos que desejam aceitar nomes alternativos de assunto uniformResourceIdentifier podem usar uma função options.checkServerIdentity personalizada que implementa o comportamento desejado.

tls.connect(options[, callback])

[Histórico]

Versão	Alterações
v15.1.0, v14.18.0	Adicionado a opção onread.
v14.1.0, v13.14.0	A opção highWaterMark agora é aceita.
v13.6.0, v12.16.0	A opção pskCallback agora é suportada.
v12.9.0	Suporte à opção allowHalfOpen.
v12.4.0	A opção hints agora é suportada.
v12.2.0	A opção enableTrace agora é suportada.
v11.8.0, v10.16.0	A opção timeout agora é suportada.
v8.0.0	A opção lookup agora é suportada.
v8.0.0	A opção ALPNProtocols pode ser um TypedArray ou DataView agora.
v5.0.0	Opções ALPN agora são suportadas.
v5.3.0, v4.7.0	A opção secureContext agora é suportada.
v0.11.3	Adicionado em: v0.11.3

• options <Object>

  • enableTrace: Veja tls.createServer()
  • host <string> Host ao qual o cliente deve se conectar. Padrão: 'localhost'.
  • port <number> Porta à qual o cliente deve se conectar.
  • path <string> Cria conexão de socket Unix para o caminho. Se esta opção for especificada, host e port serão ignorados.
  • socket <stream.Duplex> Estabelece conexão segura em um socket fornecido em vez de criar um novo socket. Normalmente, esta é uma instância de net.Socket, mas qualquer stream Duplex é permitido. Se esta opção for especificada, path, host e port serão ignorados, exceto para validação de certificado. Geralmente, um socket já está conectado quando passado para tls.connect(), mas pode ser conectado posteriormente. A conexão/desconexão/destruição do socket é responsabilidade do usuário; chamar tls.connect() não causará a chamada de net.connect().
  • allowHalfOpen <boolean> Se definido como false, o socket encerrará automaticamente o lado gravável quando o lado legível terminar. Se a opção socket estiver definida, esta opção não terá efeito. Veja a opção allowHalfOpen de net.Socket para detalhes. Padrão: false.
  • rejectUnauthorized <boolean> Se não for false, o certificado do servidor é verificado contra a lista de CAs fornecidas. Um evento 'error' é emitido se a verificação falhar; err.code contém o código de erro OpenSSL. Padrão: true.
  • pskCallback <Function> Para negociação TLS-PSK, veja Chaves pré-compartilhadas.
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Uma matriz de strings, Buffers, TypedArrays ou DataViews, ou um único Buffer, TypedArray ou DataView contendo os protocolos ALPN suportados. Buffers devem ter o formato [len][name][len][name]... por exemplo, '\x08http/1.1\x08http/1.0', onde o byte len é o comprimento do próximo nome do protocolo. Passar uma matriz geralmente é muito mais simples, por exemplo, ['http/1.1', 'http/1.0']. Protocolos anteriores na lista têm preferência mais alta do que aqueles posteriores.
  • servername: <string> Nome do servidor para a extensão SNI (Server Name Indication) TLS. É o nome do host ao qual está sendo conectado e deve ser um nome de host, e não um endereço IP. Pode ser usado por um servidor multi-homing para escolher o certificado correto a ser apresentado ao cliente, veja a opção SNICallback para tls.createServer().
  • checkServerIdentity(servername, cert) <Function> Uma função de callback a ser usada (em vez da função tls.checkServerIdentity() embutida) ao verificar o nome do host do servidor (ou o servername fornecido quando explicitamente definido) contra o certificado. Isso deve retornar um <Error> se a verificação falhar. O método deve retornar undefined se o servername e o cert forem verificados.
  • session <Buffer> Uma instância Buffer, contendo a sessão TLS.
  • minDHSize <number> Tamanho mínimo do parâmetro DH em bits para aceitar uma conexão TLS. Quando um servidor oferece um parâmetro DH com um tamanho menor que minDHSize, a conexão TLS é destruída e um erro é lançado. Padrão: 1024.
  • highWaterMark: <number> Consistente com o parâmetro highWaterMark do stream legível. Padrão: 16 * 1024.
  • secureContext: Objeto de contexto TLS criado com tls.createSecureContext(). Se um secureContext não for fornecido, um será criado passando todo o objeto options para tls.createSecureContext().
  • onread <Object> Se a opção socket estiver ausente, os dados recebidos são armazenados em um único buffer e passados para o callback fornecido quando os dados chegam no socket, caso contrário, a opção é ignorada. Veja a opção onread de net.Socket para detalhes.
  • ...: Opções tls.createSecureContext() que são usadas se a opção secureContext estiver ausente, caso contrário, elas serão ignoradas.
  • ...: Qualquer opção socket.connect() não listada anteriormente.

• callback <Function>

• Retorna: <tls.TLSSocket>

A função callback, se especificada, será adicionada como um ouvinte para o evento 'secureConnect'.

tls.connect() retorna um objeto tls.TLSSocket.

Ao contrário da API https, tls.connect() não ativa a extensão SNI (Server Name Indication) por padrão, o que pode fazer com que alguns servidores retornem um certificado incorreto ou rejeitem a conexão completamente. Para ativar o SNI, defina a opção servername além de host.

O seguinte ilustra um cliente para o exemplo de servidor de eco de tls.createServer():

ESM

// Assume um servidor de eco que está ouvindo na porta 8000.
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // Necessário apenas se o servidor exigir autenticação de certificado do cliente.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necessário apenas se o servidor usar um certificado autoassinado.
  ca: [readFileSync('server-cert.pem')],

  // Necessário apenas se o certificado do servidor não for para "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('cliente conectado', socket.authorized ? 'autorizado' : 'não autorizado')
  stdin.pipe(socket)
  stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('servidor encerra a conexão')
})

CJS

// Assume um servidor de eco que está ouvindo na porta 8000.
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // Necessário apenas se o servidor exigir autenticação de certificado do cliente.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necessário apenas se o servidor usar um certificado autoassinado.
  ca: [readFileSync('server-cert.pem')],

  // Necessário apenas se o certificado do servidor não for para "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('cliente conectado', socket.authorized ? 'autorizado' : 'não autorizado')
  process.stdin.pipe(socket)
  process.stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('servidor encerra a conexão')
})

Para gerar o certificado e a chave para este exemplo, execute:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout client-key.pem -out client-cert.pem

Então, para gerar o certificado server-cert.pem para este exemplo, execute:

openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \
  -inkey client-key.pem -in client-cert.pem

tls.connect(path[, options][, callback])

Adicionado em: v0.11.3

• path <string> Valor padrão para options.path.
• options <Object> Veja tls.connect().
• callback <Function> Veja tls.connect().
• Retorna: <tls.TLSSocket>

Igual a tls.connect() exceto que path pode ser fornecido como um argumento em vez de uma opção.

Uma opção de caminho, se especificada, terá precedência sobre o argumento de caminho.

tls.connect(port[, host][, options][, callback])

Adicionado em: v0.11.3

• port <number> Valor padrão para options.port.
• host <string> Valor padrão para options.host.
• options <Object> Veja tls.connect().
• callback <Function> Veja tls.connect().
• Retorna: <tls.TLSSocket>

Igual a tls.connect() exceto que port e host podem ser fornecidos como argumentos em vez de opções.

Uma opção de porta ou host, se especificada, terá precedência sobre qualquer argumento de porta ou host.

tls.createSecureContext([options])

[Histórico]

Versão	Alterações
v22.9.0, v20.18.0	A opção allowPartialTrustChain foi adicionada.
v22.4.0, v20.16.0	As opções clientCertEngine, privateKeyEngine e privateKeyIdentifier dependem do suporte do mecanismo personalizado no OpenSSL, que está obsoleto no OpenSSL 3.
v19.8.0, v18.16.0	A opção dhparam agora pode ser definida como 'auto' para habilitar DHE com parâmetros bem conhecidos apropriados.
v12.12.0	Adicionadas as opções privateKeyIdentifier e privateKeyEngine para obter a chave privada de um mecanismo OpenSSL.
v12.11.0	Adicionada a opção sigalgs para substituir os algoritmos de assinatura suportados.
v12.0.0	Suporte TLSv1.3 adicionado.
v11.5.0	A opção ca: agora suporta BEGIN TRUSTED CERTIFICATE.
v11.4.0, v10.16.0	O minVersion e o maxVersion podem ser usados para restringir as versões de protocolo TLS permitidas.
v10.0.0	O ecdhCurve não pode mais ser definido como false devido a uma alteração no OpenSSL.
v9.3.0	O parâmetro options agora pode incluir clientCertEngine.
v9.0.0	A opção ecdhCurve agora pode ser vários nomes de curva separados por ':' ou 'auto'.
v7.3.0	Se a opção key for uma matriz, as entradas individuais não precisam mais de uma propriedade passphrase. As entradas Array também podem ser apenas strings ou Buffers agora.
v5.2.0	A opção ca agora pode ser uma única string contendo vários certificados CA.
v0.11.13	Adicionada em: v0.11.13

• options <Object>
  • allowPartialTrustChain <boolean> Tratar certificados intermediários (não autoassinados) na lista de certificados CA de confiança como confiáveis.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> Opcionalmente substitua os certificados CA confiáveis. O padrão é confiar nas CAs bem conhecidas selecionadas pela Mozilla. As CAs da Mozilla são completamente substituídas quando as CAs são especificadas explicitamente usando esta opção. O valor pode ser uma string ou Buffer, ou uma Array de strings e/ou Buffers. Qualquer string ou Buffer pode conter várias CAs PEM concatenadas. O certificado do par deve ser encadeável a uma CA confiável pelo servidor para que a conexão seja autenticada. Ao usar certificados que não são encadeáveis a uma CA bem conhecida, a CA do certificado deve ser especificada explicitamente como confiável ou a conexão falhará na autenticação. Se o par usar um certificado que não corresponda ou não seja encadeado a uma das CAs padrão, use a opção ca para fornecer um certificado CA que o certificado do par possa corresponder ou encadear. Para certificados autoassinados, o certificado é sua própria CA e deve ser fornecido. Para certificados codificados em PEM, os tipos suportados são "TRUSTED CERTIFICATE", "X509 CERTIFICATE" e "CERTIFICATE". Veja também tls.rootCertificates.
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> Cadeias de certificados em formato PEM. Uma cadeia de certificados deve ser fornecida por chave privada. Cada cadeia de certificados deve consistir no certificado formatado em PEM para uma key privada fornecida, seguida pelos certificados intermediários formatados em PEM (se houver), em ordem, e não incluindo a CA raiz (a CA raiz deve ser pré-conhecida pelo par, consulte ca). Ao fornecer várias cadeias de certificados, elas não precisam estar na mesma ordem que suas chaves privadas em key. Se os certificados intermediários não forem fornecidos, o par não poderá validar o certificado e a troca de mensagens falhará.
  • sigalgs <string> Lista separada por dois pontos de algoritmos de assinatura suportados. A lista pode conter algoritmos de resumo (SHA256, MD5 etc.), algoritmos de chave pública (RSA-PSS, ECDSA etc.), combinação de ambos (por exemplo, 'RSA+SHA384') ou nomes de esquemas TLS v1.3 (por exemplo, rsa_pss_pss_sha512). Consulte as páginas manuais do OpenSSL para obter mais informações.
  • ciphers <string> Especificação do conjunto de cifras, substituindo o padrão. Para obter mais informações, consulte Modificando o conjunto de cifras TLS padrão. As cifras permitidas podem ser obtidas por meio de tls.getCiphers(). Os nomes das cifras devem ser maiúsculos para que o OpenSSL os aceite.
  • clientCertEngine <string> Nome de um mecanismo OpenSSL que pode fornecer o certificado do cliente. Obsoleto.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> CRLs (Listas de Revogação de Certificados) formatadas em PEM.
  • dhparam <string> | <Buffer> 'auto' ou parâmetros Diffie-Hellman personalizados, necessários para o sigilo avançado perfeito não ECDHE [/api/tls#perfect-forward-secrecy]. Se omitido ou inválido, os parâmetros são descartados silenciosamente e as cifras DHE não estarão disponíveis. O sigilo avançado perfeito baseado em ECDHE [/api/tls#perfect-forward-secrecy] ainda estará disponível.
  • ecdhCurve <string> Uma string descrevendo uma curva nomeada ou uma lista separada por dois pontos de NIDs ou nomes de curva, por exemplo P-521:P-384:P-256, para usar para o acordo de chave ECDH. Defina como auto para selecionar a curva automaticamente. Use crypto.getCurves() para obter uma lista de nomes de curva disponíveis. Em versões recentes, openssl ecparam -list_curves também exibirá o nome e a descrição de cada curva elíptica disponível. Padrão: tls.DEFAULT_ECDH_CURVE.
  • honorCipherOrder <boolean> Tentar usar as preferências do conjunto de cifras do servidor em vez das do cliente. Quando true, faz com que SSL_OP_CIPHER_SERVER_PREFERENCE seja definido em secureOptions, veja Opções OpenSSL para obter mais informações.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Chaves privadas em formato PEM. PEM permite a opção de chaves privadas criptografadas. As chaves criptografadas serão descriptografadas com options.passphrase. Várias chaves usando algoritmos diferentes podem ser fornecidas como uma matriz de strings ou buffers de chave não criptografados, ou uma matriz de objetos na forma {pem: \<string|buffer\>[, passphrase: \<string\>]}. A forma de objeto só pode ocorrer em uma matriz. object.passphrase é opcional. As chaves criptografadas serão descriptografadas com object.passphrase se fornecido, ou options.passphrase se não for.
  • privateKeyEngine <string> Nome de um mecanismo OpenSSL para obter a chave privada. Deve ser usado junto com privateKeyIdentifier. Obsoleto.
  • privateKeyIdentifier <string> Identificador de uma chave privada gerenciada por um mecanismo OpenSSL. Deve ser usado junto com privateKeyEngine. Não deve ser definido junto com key, pois ambas as opções definem uma chave privada de maneiras diferentes. Obsoleto.
  • maxVersion <string> Opcionalmente, define a versão máxima do TLS a ser permitida. Um de 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' ou 'TLSv1'. Não pode ser especificado junto com a opção secureProtocol; use um ou outro. Padrão: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> Opcionalmente, define a versão mínima do TLS a ser permitida. Um de 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' ou 'TLSv1'. Não pode ser especificado junto com a opção secureProtocol; use um ou outro. Evite definir para menos que TLSv1.2, mas pode ser necessário para interoperabilidade. Versões anteriores ao TLSv1.2 podem exigir a redução do Nível de Segurança do OpenSSL. Padrão: tls.DEFAULT_MIN_VERSION.
  • passphrase <string> Senha compartilhada usada para uma única chave privada e/ou um PFX.
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Chave privada e cadeia de certificados codificados em PFX ou PKCS12. pfx é uma alternativa para fornecer key e cert individualmente. PFX geralmente é criptografado, se for, passphrase será usado para descriptografá-lo. Vários PFX podem ser fornecidos como uma matriz de buffers PFX não criptografados, ou uma matriz de objetos na forma {buf: \<string|buffer\>[, passphrase: \<string\>]}. A forma de objeto só pode ocorrer em uma matriz. object.passphrase é opcional. Os PFX criptografados serão descriptografados com object.passphrase se fornecido, ou options.passphrase se não for.
  • secureOptions <number> Opcionalmente, afeta o comportamento do protocolo OpenSSL, o que geralmente não é necessário. Isso deve ser usado com cuidado, se houver! O valor é uma máscara de bits numérica das opções SSL_OP_* de Opções OpenSSL.
  • secureProtocol <string> Mecanismo herdado para selecionar a versão do protocolo TLS a ser usada, não suporta o controle independente da versão mínima e máxima e não suporta a limitação do protocolo a TLSv1.3. Use minVersion e maxVersion em vez disso. Os valores possíveis são listados como SSL_METHODS, use os nomes das funções como strings. Por exemplo, use 'TLSv1_1_method' para forçar a versão 1.1 do TLS ou 'TLS_method' para permitir qualquer versão do protocolo TLS até o TLSv1.3. Não é recomendável usar versões do TLS inferiores a 1.2, mas pode ser necessário para interoperabilidade. Padrão: nenhum, consulte minVersion.
  • sessionIdContext <string> Identificador opaco usado por servidores para garantir que o estado da sessão não seja compartilhado entre aplicativos. Não usado por clientes.
  • ticketKeys: <Buffer> 48 bytes de dados pseudorandom criptograficamente fortes. Consulte Retomada de Sessão para obter mais informações.
  • sessionTimeout <number> O número de segundos após o qual uma sessão TLS criada pelo servidor não será mais retomada. Consulte Retomada de Sessão para obter mais informações. Padrão: 300.

tls.createServer() define o valor padrão da opção honorCipherOrder como true, outras APIs que criam contextos seguros não o definem.

tls.createServer() usa um valor de hash SHA1 truncado de 128 bits gerado a partir de process.argv como o valor padrão da opção sessionIdContext, outras APIs que criam contextos seguros não têm valor padrão.

O método tls.createSecureContext() cria um objeto SecureContext. Ele pode ser usado como um argumento para várias APIs tls, como server.addContext(), mas não possui métodos públicos. O construtor tls.Server e o método tls.createServer() não suportam a opção secureContext.

Uma chave é obrigatória para cifras que usam certificados. key ou pfx podem ser usados para fornecê-la.

Se a opção ca não for fornecida, o Node.js usará por padrão a lista de CAs publicamente confiáveis da Mozilla.

Parâmetros DHE personalizados são desaconselhados em favor da nova opção dhparam: 'auto'. Quando definido como 'auto', parâmetros DHE bem conhecidos de força suficiente serão selecionados automaticamente. Caso contrário, se necessário, openssl dhparam pode ser usado para criar parâmetros personalizados. O comprimento da chave deve ser maior ou igual a 1024 bits, caso contrário, um erro será lançado. Embora 1024 bits sejam permitidos, use 2048 bits ou mais para segurança mais forte.

tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])

[Histórico]

Versão	Alterações
v5.0.0	Opções ALPN agora são suportadas.
v0.11.3	Obsoleto desde: v0.11.3
v0.3.2	Adicionado em: v0.3.2

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use tls.TLSSocket em vez disso.

• context <Object> Um objeto de contexto seguro conforme retornado por tls.createSecureContext()
• isServer <boolean> true para especificar que esta conexão TLS deve ser aberta como um servidor.
• requestCert <boolean> true para especificar se um servidor deve solicitar um certificado de um cliente de conexão. Aplica-se apenas quando isServer é true.
• rejectUnauthorized <boolean> Se não for false, um servidor rejeita automaticamente clientes com certificados inválidos. Aplica-se apenas quando isServer é true.
• options
  • enableTrace: Veja tls.createServer()
  • secureContext: Um objeto de contexto TLS de tls.createSecureContext()
  • isServer: Se true, o socket TLS será instanciado no modo servidor. Padrão: false.
  • server <net.Server> Uma instância net.Server
  • requestCert: Veja tls.createServer()
  • rejectUnauthorized: Veja tls.createServer()
  • ALPNProtocols: Veja tls.createServer()
  • SNICallback: Veja tls.createServer()
  • session <Buffer> Uma instância Buffer contendo uma sessão TLS.
  • requestOCSP <boolean> Se true, especifica que a extensão de solicitação de status OCSP será adicionada ao client hello e um evento 'OCSPResponse' será emitido no socket antes de estabelecer uma comunicação segura.

Cria um novo objeto de par seguro com dois fluxos, um dos quais lê e grava os dados criptografados e o outro lê e grava os dados em texto claro. Geralmente, o fluxo criptografado é canalizado para/de um fluxo de dados criptografados de entrada e o de texto claro é usado como uma substituição para o fluxo criptografado inicial.

tls.createSecurePair() retorna um objeto tls.SecurePair com propriedades de fluxo cleartext e encrypted.

Usar cleartext tem a mesma API que tls.TLSSocket.

O método tls.createSecurePair() agora está obsoleto em favor de tls.TLSSocket(). Por exemplo, o código:

pair = tls.createSecurePair(/* ... */)
pair.encrypted.pipe(socket)
socket.pipe(pair.encrypted)

pode ser substituído por:

secureSocket = tls.TLSSocket(socket, options)

onde secureSocket tem a mesma API que pair.cleartext.

tls.createServer([options][, secureConnectionListener])

[Histórico]

Versão	Alterações
v22.4.0, v20.16.0	A opção clientCertEngine depende do suporte do mecanismo personalizado no OpenSSL, que está obsoleto no OpenSSL 3.
v19.0.0	Se ALPNProtocols estiver definido, as conexões de entrada que enviam uma extensão ALPN sem protocolos suportados são encerradas com um alerta fatal no_application_protocol.
v20.4.0, v18.19.0	O parâmetro options agora pode incluir ALPNCallback.
v12.3.0	O parâmetro options agora suporta opções net.createServer().
v9.3.0	O parâmetro options agora pode incluir clientCertEngine.
v8.0.0	A opção ALPNProtocols agora pode ser um TypedArray ou DataView.
v5.0.0	As opções ALPN agora são suportadas.
v0.3.2	Adicionado em: v0.3.2

• options <Object>

  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Uma matriz de strings, Buffers, TypedArrays ou DataViews, ou um único Buffer, TypedArray ou DataView contendo os protocolos ALPN suportados. Os Buffers devem ter o formato [len][name][len][name]... por exemplo, 0x05hello0x05world, onde o primeiro byte é o comprimento do próximo nome do protocolo. Passar uma matriz geralmente é muito mais simples, por exemplo, ['hello', 'world']. (Os protocolos devem ser ordenados por sua prioridade.)
  • ALPNCallback: <Function> Se definido, será chamado quando um cliente abrir uma conexão usando a extensão ALPN. Um argumento será passado para a função de retorno de chamada: um objeto contendo os campos servername e protocols, respectivamente contendo o nome do servidor da extensão SNI (se houver) e uma matriz de strings de nomes de protocolo ALPN. A função de retorno de chamada deve retornar uma das strings listadas em protocols, que será retornada ao cliente como o protocolo ALPN selecionado, ou undefined, para rejeitar a conexão com um alerta fatal. Se uma string for retornada que não corresponde a um dos protocolos ALPN do cliente, um erro será lançado. Esta opção não pode ser usada com a opção ALPNProtocols, e definir ambas as opções lançará um erro.
  • clientCertEngine <string> Nome de um mecanismo OpenSSL que pode fornecer o certificado do cliente. Obsoleto.
  • enableTrace <boolean> Se true, tls.TLSSocket.enableTrace() será chamado em novas conexões. O rastreamento pode ser ativado após o estabelecimento da conexão segura, mas esta opção deve ser usada para rastrear a configuração da conexão segura. Padrão: false.
  • handshakeTimeout <number> Aborta a conexão se o handshake SSL/TLS não for concluído no número especificado de milissegundos. Um 'tlsClientError' é emitido no objeto tls.Server sempre que um handshake tiver tempo limite. Padrão: 120000 (120 segundos).
  • rejectUnauthorized <boolean> Se não for false, o servidor rejeitará qualquer conexão que não esteja autorizada com a lista de CAs fornecidas. Esta opção só tem efeito se requestCert for true. Padrão: true.
  • requestCert <boolean> Se true, o servidor solicitará um certificado dos clientes que se conectarem e tentarão verificar esse certificado. Padrão: false.
  • sessionTimeout <number> O número de segundos após o qual uma sessão TLS criada pelo servidor não poderá mais ser retomada. Veja Retomada de Sessão para mais informações. Padrão: 300.
  • SNICallback(servername, callback) <Function> Uma função que será chamada se o cliente suportar a extensão SNI TLS. Dois argumentos serão passados quando chamado: servername e callback. callback é uma função de retorno de chamada com prioridade de erro que recebe dois argumentos opcionais: error e ctx. ctx, se fornecido, é uma instância SecureContext. tls.createSecureContext() pode ser usado para obter um SecureContext adequado. Se callback for chamado com um argumento ctx falso, o contexto seguro padrão do servidor será usado. Se SNICallback não foi fornecido, a função de retorno de chamada padrão com API de alto nível será usada (veja abaixo).
  • ticketKeys: <Buffer> 48 bytes de dados pseudorandom criptograficamente fortes. Veja Retomada de Sessão para mais informações.
  • pskCallback <Function> Para negociação TLS-PSK, veja Pre-shared keys.
  • pskIdentityHint <string> dica opcional para enviar a um cliente para ajudar na seleção da identidade durante a negociação TLS-PSK. Será ignorado no TLS 1.3. Ao falhar na configuração de pskIdentityHint, 'tlsClientError' será emitido com o código 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED'.
  • ...: Qualquer opção tls.createSecureContext() pode ser fornecida. Para servidores, as opções de identidade (pfx, key/cert ou pskCallback) geralmente são necessárias.
  • ...: Qualquer opção net.createServer() pode ser fornecida.

• secureConnectionListener <Function>

• Retorna: <tls.Server>

Cria um novo tls.Server. O secureConnectionListener, se fornecido, é automaticamente definido como um ouvinte para o evento 'secureConnection'.

As opções ticketKeys são automaticamente compartilhadas entre os trabalhadores do módulo node:cluster.

O seguinte ilustra um servidor de eco simples:

ESM

import { createServer } from 'node:tls'
import { readFileSync } from 'node:fs'

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // Isso é necessário apenas se estiver usando autenticação de certificado de cliente.
  requestCert: true,

  // Isso é necessário apenas se o cliente usar um certificado autoassinado.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('servidor conectado', socket.authorized ? 'autorizado' : 'não autorizado')
  socket.write('bem-vindo!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('servidor vinculado')
})

CJS

const { createServer } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // Isso é necessário apenas se estiver usando autenticação de certificado de cliente.
  requestCert: true,

  // Isso é necessário apenas se o cliente usar um certificado autoassinado.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('servidor conectado', socket.authorized ? 'autorizado' : 'não autorizado')
  socket.write('bem-vindo!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('servidor vinculado')
})

Para gerar o certificado e a chave para este exemplo, execute:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout server-key.pem -out server-cert.pem

Então, para gerar o certificado client-cert.pem para este exemplo, execute:

openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
  -inkey server-key.pem -in server-cert.pem

O servidor pode ser testado conectando-se a ele usando o cliente de exemplo de tls.connect().

tls.getCiphers()

Adicionado em: v0.10.2

• Retorna: <string[]>

Retorna um array com os nomes dos cifras TLS suportados. Os nomes são minúsculos por razões históricas, mas devem ser convertidos para maiúsculas para serem usados na opção ciphers de tls.createSecureContext().

Nem todos os cifras suportados são ativados por padrão. Veja Modificando o conjunto de cifras TLS padrão.

Os nomes de cifra que começam com 'tls_' são para TLSv1.3, todos os outros são para TLSv1.2 e abaixo.

console.log(tls.getCiphers()) // ['aes128-gcm-sha256', 'aes128-sha', ...]

tls.rootCertificates

Adicionado em: v12.3.0

• <string[]>

Um array imutável de strings representando os certificados raiz (em formato PEM) do armazenamento de CA do Mozilla incluído, conforme fornecido pela versão atual do Node.js.

O armazenamento de CA incluído, conforme fornecido pelo Node.js, é um instantâneo do armazenamento de CA do Mozilla que é fixado no momento da liberação. É idêntico em todas as plataformas suportadas.

tls.DEFAULT_ECDH_CURVE

[Histórico]

Versão	Alterações
v10.0.0	Valor padrão alterado para 'auto'.
v0.11.13	Adicionada em: v0.11.13

O nome da curva padrão a ser usado para o acordo de chave ECDH em um servidor tls. O valor padrão é 'auto'. Veja tls.createSecureContext() para mais informações.

tls.DEFAULT_MAX_VERSION

Adicionado em: v11.4.0

• <string> O valor padrão da opção maxVersion de tls.createSecureContext(). Pode ser atribuído a qualquer uma das versões de protocolo TLS suportadas, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' ou 'TLSv1'. Padrão: 'TLSv1.3', a menos que alterado usando opções de CLI. Usando --tls-max-v1.2 define o padrão como 'TLSv1.2'. Usando --tls-max-v1.3 define o padrão como 'TLSv1.3'. Se várias opções forem fornecidas, o máximo mais alto será usado.

tls.DEFAULT_MIN_VERSION

Adicionado em: v11.4.0

• <string> O valor padrão da opção minVersion de tls.createSecureContext(). Pode ser atribuído qualquer uma das versões de protocolo TLS suportadas, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' ou 'TLSv1'. Versões anteriores ao TLSv1.2 podem exigir o downgrade do Nível de Segurança OpenSSL. Padrão: 'TLSv1.2', a menos que alterado usando opções de CLI. Usar --tls-min-v1.0 define o padrão como 'TLSv1'. Usar --tls-min-v1.1 define o padrão como 'TLSv1.1'. Usar --tls-min-v1.3 define o padrão como 'TLSv1.3'. Se várias das opções forem fornecidas, o mínimo mais baixo será usado.

tls.DEFAULT_CIPHERS

Adicionado em: v19.8.0, v18.16.0

• <string> O valor padrão da opção ciphers de tls.createSecureContext(). Pode ser atribuído qualquer um dos cifras OpenSSL suportados. O padrão é o conteúdo de crypto.constants.defaultCoreCipherList, a menos que alterado usando opções de CLI com --tls-default-ciphers.