TLS (SSL)

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código Fuente: lib/tls.js

El módulo node:tls proporciona una implementación de los protocolos Transport Layer Security (TLS) y Secure Socket Layer (SSL) que se construye sobre OpenSSL. Se puede acceder al módulo usando:

ESM

import tls from 'node:tls'

CJS

const tls = require('node:tls')

Determinando si el soporte de crypto no está disponible

Es posible que Node.js se construya sin incluir soporte para el módulo node:crypto. En tales casos, intentar importar desde tls o llamar a require('node:tls') resultará en un error que se lanzará.

Al usar CommonJS, el error lanzado se puede capturar usando try/catch:

let tls
try {
  tls = require('node:tls')
} catch (err) {
  console.error('¡El soporte de tls está deshabilitado!')
}

Al usar la palabra clave léxica ESM import, el error solo se puede capturar si se registra un controlador para process.on('uncaughtException') antes de que se realice cualquier intento de cargar el módulo (usando, por ejemplo, un módulo de precarga).

Al usar ESM, si existe la posibilidad de que el código pueda ejecutarse en una compilación de Node.js donde el soporte de crypto no esté habilitado, considere usar la función import() en lugar de la palabra clave léxica import:

let tls
try {
  tls = await import('node:tls')
} catch (err) {
  console.error('¡El soporte de tls está deshabilitado!')
}

Conceptos de TLS/SSL

TLS/SSL es un conjunto de protocolos que se basan en una infraestructura de clave pública (PKI) para habilitar la comunicación segura entre un cliente y un servidor. En la mayoría de los casos comunes, cada servidor debe tener una clave privada.

Las claves privadas se pueden generar de varias maneras. El siguiente ejemplo ilustra el uso de la interfaz de línea de comandos OpenSSL para generar una clave privada RSA de 2048 bits:

openssl genrsa -out ryans-key.pem 2048

Con TLS/SSL, todos los servidores (y algunos clientes) deben tener un certificado. Los certificados son claves públicas que corresponden a una clave privada y que están firmadas digitalmente por una Autoridad de Certificación o por el propietario de la clave privada (dichos certificados se denominan "autofirmados"). El primer paso para obtener un certificado es crear un archivo de Solicitud de Firma de Certificado (CSR).

La interfaz de línea de comandos OpenSSL se puede utilizar para generar un CSR para una clave privada:

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

Una vez que se genera el archivo CSR, se puede enviar a una Autoridad de Certificación para que lo firme o se puede utilizar para generar un certificado autofirmado.

La creación de un certificado autofirmado utilizando la interfaz de línea de comandos OpenSSL se ilustra en el siguiente ejemplo:

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

Una vez que se genera el certificado, se puede utilizar para generar un archivo .pfx o .p12:

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

Donde:

• in: es el certificado firmado
• inkey: es la clave privada asociada
• certfile: es una concatenación de todos los certificados de la Autoridad de Certificación (CA) en un solo archivo, por ejemplo, cat ca1-cert.pem ca2-cert.pem \> ca-cert.pem

Confidencialidad directa perfecta

El término confidencialidad directa o confidencialidad directa perfecta describe una característica de los métodos de acuerdo de claves (es decir, intercambio de claves). Es decir, las claves del servidor y del cliente se utilizan para negociar nuevas claves temporales que se utilizan específica y únicamente para la sesión de comunicación actual. En la práctica, esto significa que incluso si la clave privada del servidor se ve comprometida, la comunicación solo puede ser descifrada por los espías si el atacante logra obtener el par de claves generado específicamente para la sesión.

La confidencialidad directa perfecta se logra generando aleatoriamente un par de claves para el acuerdo de claves en cada protocolo de enlace TLS/SSL (en contraste con el uso de la misma clave para todas las sesiones). Los métodos que implementan esta técnica se denominan "efímeros".

Actualmente, se utilizan comúnmente dos métodos para lograr la confidencialidad directa perfecta (observe el carácter "E" agregado a las abreviaturas tradicionales):

• ECDHE: Una versión efímera del protocolo de acuerdo de claves Diffie-Hellman de curva elíptica.
• DHE: Una versión efímera del protocolo de acuerdo de claves Diffie-Hellman.

La confidencialidad directa perfecta mediante ECDHE está habilitada de forma predeterminada. La opción ecdhCurve se puede usar al crear un servidor TLS para personalizar la lista de curvas ECDH admitidas para usar. Consulte tls.createServer() para obtener más información.

DHE está deshabilitado de forma predeterminada, pero se puede habilitar junto con ECDHE estableciendo la opción dhparam en 'auto'. También se admiten parámetros DHE personalizados, pero se desaconsejan en favor de parámetros conocidos y seleccionados automáticamente.

La confidencialidad directa perfecta era opcional hasta TLSv1.2. A partir de TLSv1.3, siempre se usa (EC)DHE (con la excepción de las conexiones solo PSK).

ALPN y SNI

ALPN (Extensión de Negociación de Protocolo de Capa de Aplicación) y SNI (Indicación de Nombre de Servidor) son extensiones del protocolo de enlace TLS:

• ALPN: Permite el uso de un servidor TLS para múltiples protocolos (HTTP, HTTP/2)
• SNI: Permite el uso de un servidor TLS para múltiples nombres de host con diferentes certificados.

Claves precompartidas

El soporte de TLS-PSK está disponible como una alternativa a la autenticación normal basada en certificados. Utiliza una clave precompartida en lugar de certificados para autenticar una conexión TLS, proporcionando autenticación mutua. TLS-PSK y la infraestructura de clave pública no son mutuamente excluyentes. Los clientes y servidores pueden admitir ambos, eligiendo cualquiera de ellos durante el paso normal de negociación de cifrado.

TLS-PSK es una buena opción solo cuando existen medios para compartir de forma segura una clave con cada máquina que se conecta, por lo que no reemplaza la infraestructura de clave pública (PKI) para la mayoría de los usos de TLS. La implementación de TLS-PSK en OpenSSL ha experimentado muchas fallas de seguridad en los últimos años, principalmente porque solo la utiliza una minoría de aplicaciones. Considere todas las soluciones alternativas antes de cambiar a los cifrados PSK. Al generar PSK, es de importancia crítica usar suficiente entropía como se discute en RFC 4086. Derivar un secreto compartido de una contraseña u otras fuentes de baja entropía no es seguro.

Los cifrados PSK están deshabilitados por defecto, y por lo tanto, usar TLS-PSK requiere especificar explícitamente un conjunto de cifrado con la opción ciphers. La lista de cifrados disponibles se puede recuperar a través de openssl ciphers -v 'PSK'. Todos los cifrados TLS 1.3 son elegibles para PSK y se pueden recuperar a través de openssl ciphers -v -s -tls1_3 -psk. En la conexión del cliente, se debe pasar un checkServerIdentity personalizado porque el predeterminado fallará en ausencia de un certificado.

Según el RFC 4279, se deben admitir identidades PSK de hasta 128 bytes de longitud y PSK de hasta 64 bytes de longitud. A partir de OpenSSL 1.1.0, el tamaño máximo de identidad es de 128 bytes y la longitud máxima de PSK es de 256 bytes.

La implementación actual no admite devoluciones de llamada asincrónicas de PSK debido a las limitaciones de la API OpenSSL subyacente.

Para usar TLS-PSK, el cliente y el servidor deben especificar la opción pskCallback, una función que devuelve el PSK a usar (que debe ser compatible con el resumen del cifrado seleccionado).

Se llamará primero en el cliente:

• hint: <string> mensaje opcional enviado desde el servidor para ayudar al cliente a decidir qué identidad usar durante la negociación. Siempre null si se usa TLS 1.3.
• Devuelve: <Object> en la forma { psk: \<Buffer|TypedArray|DataView\>, identity: \<string\> } o null.

Luego en el servidor:

• socket: <tls.TLSSocket> la instancia del socket del servidor, equivalente a this.
• identity: <string> parámetro de identidad enviado desde el cliente.
• Devuelve: <Buffer> | <TypedArray> | <DataView> el PSK (o null).

Un valor de retorno de null detiene el proceso de negociación y envía un mensaje de alerta unknown_psk_identity a la otra parte. Si el servidor desea ocultar el hecho de que la identidad PSK no era conocida, la devolución de llamada debe proporcionar algunos datos aleatorios como psk para hacer que la conexión falle con decrypt_error antes de que termine la negociación.

Mitigación de ataques de renegociación iniciados por el cliente

El protocolo TLS permite a los clientes renegociar ciertos aspectos de la sesión TLS. Desafortunadamente, la renegociación de la sesión requiere una cantidad desproporcionada de recursos del lado del servidor, lo que la convierte en un vector potencial para ataques de denegación de servicio.

Para mitigar el riesgo, la renegociación se limita a tres veces cada diez minutos. Se emite un evento 'error' en la instancia tls.TLSSocket cuando se excede este umbral. Los límites son configurables:

• tls.CLIENT_RENEG_LIMIT <número> Especifica el número de solicitudes de renegociación. Predeterminado: 3.
• tls.CLIENT_RENEG_WINDOW <número> Especifica el tiempo de la ventana de renegociación en segundos. Predeterminado: 600 (10 minutos).

Los límites de renegociación predeterminados no deben modificarse sin una comprensión completa de las implicaciones y los riesgos.

TLSv1.3 no admite la renegociación.

Reanudación de sesión

Establecer una sesión TLS puede ser relativamente lento. El proceso puede acelerarse guardando y reutilizando posteriormente el estado de la sesión. Existen varios mecanismos para hacerlo, que se analizan aquí desde el más antiguo al más nuevo (y preferido).

Identificadores de sesión

Los servidores generan un ID único para las nuevas conexiones y lo envían al cliente. Los clientes y los servidores guardan el estado de la sesión. Al volver a conectarse, los clientes envían el ID del estado de la sesión guardada y, si el servidor también tiene el estado para ese ID, puede aceptar utilizarlo. De lo contrario, el servidor creará una nueva sesión. Consulte RFC 2246 para obtener más información, páginas 23 y 30.

La reanudación mediante identificadores de sesión es compatible con la mayoría de los navegadores web al realizar peticiones HTTPS.

En Node.js, los clientes esperan el evento 'session' para obtener los datos de la sesión, y proporcionan los datos a la opción session de un posterior tls.connect() para reutilizar la sesión. Los servidores deben implementar manejadores para los eventos 'newSession' y 'resumeSession' para guardar y restaurar los datos de la sesión utilizando el ID de la sesión como clave de búsqueda para reutilizar las sesiones. Para reutilizar las sesiones a través de equilibradores de carga o trabajadores de clúster, los servidores deben utilizar una caché de sesiones compartida (como Redis) en sus manejadores de sesiones.

Tickets de sesión

Los servidores cifran todo el estado de la sesión y lo envían al cliente como un "ticket". Al reconectar, el estado se envía al servidor en la conexión inicial. Este mecanismo evita la necesidad de una caché de sesión en el lado del servidor. Si el servidor no usa el ticket, por alguna razón (falla al descifrarlo, es demasiado viejo, etc.), creará una nueva sesión y enviará un nuevo ticket. Consulte RFC 5077 para obtener más información.

La reanudación mediante tickets de sesión está siendo compatible comúnmente por muchos navegadores web al realizar solicitudes HTTPS.

Para Node.js, los clientes usan las mismas API para la reanudación con identificadores de sesión que para la reanudación con tickets de sesión. Para la depuración, si tls.TLSSocket.getTLSTicket() devuelve un valor, los datos de la sesión contienen un ticket, de lo contrario, contienen el estado de la sesión del lado del cliente.

Con TLSv1.3, tenga en cuenta que el servidor puede enviar varios tickets, lo que resulta en múltiples eventos 'session', consulte 'session' para obtener más información.

Los servidores de un solo proceso no necesitan ninguna implementación específica para usar tickets de sesión. Para usar tickets de sesión en reinicios de servidores o balanceadores de carga, todos los servidores deben tener las mismas claves de ticket. Internamente, hay tres claves de 16 bytes, pero la API tls las expone como un único búfer de 48 bytes para mayor comodidad.

Es posible obtener las claves del ticket llamando a server.getTicketKeys() en una instancia del servidor y luego distribuirlas, pero es más razonable generar de forma segura 48 bytes de datos aleatorios seguros y establecerlos con la opción ticketKeys de tls.createServer(). Las claves deben regenerarse regularmente y las claves del servidor se pueden restablecer con server.setTicketKeys().

Las claves de los tickets de sesión son claves criptográficas y deben almacenarse de forma segura. Con TLS 1.2 e inferior, si se ven comprometidas, todas las sesiones que usaron tickets encriptados con ellas pueden ser descifradas. No deben almacenarse en el disco y deben regenerarse regularmente.

Si los clientes anuncian soporte para tickets, el servidor los enviará. El servidor puede deshabilitar los tickets suministrando require('node:constants').SSL_OP_NO_TICKET en secureOptions.

Tanto los identificadores de sesión como los tickets de sesión agotan el tiempo de espera, lo que hace que el servidor cree nuevas sesiones. El tiempo de espera se puede configurar con la opción sessionTimeout de tls.createServer().

Para todos los mecanismos, cuando falla la reanudación, los servidores crearán nuevas sesiones. Dado que el hecho de no poder reanudar la sesión no causa fallas en la conexión TLS/HTTPS, es fácil no notar un rendimiento TLS innecesariamente deficiente. La CLI de OpenSSL se puede usar para verificar que los servidores estén reanudando las sesiones. Use la opción -reconnect para openssl s_client, por ejemplo:

openssl s_client -connect localhost:443 -reconnect

Lea la salida de depuración. La primera conexión debería decir "New", por ejemplo:

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

Las conexiones posteriores deberían decir "Reused", por ejemplo:

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

Modificación del conjunto de cifrado TLS predeterminado

Node.js está construido con un conjunto predeterminado de cifrados TLS habilitados y deshabilitados. Esta lista de cifrados predeterminada se puede configurar al compilar Node.js para permitir que las distribuciones proporcionen su propia lista predeterminada.

Se puede usar el siguiente comando para mostrar el conjunto de cifrado predeterminado:

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 valor predeterminado se puede reemplazar por completo usando el modificador de línea de comandos --tls-cipher-list (directamente o a través de la variable de entorno NODE_OPTIONS). Por ejemplo, lo siguiente hace que ECDHE-RSA-AES128-GCM-SHA256:!RC4 sea el conjunto de cifrado TLS predeterminado:

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 verificarlo, use el siguiente comando para mostrar la lista de cifrado establecida, tenga en cuenta la diferencia entre defaultCoreCipherList y defaultCipherList:

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

es decir, la lista defaultCoreCipherList se establece en el momento de la compilación y la defaultCipherList se establece en tiempo de ejecución.

Para modificar los conjuntos de cifrado predeterminados desde el tiempo de ejecución, modifique la variable tls.DEFAULT_CIPHERS, esto debe realizarse antes de escuchar en cualquier socket, no afectará a los sockets ya abiertos. Por ejemplo:

// Eliminar cifrados CBC obsoletos y cifrados basados en intercambio de claves RSA, ya que no proporcionan secreto perfecto hacia adelante
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'

El valor predeterminado también se puede reemplazar por cliente o servidor utilizando la opción ciphers de tls.createSecureContext(), que también está disponible en tls.createServer(), tls.connect(), y al crear nuevos tls.TLSSockets.

La lista de cifrados puede contener una mezcla de nombres de conjuntos de cifrado TLSv1.3, los que comienzan con 'TLS_', y especificaciones para conjuntos de cifrado TLSv1.2 e inferiores. Los cifrados TLSv1.2 admiten un formato de especificación heredado, consulte la documentación de OpenSSL formato de lista de cifrado para obtener detalles, pero esas especificaciones no se aplican a los cifrados TLSv1.3. Los conjuntos TLSv1.3 solo se pueden habilitar incluyendo su nombre completo en la lista de cifrado. No se pueden, por ejemplo, habilitar o deshabilitar mediante el uso de la especificación heredada TLSv1.2 'EECDH' o '!EECDH'.

A pesar del orden relativo de los conjuntos de cifrado TLSv1.3 y TLSv1.2, el protocolo TLSv1.3 es significativamente más seguro que TLSv1.2, y siempre se elegirá sobre TLSv1.2 si el handshake indica que es compatible, y si algún conjunto de cifrado TLSv1.3 está habilitado.

El conjunto de cifrado predeterminado incluido en Node.js se ha seleccionado cuidadosamente para reflejar las mejores prácticas de seguridad actuales y la mitigación de riesgos. Cambiar el conjunto de cifrado predeterminado puede tener un impacto significativo en la seguridad de una aplicación. El modificador --tls-cipher-list y la opción ciphers solo deben usarse si es absolutamente necesario.

El conjunto de cifrado predeterminado prefiere los cifrados GCM para la configuración de criptografía moderna de Chrome y también prefiere los cifrados ECDHE y DHE para el secreto perfecto hacia adelante, al tiempo que ofrece alguna compatibilidad con versiones anteriores.

Los clientes antiguos que se basan en cifrados inseguros y obsoletos basados en RC4 o DES (como Internet Explorer 6) no pueden completar el proceso de handshake con la configuración predeterminada. Si estos clientes deben ser compatibles, las recomendaciones de TLS pueden ofrecer un conjunto de cifrado compatible. Para obtener más detalles sobre el formato, consulte la documentación de OpenSSL formato de lista de cifrado.

Solo hay cinco conjuntos de cifrado 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'

Los tres primeros están habilitados de forma predeterminada. Los dos conjuntos basados en CCM son compatibles con TLSv1.3 porque pueden tener un mejor rendimiento en sistemas limitados, pero no están habilitados de forma predeterminada ya que ofrecen menos seguridad.

Nivel de seguridad de OpenSSL

La biblioteca OpenSSL aplica niveles de seguridad para controlar el nivel mínimo aceptable de seguridad para las operaciones criptográficas. Los niveles de seguridad de OpenSSL varían de 0 a 5, y cada nivel impone requisitos de seguridad más estrictos. El nivel de seguridad predeterminado es 1, que generalmente es adecuado para la mayoría de las aplicaciones modernas. Sin embargo, algunas características y protocolos heredados, como TLSv1, requieren un nivel de seguridad más bajo (SECLEVEL=0) para funcionar correctamente. Para obtener información más detallada, consulte la documentación de OpenSSL sobre los niveles de seguridad.

Configuración de niveles de seguridad

Para ajustar el nivel de seguridad en su aplicación Node.js, puede incluir @SECLEVEL=X dentro de una cadena de cifrado, donde X es el nivel de seguridad deseado. Por ejemplo, para establecer el nivel de seguridad en 0 mientras usa la lista de cifrado predeterminada de OpenSSL, podría usar:

ESM

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

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Cliente conectado con el 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 con el protocolo:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

Este enfoque establece el nivel de seguridad en 0, lo que permite el uso de funciones heredadas mientras se siguen aprovechando los cifrados predeterminados de OpenSSL.

Usando

También puede establecer el nivel de seguridad y los cifrados desde la línea de comandos utilizando --tls-cipher-list=DEFAULT@SECLEVEL=X como se describe en Modificación del conjunto de cifrado TLS predeterminado. Sin embargo, generalmente se desaconseja utilizar la opción de la línea de comandos para establecer los cifrados y es preferible configurar los cifrados para contextos individuales dentro del código de su aplicación, ya que este enfoque proporciona un control más preciso y reduce el riesgo de degradar globalmente el nivel de seguridad.

Códigos de error de certificado X509

Varias funciones pueden fallar debido a errores de certificado que son reportados por OpenSSL. En tal caso, la función proporciona un <Error> a través de su callback que tiene la propiedad code que puede tomar uno de los siguientes valores:

• 'UNABLE_TO_GET_ISSUER_CERT': No se puede obtener el certificado emisor.
• 'UNABLE_TO_GET_CRL': No se puede obtener la CRL del certificado.
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': No se puede descifrar la firma del certificado.
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': No se puede descifrar la firma de la CRL.
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': No se puede decodificar la clave pública del emisor.
• 'CERT_SIGNATURE_FAILURE': Fallo en la firma del certificado.
• 'CRL_SIGNATURE_FAILURE': Fallo en la firma de la CRL.
• 'CERT_NOT_YET_VALID': El certificado aún no es válido.
• 'CERT_HAS_EXPIRED': El certificado ha expirado.
• 'CRL_NOT_YET_VALID': La CRL aún no es válida.
• 'CRL_HAS_EXPIRED': La CRL ha expirado.
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD': Error de formato en el campo notBefore del certificado.
• 'ERROR_IN_CERT_NOT_AFTER_FIELD': Error de formato en el campo notAfter del certificado.
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD': Error de formato en el campo lastUpdate de la CRL.
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': Error de formato en el campo nextUpdate de la CRL.
• 'OUT_OF_MEM': Sin memoria.
• 'DEPTH_ZERO_SELF_SIGNED_CERT': Certificado autofirmado.
• 'SELF_SIGNED_CERT_IN_CHAIN': Certificado autofirmado en la cadena de certificados.
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': No se puede obtener el certificado emisor local.
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': No se puede verificar el primer certificado.
• 'CERT_CHAIN_TOO_LONG': Cadena de certificados demasiado larga.
• 'CERT_REVOKED': Certificado revocado.
• 'INVALID_CA': Certificado CA no válido.
• 'PATH_LENGTH_EXCEEDED': Se ha superado la restricción de longitud de la ruta.
• 'INVALID_PURPOSE': Propósito de certificado no admitido.
• 'CERT_UNTRUSTED': Certificado no confiable.
• 'CERT_REJECTED': Certificado rechazado.
• 'HOSTNAME_MISMATCH': Desajuste de nombre de host.

Clase: tls.CryptoStream

Añadido en: v0.3.4

Obsoleto desde: v0.11.3

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Utilice tls.TLSSocket en su lugar.

La clase tls.CryptoStream representa un flujo de datos cifrados. Esta clase está obsoleta y ya no debe utilizarse.

cryptoStream.bytesWritten

Añadido en: v0.3.4

Obsoleto desde: v0.11.3

La propiedad cryptoStream.bytesWritten devuelve el número total de bytes escritos en el socket subyacente incluidos los bytes necesarios para la implementación del protocolo TLS.

Clase: tls.SecurePair

Añadido en: v0.3.2

Obsoleto desde: v0.11.3

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Utilice tls.TLSSocket en su lugar.

Devuelto por tls.createSecurePair().

Evento: 'secure'

Agregado en: v0.3.2

Obsoleto desde: v0.11.3

El evento 'secure' es emitido por el objeto SecurePair una vez que se ha establecido una conexión segura.

Al igual que al verificar el evento 'secureConnection' del servidor, se debe inspeccionar pair.cleartext.authorized para confirmar si el certificado utilizado está correctamente autorizado.

Clase: tls.Server

Agregado en: v0.3.2

• Extiende: <net.Server>

Acepta conexiones cifradas utilizando TLS o SSL.

Evento: 'connection'

Agregado en: v0.3.2

• socket <stream.Duplex>

Este evento se emite cuando se establece un nuevo flujo TCP, antes de que comience el handshake TLS. socket es típicamente un objeto de tipo net.Socket pero no recibirá eventos a diferencia del socket creado a partir del evento 'connection' de net.Server. Generalmente, los usuarios no querrán acceder a este evento.

Este evento también puede ser emitido explícitamente por los usuarios para inyectar conexiones en el servidor TLS. En ese caso, se puede pasar cualquier flujo Duplex.

Evento: 'keylog'

Agregado en: v12.3.0, v10.20.0

• line <Buffer> Línea de texto ASCII, en formato NSS SSLKEYLOGFILE.
• tlsSocket <tls.TLSSocket> La instancia tls.TLSSocket en la que se generó.

El evento keylog se emite cuando se genera o recibe material clave por una conexión a este servidor (normalmente antes de que se haya completado el handshake, pero no necesariamente). Este material clave se puede almacenar para la depuración, ya que permite descifrar el tráfico TLS capturado. Se puede emitir varias veces para cada socket.

Un caso de uso típico es agregar las líneas recibidas a un archivo de texto común, que luego es utilizado por software (como Wireshark) para descifrar el tráfico:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...') return // Solo registrar claves para una IP en particular
  logFile.write(line)
})

Evento: 'newSession'

[Historial]

Versión	Cambios
v0.11.12	Ahora se admite el argumento callback.
v0.9.2	Agregado en: v0.9.2

El evento 'newSession' se emite al crear una nueva sesión TLS. Esto se puede usar para almacenar sesiones en almacenamiento externo. Los datos se deben proporcionar a la devolución de llamada 'resumeSession'.

La devolución de llamada del listener recibe tres argumentos cuando se llama:

• sessionId <Buffer> El identificador de la sesión TLS
• sessionData <Buffer> Los datos de la sesión TLS
• callback <Function> Una función de devolución de llamada que no toma argumentos y que se debe invocar para que los datos se envíen o reciban a través de la conexión segura.

Escuchar este evento solo tendrá efecto en las conexiones establecidas después de agregar el listener del evento.

Evento: 'OCSPRequest'

Agregado en: v0.11.13

El evento 'OCSPRequest' se emite cuando el cliente envía una solicitud de estado de certificado. La devolución de llamada del listener recibe tres argumentos cuando se llama:

• certificate <Buffer> El certificado del servidor
• issuer <Buffer> El certificado del emisor
• callback <Function> Una función de devolución de llamada que se debe invocar para proporcionar los resultados de la solicitud OCSP.

El certificado actual del servidor se puede analizar para obtener la URL de OCSP y el ID del certificado; después de obtener una respuesta de OCSP, se invoca callback(null, resp), donde resp es una instancia de Buffer que contiene la respuesta de OCSP. Tanto certificate como issuer son representaciones DER de Buffer de los certificados primario y del emisor. Estos se pueden usar para obtener el ID del certificado OCSP y la URL del endpoint de OCSP.

Alternativamente, se puede llamar a callback(null, null), lo que indica que no hubo respuesta de OCSP.

Llamar a callback(err) resultará en una llamada socket.destroy(err).

El flujo típico de una solicitud OCSP es el siguiente:

El issuer puede ser null si el certificado es autofirmado o el emisor no está en la lista de certificados raíz. (Se puede proporcionar un emisor a través de la opción ca al establecer la conexión TLS).

Escuchar este evento solo tendrá efecto en las conexiones establecidas después de agregar el listener del evento.

Se puede usar un módulo npm como asn1.js para analizar los certificados.

Evento: 'resumeSession'

Agregado en: v0.9.2

El evento 'resumeSession' se emite cuando el cliente solicita reanudar una sesión TLS anterior. La función de devolución de llamada del oyente recibe dos argumentos cuando se llama:

• sessionId <Buffer> El identificador de la sesión TLS
• callback <Function> Una función de devolución de llamada que se debe llamar cuando se haya recuperado la sesión anterior: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

El oyente de eventos debe realizar una búsqueda en un almacenamiento externo de la sessionData guardada por el controlador de eventos 'newSession' utilizando el sessionId dado. Si se encuentra, llama a callback(null, sessionData) para reanudar la sesión. Si no se encuentra, la sesión no se puede reanudar. Se debe llamar a callback() sin sessionData para que el protocolo de enlace pueda continuar y se pueda crear una nueva sesión. Es posible llamar a callback(err) para terminar la conexión entrante y destruir el socket.

Escuchar este evento tendrá efecto solo en las conexiones establecidas después de la adición del oyente de eventos.

Lo siguiente ilustra cómo reanudar una sesión 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'

Agregado en: v0.3.2

El evento 'secureConnection' se emite después de que el proceso de handshake para una nueva conexión se haya completado exitosamente. La función de callback del listener recibe un único argumento cuando es llamada:

• tlsSocket <tls.TLSSocket> El socket TLS establecido.

La propiedad tlsSocket.authorized es un boolean que indica si el cliente ha sido verificado por una de las Autoridades de Certificación suministradas para el servidor. Si tlsSocket.authorized es false, entonces socket.authorizationError se establece para describir cómo falló la autorización. Dependiendo de la configuración del servidor TLS, las conexiones no autorizadas aún pueden ser aceptadas.

La propiedad tlsSocket.alpnProtocol es una cadena que contiene el protocolo ALPN seleccionado. Cuando ALPN no tiene un protocolo seleccionado porque el cliente o el servidor no enviaron una extensión ALPN, tlsSocket.alpnProtocol es igual a false.

La propiedad tlsSocket.servername es una cadena que contiene el nombre del servidor solicitado a través de SNI.

Evento: 'tlsClientError'

Agregado en: v6.0.0

El evento 'tlsClientError' se emite cuando ocurre un error antes de que se establezca una conexión segura. La función de callback del listener recibe dos argumentos cuando es llamada:

• exception <Error> El objeto Error que describe el error
• tlsSocket <tls.TLSSocket> La instancia tls.TLSSocket de la cual se originó el error.

server.addContext(hostname, context)

Agregado en: v0.5.3

• hostname <string> Un nombre de host SNI o comodín (p. ej. '*')
• context <Object> | <tls.SecureContext> Un objeto que contiene cualquiera de las posibles propiedades de los argumentos options de tls.createSecureContext() (p. ej. key, cert, ca, etc.), o un objeto de contexto TLS creado con tls.createSecureContext() en sí mismo.

El método server.addContext() agrega un contexto seguro que se utilizará si el nombre SNI de la solicitud del cliente coincide con el hostname (o comodín) proporcionado.

Cuando hay múltiples contextos coincidentes, se utiliza el agregado más recientemente.

server.address()

Añadido en: v0.6.0

• Devuelve: <Object>

Devuelve la dirección vinculada, el nombre de la familia de direcciones y el puerto del servidor según lo informa el sistema operativo. Consulte net.Server.address() para obtener más información.

server.close([callback])

Añadido en: v0.3.2

• callback <Function> Una función de retrollamada de escucha que se registrará para escuchar el evento 'close' de la instancia del servidor.
• Devuelve: <tls.Server>

El método server.close() impide que el servidor acepte nuevas conexiones.

Esta función opera de forma asíncrona. El evento 'close' se emitirá cuando el servidor no tenga más conexiones abiertas.

server.getTicketKeys()

Añadido en: v3.0.0

• Devuelve: <Buffer> Un búfer de 48 bytes que contiene las claves de la sesión de ticket.

Devuelve las claves de la sesión de ticket.

Consulte Reanudación de sesión para obtener más información.

server.listen()

Comienza a escuchar el servidor las conexiones cifradas. Este método es idéntico a server.listen() de net.Server.

server.setSecureContext(options)

Agregado en: v11.0.0

• options <Object> Un objeto que contiene cualquiera de las propiedades posibles de los argumentos options de tls.createSecureContext() (p. ej., key, cert, ca, etc.).

El método server.setSecureContext() reemplaza el contexto seguro de un servidor existente. Las conexiones existentes al servidor no se interrumpen.

server.setTicketKeys(keys)

Agregado en: v3.0.0

• keys <Buffer> | <TypedArray> | <DataView> Un búfer de 48 bytes que contiene las claves del ticket de sesión.

Establece las claves del ticket de sesión.

Los cambios en las claves del ticket solo son efectivos para futuras conexiones al servidor. Las conexiones al servidor existentes o actualmente pendientes utilizarán las claves anteriores.

Consulte Reanudación de sesión para obtener más información.

Clase: tls.TLSSocket

Agregado en: v0.11.4

• Extiende: <net.Socket>

Realiza un cifrado transparente de los datos escritos y toda la negociación TLS requerida.

Las instancias de tls.TLSSocket implementan la interfaz Stream dúplex.

Los métodos que devuelven metadatos de la conexión TLS (por ejemplo, tls.TLSSocket.getPeerCertificate()) solo devolverán datos mientras la conexión esté abierta.

new tls.TLSSocket(socket[, options])

[Historial]

Versión	Cambios
v12.2.0	Ahora se admite la opción enableTrace.
v5.0.0	Ahora se admiten las opciones ALPN.
v0.11.4	Agregado en: v0.11.4

• socket <net.Socket> | <stream.Duplex> En el lado del servidor, cualquier flujo Duplex. En el lado del cliente, cualquier instancia de net.Socket (para soporte genérico de flujo Duplex en el lado del cliente, se debe usar tls.connect()).
• options <Object>
  • enableTrace: Consulte tls.createServer()
  • isServer: El protocolo SSL/TLS es asimétrico, los TLSSockets deben saber si deben comportarse como un servidor o un cliente. Si es true, el socket TLS se instanciará como un servidor. Predeterminado: false.
  • server <net.Server> Una instancia de net.Server.
  • requestCert: Indica si se debe autenticar el par remoto solicitando un certificado. Los clientes siempre solicitan un certificado de servidor. Los servidores (isServer es true) pueden establecer requestCert en true para solicitar un certificado de cliente.
  • rejectUnauthorized: Consulte tls.createServer()
  • ALPNProtocols: Consulte tls.createServer()
  • SNICallback: Consulte tls.createServer()
  • session <Buffer> Una instancia de Buffer que contiene una sesión TLS.
  • requestOCSP <boolean> Si es true, especifica que la extensión de solicitud de estado OCSP se agregará al saludo del cliente y se emitirá un evento 'OCSPResponse' en el socket antes de establecer una comunicación segura
  • secureContext: Objeto de contexto TLS creado con tls.createSecureContext(). Si no se proporciona un secureContext, se creará uno pasando todo el objeto options a tls.createSecureContext().
  • ...: Opciones de tls.createSecureContext() que se utilizan si falta la opción secureContext. De lo contrario, se ignoran.

Construye un nuevo objeto tls.TLSSocket a partir de un socket TCP existente.

Event: 'keylog'

Agregado en: v12.3.0, v10.20.0

• line <Buffer> Línea de texto ASCII, en formato NSS SSLKEYLOGFILE.

El evento keylog se emite en un tls.TLSSocket cuando el material de clave es generado o recibido por el socket. Este material de clave se puede almacenar para depuración, ya que permite descifrar el tráfico TLS capturado. Puede emitirse varias veces, antes o después de que se complete el protocolo de enlace.

Un caso de uso típico es agregar las líneas recibidas a un archivo de texto común, que luego es utilizado por software (como Wireshark) para descifrar el tráfico:

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

Event: 'OCSPResponse'

Agregado en: v0.11.13

El evento 'OCSPResponse' se emite si la opción requestOCSP se estableció cuando se creó el tls.TLSSocket y se ha recibido una respuesta OCSP. La función de callback del listener recibe un solo argumento cuando se llama:

• response <Buffer> La respuesta OCSP del servidor

Por lo general, la response es un objeto firmado digitalmente de la CA del servidor que contiene información sobre el estado de revocación del certificado del servidor.

Evento: 'secureConnect'

Agregado en: v0.11.4

El evento 'secureConnect' se emite después de que el proceso de negociación para una nueva conexión se haya completado correctamente. La función de devolución de llamada del oyente se llamará independientemente de si el certificado del servidor ha sido autorizado o no. Es responsabilidad del cliente verificar la propiedad tlsSocket.authorized para determinar si el certificado del servidor fue firmado por una de las CA especificadas. Si tlsSocket.authorized === false, entonces el error se puede encontrar examinando la propiedad tlsSocket.authorizationError. Si se utilizó ALPN, se puede verificar la propiedad tlsSocket.alpnProtocol para determinar el protocolo negociado.

El evento 'secureConnect' no se emite cuando se crea un <tls.TLSSocket> utilizando el constructor new tls.TLSSocket().

Evento: 'session'

Agregado en: v11.10.0

• session <Buffer>

El evento 'session' se emite en un tls.TLSSocket del cliente cuando hay una nueva sesión o ticket TLS disponible. Esto puede ocurrir o no antes de que se complete la negociación, dependiendo de la versión del protocolo TLS que se haya negociado. El evento no se emite en el servidor, o si no se creó una nueva sesión, por ejemplo, cuando se reanudó la conexión. Para algunas versiones del protocolo TLS, el evento puede emitirse varias veces, en cuyo caso todas las sesiones se pueden usar para la reanudación.

En el cliente, la session se puede proporcionar a la opción session de tls.connect() para reanudar la conexión.

Consulte Reanudación de Sesión para obtener más información.

Para TLSv1.2 e inferior, se puede llamar a tls.TLSSocket.getSession() una vez que se complete la negociación. Para TLSv1.3, el protocolo solo permite la reanudación basada en tickets, se envían varios tickets y los tickets no se envían hasta después de que se completa la negociación. Por lo tanto, es necesario esperar el evento 'session' para obtener una sesión reanudable. Las aplicaciones deben usar el evento 'session' en lugar de getSession() para asegurarse de que funcionarán para todas las versiones de TLS. Las aplicaciones que solo esperan obtener o usar una sesión deben escuchar este evento solo una vez:

tlsSocket.once('session', session => {
  // La sesión se puede usar inmediatamente o más tarde.
  tls.connect({
    session: session,
    // Otras opciones de conexión...
  })
})

tlsSocket.address()

[Historial]

Versión	Cambios
v18.4.0	La propiedad family ahora devuelve una cadena en lugar de un número.
v18.0.0	La propiedad family ahora devuelve un número en lugar de una cadena.
v0.11.4	Añadido en: v0.11.4

• Devuelve: <Objeto>

Devuelve la dirección enlazada, el nombre de la familia de la dirección y el puerto del socket subyacente según lo informado por el sistema operativo: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError

Añadido en: v0.11.4

Devuelve la razón por la que el certificado del par no fue verificado. Esta propiedad se establece solo cuando tlsSocket.authorized === false.

tlsSocket.authorized

Añadido en: v0.11.4

• <booleano>

Esta propiedad es true si el certificado del par fue firmado por una de las CA especificadas al crear la instancia tls.TLSSocket, de lo contrario, false.

tlsSocket.disableRenegotiation()

Agregado en: v8.4.0

Deshabilita la renegociación TLS para esta instancia de TLSSocket. Una vez llamada, los intentos de renegociación activarán un evento 'error' en el TLSSocket.

tlsSocket.enableTrace()

Agregado en: v12.2.0

Cuando está habilitado, la información de seguimiento de paquetes TLS se escribe en stderr. Esto se puede usar para depurar problemas de conexión TLS.

El formato de la salida es idéntico a la salida de openssl s_client -trace o openssl s_server -trace. Si bien es producido por la función SSL_trace() de OpenSSL, el formato no está documentado, puede cambiar sin previo aviso y no se debe confiar en él.

tlsSocket.encrypted

Agregado en: v0.11.4

Siempre devuelve true. Esto se puede utilizar para distinguir los sockets TLS de las instancias regulares de net.Socket.

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

Agregado en: v13.10.0, v12.17.0

• length <number> número de bytes a recuperar del material de claves
• label <string> una etiqueta específica de la aplicación, normalmente este será un valor del Registro de etiquetas de exportador de IANA.
• context <Buffer> Opcionalmente proporciona un contexto.
• Devuelve: <Buffer> bytes solicitados del material de claves

El material de claves se utiliza para validaciones para prevenir diferentes tipos de ataques en protocolos de red, por ejemplo en las especificaciones de IEEE 802.1X.

Ejemplo

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

/*
 Ejemplo 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 más bytes>
*/

Consulta la documentación de OpenSSL SSL_export_keying_material para obtener más información.

tlsSocket.getCertificate()

Añadido en: v11.2.0

• Devuelve: <Object>

Devuelve un objeto que representa el certificado local. El objeto devuelto tiene algunas propiedades correspondientes a los campos del certificado.

Consulta tls.TLSSocket.getPeerCertificate() para ver un ejemplo de la estructura del certificado.

Si no hay certificado local, se devolverá un objeto vacío. Si el socket ha sido destruido, se devolverá null.

tlsSocket.getCipher()

[Historial]

Versión	Cambios
v13.4.0, v12.16.0	Devuelve el nombre de cifrado IETF como standardName.
v12.0.0	Devuelve la versión mínima de cifrado, en lugar de una cadena fija ('TLSv1/SSLv3').
v0.11.4	Añadido en: v0.11.4

• Devuelve: <Object>
  • name <string> Nombre de OpenSSL para el conjunto de cifrado.
  • standardName <string> Nombre IETF para el conjunto de cifrado.
  • version <string> La versión mínima del protocolo TLS soportada por este conjunto de cifrado. Para el protocolo negociado real, consulta tls.TLSSocket.getProtocol().

Devuelve un objeto que contiene información sobre el conjunto de cifrado negociado.

Por ejemplo, un protocolo TLSv1.2 con cifrado AES256-SHA:

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

Consulta SSL_CIPHER_get_name para más información.

tlsSocket.getEphemeralKeyInfo()

Agregado en: v5.0.0

• Devuelve: <Objeto>

Devuelve un objeto que representa el tipo, el nombre y el tamaño del parámetro de un intercambio de claves efímeras en secreto perfecto hacia adelante en una conexión de cliente. Devuelve un objeto vacío cuando el intercambio de claves no es efímero. Dado que esto solo se admite en un socket de cliente; se devuelve null si se llama en un socket de servidor. Los tipos admitidos son 'DH' y 'ECDH'. La propiedad name solo está disponible cuando el tipo es 'ECDH'.

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

tlsSocket.getFinished()

Agregado en: v9.9.0

• Devuelve: <Buffer> | <undefined> El último mensaje Finished que se ha enviado al socket como parte de un handshake SSL/TLS, o undefined si aún no se ha enviado ningún mensaje Finished.

Como los mensajes Finished son resúmenes de mensajes del handshake completo (con un total de 192 bits para TLS 1.0 y más para SSL 3.0), se pueden usar para procedimientos de autenticación externos cuando la autenticación proporcionada por SSL/TLS no es deseada o no es suficiente.

Corresponde a la rutina SSL_get_finished en OpenSSL y puede usarse para implementar el enlace de canal tls-unique de RFC 5929.

tlsSocket.getPeerCertificate([detailed])

Agregado en: v0.11.4

• detailed <boolean> Incluye la cadena de certificados completa si es true, de lo contrario, incluye solo el certificado del par.
• Devuelve: <Object> Un objeto de certificado.

Devuelve un objeto que representa el certificado del par. Si el par no proporciona un certificado, se devolverá un objeto vacío. Si el socket ha sido destruido, se devolverá null.

Si se solicitó la cadena de certificados completa, cada certificado incluirá una propiedad issuerCertificate que contiene un objeto que representa el certificado de su emisor.

Objeto de certificado

[Historial]

Versión	Cambios
v19.1.0, v18.13.0	Agregada la propiedad "ca".
v17.2.0, v16.14.0	Agregado fingerprint512.
v11.4.0	Soporte para información de clave pública de curva elíptica.

Un objeto de certificado tiene propiedades que corresponden a los campos del certificado.

• ca <boolean> true si es una Autoridad de Certificación (CA), false de lo contrario.
• raw <Buffer> Los datos del certificado X.509 codificados en DER.
• subject <Object> El sujeto del certificado, descrito en términos de País (C), EstadoOProvincia (ST), Localidad (L), Organización (O), UnidadOrganizacional (OU) y NombreComún (CN). El NombreComún suele ser un nombre DNS con certificados TLS. Ejemplo: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> El emisor del certificado, descrito en los mismos términos que el subject.
• valid_from <string> La fecha y hora a partir de la cual el certificado es válido.
• valid_to <string> La fecha y hora hasta la cual el certificado es válido.
• serialNumber <string> El número de serie del certificado, como una cadena hexadecimal. Ejemplo: 'B9B0D332A1AA5635'.
• fingerprint <string> El resumen SHA-1 del certificado codificado en DER. Se devuelve como una cadena hexadecimal separada por :. Ejemplo: '2A:7A:C2:DD:...'.
• fingerprint256 <string> El resumen SHA-256 del certificado codificado en DER. Se devuelve como una cadena hexadecimal separada por :. Ejemplo: '2A:7A:C2:DD:...'.
• fingerprint512 <string> El resumen SHA-512 del certificado codificado en DER. Se devuelve como una cadena hexadecimal separada por :. Ejemplo: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (Opcional) El uso extendido de clave, un conjunto de OID.
• subjectaltname <string> (Opcional) Una cadena que contiene nombres concatenados para el sujeto, una alternativa a los nombres subject.
• infoAccess <Array> (Opcional) Un arreglo que describe AuthorityInfoAccess, usado con OCSP.
• issuerCertificate <Object> (Opcional) El objeto del certificado emisor. Para certificados autofirmados, esto puede ser una referencia circular.

El certificado puede contener información sobre la clave pública, dependiendo del tipo de clave.

Para claves RSA, se pueden definir las siguientes propiedades:

• bits <number> El tamaño de bit RSA. Ejemplo: 1024.
• exponent <string> El exponente RSA, como una cadena en notación de número hexadecimal. Ejemplo: '0x010001'.
• modulus <string> El módulo RSA, como una cadena hexadecimal. Ejemplo: 'B56CE45CB7...'.
• pubkey <Buffer> La clave pública.

Para claves EC, se pueden definir las siguientes propiedades:

• pubkey <Buffer> La clave pública.
• bits <number> El tamaño de la clave en bits. Ejemplo: 256.
• asn1Curve <string> (Opcional) El nombre ASN.1 del OID de la curva elíptica. Las curvas conocidas se identifican por un OID. Si bien es inusual, es posible que la curva se identifique por sus propiedades matemáticas, en cuyo caso no tendrá un OID. Ejemplo: 'prime256v1'.
• nistCurve <string> (Opcional) El nombre NIST para la curva elíptica, si tiene uno (no a todas las curvas conocidas se les han asignado nombres por NIST). Ejemplo: 'P-256'.

Ejemplo 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: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  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()

Agregado en: v9.9.0

• Devuelve: <Buffer> | <undefined> El último mensaje Finished que se espera o que realmente se ha recibido del socket como parte de un protocolo de enlace SSL/TLS, o undefined si no hay ningún mensaje Finished hasta el momento.

Como los mensajes Finished son resúmenes de mensajes del protocolo de enlace completo (con un total de 192 bits para TLS 1.0 y más para SSL 3.0), se pueden utilizar para procedimientos de autenticación externos cuando la autenticación proporcionada por SSL/TLS no es deseada o no es suficiente.

Corresponde a la rutina SSL_get_peer_finished en OpenSSL y puede utilizarse para implementar el enlace de canal tls-unique de RFC 5929.

tlsSocket.getPeerX509Certificate()

Agregado en: v15.9.0

• Devuelve: <X509Certificate>

Devuelve el certificado del par como un objeto <X509Certificate>.

Si no hay certificado del par, o si el socket ha sido destruido, se devolverá undefined.

tlsSocket.getProtocol()

Agregado en: v5.7.0

• Devuelve: <string> | <null>

Devuelve una cadena que contiene la versión del protocolo SSL/TLS negociada de la conexión actual. El valor 'unknown' se devolverá para los sockets conectados que no hayan completado el proceso de establecimiento de conexión. El valor null se devolverá para los sockets del servidor o los sockets del cliente desconectados.

Las versiones de protocolo son:

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

Consulta la documentación de OpenSSL SSL_get_version para obtener más información.

tlsSocket.getSession()

Agregado en: v0.11.4

• <Buffer>

Devuelve los datos de la sesión TLS o undefined si no se negoció ninguna sesión. En el cliente, los datos se pueden proporcionar a la opción session de tls.connect() para reanudar la conexión. En el servidor, puede ser útil para la depuración.

Consulta Reanudación de la sesión para obtener más información.

Nota: getSession() solo funciona para TLSv1.2 y versiones anteriores. Para TLSv1.3, las aplicaciones deben usar el evento 'session' (también funciona para TLSv1.2 y versiones anteriores).

tlsSocket.getSharedSigalgs()

Agregado en: v12.11.0

• Devuelve: <Array> Lista de algoritmos de firma compartidos entre el servidor y el cliente en orden de preferencia decreciente.

Consulte SSL_get_shared_sigalgs para obtener más información.

tlsSocket.getTLSTicket()

Agregado en: v0.11.4

• <Buffer>

Para un cliente, devuelve el ticket de sesión TLS si hay uno disponible, o undefined. Para un servidor, siempre devuelve undefined.

Puede ser útil para la depuración.

Consulte Reanudación de sesión para obtener más información.

tlsSocket.getX509Certificate()

Agregado en: v15.9.0

• Devuelve: <X509Certificate>

Devuelve el certificado local como un objeto <X509Certificate>.

Si no hay un certificado local, o el socket ha sido destruido, se devolverá undefined.

tlsSocket.isSessionReused()

Agregado en: v0.5.6

• Devuelve: <boolean> true si la sesión fue reutilizada, false de lo contrario.

Ver Reanudación de Sesión para más información.

tlsSocket.localAddress

Agregado en: v0.11.4

• <string>

Devuelve la representación en cadena de la dirección IP local.

tlsSocket.localPort

Agregado en: v0.11.4

• <integer>

Devuelve la representación numérica del puerto local.

tlsSocket.remoteAddress

Agregado en: v0.11.4

• <string>

Devuelve la representación en cadena de la dirección IP remota. Por ejemplo, '74.125.127.100' o '2001:4860:a005::68'.

tlsSocket.remoteFamily

Agregado en: v0.11.4

• <string>

Devuelve la representación en cadena de la familia IP remota. 'IPv4' o 'IPv6'.

tlsSocket.remotePort

Añadido en: v0.11.4

• <integer>

Devuelve la representación numérica del puerto remoto. Por ejemplo, 443.

tlsSocket.renegotiate(options, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v0.11.8	Añadido en: v0.11.8

• options <Object>

  • rejectUnauthorized <boolean> Si no es false, el certificado del servidor se verifica con la lista de CAs suministradas. Se emite un evento 'error' si la verificación falla; err.code contiene el código de error de OpenSSL. Por defecto: true.
  • requestCert

• callback <Function> Si renegotiate() devolvió true, el callback se adjunta una vez al evento 'secure'. Si renegotiate() devolvió false, callback será llamado en el siguiente tick con un error, a menos que el tlsSocket haya sido destruido, en cuyo caso callback no será llamado en absoluto.

• Devuelve: <boolean> true si la renegociación fue iniciada, false en caso contrario.

El método tlsSocket.renegotiate() inicia un proceso de renegociación TLS. Al finalizar, la función callback recibirá un único argumento que será un Error (si la solicitud falló) o null.

Este método puede utilizarse para solicitar el certificado de un par después de que se haya establecido la conexión segura.

Cuando se ejecuta como servidor, el socket se destruirá con un error después de un tiempo de espera de handshakeTimeout.

Para TLSv1.3, la renegociación no se puede iniciar, ya que no es compatible con el protocolo.

tlsSocket.setKeyCert(context)

Agregado en: v22.5.0, v20.17.0

• context <Objeto> | <tls.SecureContext> Un objeto que contiene al menos las propiedades key y cert de las options de tls.createSecureContext(), o un objeto de contexto TLS creado con tls.createSecureContext() en sí mismo.

El método tlsSocket.setKeyCert() establece la clave privada y el certificado para usar en el socket. Esto es principalmente útil si desea seleccionar un certificado de servidor de ALPNCallback de un servidor TLS.

tlsSocket.setMaxSendFragment(size)

Agregado en: v0.11.11

• size <número> El tamaño máximo del fragmento TLS. El valor máximo es 16384. Predeterminado: 16384.
• Devuelve: <booleano>

El método tlsSocket.setMaxSendFragment() establece el tamaño máximo del fragmento TLS. Devuelve true si la configuración del límite tuvo éxito; false en caso contrario.

Los tamaños de fragmento más pequeños disminuyen la latencia de almacenamiento en búfer en el cliente: los fragmentos más grandes se almacenan en búfer mediante la capa TLS hasta que se recibe todo el fragmento y se verifica su integridad; los fragmentos grandes pueden abarcar múltiples viajes de ida y vuelta y su procesamiento puede retrasarse debido a la pérdida o reordenamiento de paquetes. Sin embargo, los fragmentos más pequeños agregan bytes de trama TLS adicionales y una sobrecarga de CPU, lo que puede disminuir el rendimiento general del servidor.

tls.checkServerIdentity(hostname, cert)

[Historial]

Versión	Cambios
v17.3.1, v16.13.2, v14.18.3, v12.22.9	Se ha deshabilitado la compatibilidad con nombres alternativos de sujeto uniformResourceIdentifier en respuesta a CVE-2021-44531.
v0.8.4	Añadido en: v0.8.4

• hostname <string> El nombre de host o la dirección IP para verificar el certificado.
• cert <Object> Un objeto certificado que representa el certificado del par.
• Devuelve: <Error> | <undefined>

Verifica que el certificado cert se emita para hostname.

Devuelve un objeto <Error>, rellenándolo con reason, host y cert en caso de fallo. En caso de éxito, devuelve <undefined>.

Esta función está destinada a ser utilizada en combinación con la opción checkServerIdentity que se puede pasar a tls.connect() y, como tal, opera en un objeto certificado. Para otros propósitos, considera usar x509.checkHost() en su lugar.

Esta función puede ser sobreescrita proporcionando una función alternativa como la opción options.checkServerIdentity que se pasa a tls.connect(). La función de sobreescritura puede llamar a tls.checkServerIdentity() por supuesto, para aumentar las comprobaciones realizadas con verificación adicional.

Esta función solo se llama si el certificado pasó todas las demás comprobaciones, como haber sido emitido por una CA de confianza (options.ca).

Las versiones anteriores de Node.js aceptaban incorrectamente los certificados para un hostname dado si estaba presente un nombre alternativo de sujeto uniformResourceIdentifier coincidente (ver CVE-2021-44531). Las aplicaciones que deseen aceptar nombres alternativos de sujeto uniformResourceIdentifier pueden usar una función options.checkServerIdentity personalizada que implemente el comportamiento deseado.

tls.connect(options[, callback])

[Historial]

Versión	Cambios
v15.1.0, v14.18.0	Se añadió la opción onread.
v14.1.0, v13.14.0	Ahora se acepta la opción highWaterMark.
v13.6.0, v12.16.0	Ahora se admite la opción pskCallback.
v12.9.0	Soporte para la opción allowHalfOpen.
v12.4.0	Ahora se admite la opción hints.
v12.2.0	Ahora se admite la opción enableTrace.
v11.8.0, v10.16.0	Ahora se admite la opción timeout.
v8.0.0	Ahora se admite la opción lookup.
v8.0.0	La opción ALPNProtocols ahora puede ser un TypedArray o DataView.
v5.0.0	Ahora se admiten las opciones ALPN.
v5.3.0, v4.7.0	Ahora se admite la opción secureContext.
v0.11.3	Añadido en: v0.11.3

• options <Objeto>

  • enableTrace: Ver tls.createServer()
  • host <string> Host al que debe conectarse el cliente. Predeterminado: 'localhost'.
  • port <número> Puerto al que debe conectarse el cliente.
  • path <string> Crea una conexión de socket Unix a la ruta. Si se especifica esta opción, se ignoran host y port.
  • socket <stream.Duplex> Establece una conexión segura en un socket dado en lugar de crear un nuevo socket. Por lo general, esta es una instancia de net.Socket, pero se permite cualquier flujo Duplex. Si se especifica esta opción, se ignoran path, host y port, excepto para la validación de certificados. Por lo general, un socket ya está conectado cuando se pasa a tls.connect(), pero se puede conectar más tarde. La conexión/desconexión/destrucción de socket es responsabilidad del usuario; llamar a tls.connect() no hará que se llame a net.connect().
  • allowHalfOpen <boolean> Si se establece en false, el socket finalizará automáticamente el lado grabable cuando finalice el lado legible. Si se establece la opción socket, esta opción no tiene efecto. Consulte la opción allowHalfOpen de net.Socket para obtener más información. Predeterminado: false.
  • rejectUnauthorized <boolean> Si no es false, el certificado del servidor se verifica con la lista de CA suministradas. Se emite un evento 'error' si falla la verificación; err.code contiene el código de error de OpenSSL. Predeterminado: true.
  • pskCallback <Función> Para la negociación TLS-PSK, consulte Claves precompartidas.
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Una matriz de cadenas, Buffers, TypedArrays o DataViews, o un único Buffer, TypedArray o DataView que contenga los protocolos ALPN admitidos. Los Buffers deben tener el formato [long][nombre][long][nombre]... p. ej. '\x08http/1.1\x08http/1.0', donde el byte long es la longitud del siguiente nombre de protocolo. Pasar una matriz suele ser mucho más sencillo, p. ej. ['http/1.1', 'http/1.0']. Los protocolos anteriores en la lista tienen mayor preferencia que los posteriores.
  • servername: <string> Nombre del servidor para la extensión TLS SNI (Indicación de nombre de servidor). Es el nombre del host al que se está conectando y debe ser un nombre de host, no una dirección IP. Puede ser utilizado por un servidor multi-homed para elegir el certificado correcto para presentar al cliente, consulte la opción SNICallback para tls.createServer().
  • checkServerIdentity(servername, cert) <Función> Una función de devolución de llamada que se utilizará (en lugar de la función integrada tls.checkServerIdentity()) al verificar el nombre de host del servidor (o el servername proporcionado cuando se establece explícitamente) con el certificado. Esto debería devolver un <Error> si la verificación falla. El método debería devolver undefined si se verifican servername y cert.
  • session <Buffer> Una instancia de Buffer, que contiene la sesión TLS.
  • minDHSize <número> Tamaño mínimo del parámetro DH en bits para aceptar una conexión TLS. Cuando un servidor ofrece un parámetro DH con un tamaño menor que minDHSize, se destruye la conexión TLS y se genera un error. Predeterminado: 1024.
  • highWaterMark: <número> Coherente con el parámetro de flujo legible highWaterMark. Predeterminado: 16 * 1024.
  • secureContext: Objeto de contexto TLS creado con tls.createSecureContext(). Si no se proporciona un secureContext, se creará uno pasando todo el objeto options a tls.createSecureContext().
  • onread <Objeto> Si falta la opción socket, los datos entrantes se almacenan en un único buffer y se pasan a la callback suministrada cuando llegan datos al socket; de lo contrario, se ignora la opción. Consulte la opción onread de net.Socket para obtener más información.
  • ...: Opciones de tls.createSecureContext() que se utilizan si falta la opción secureContext; de lo contrario, se ignoran.
  • ...: Cualquier opción de socket.connect() que aún no esté en la lista.

• callback <Función>

• Devuelve: <tls.TLSSocket>

La función callback, si se especifica, se añadirá como un detector para el evento 'secureConnect'.

tls.connect() devuelve un objeto tls.TLSSocket.

A diferencia de la API https, tls.connect() no habilita la extensión SNI (Server Name Indication) de forma predeterminada, lo que puede provocar que algunos servidores devuelvan un certificado incorrecto o rechacen la conexión por completo. Para habilitar SNI, establezca la opción servername además de host.

Lo siguiente ilustra un cliente para el ejemplo de servidor eco de tls.createServer():

ESM

// Asume un servidor eco que está escuchando en el puerto 8000.
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // Necesario solo si el servidor requiere la autenticación de certificado de cliente.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necesario solo si el servidor utiliza un certificado autofirmado.
  ca: [readFileSync('server-cert.pem')],

  // Necesario solo si el certificado del servidor no es para "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('cliente conectado', socket.authorized ? 'autorizado' : 'no autorizado')
  stdin.pipe(socket)
  stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('el servidor finaliza la conexión')
})

CJS

// Asume un servidor eco que está escuchando en el puerto 8000.
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // Necesario solo si el servidor requiere la autenticación de certificado de cliente.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necesario solo si el servidor utiliza un certificado autofirmado.
  ca: [readFileSync('server-cert.pem')],

  // Necesario solo si el certificado del servidor no es para "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('cliente conectado', socket.authorized ? 'autorizado' : 'no autorizado')
  process.stdin.pipe(socket)
  process.stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('el servidor finaliza la conexión')
})

Para generar el certificado y la clave para este ejemplo, ejecute:

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

Luego, para generar el certificado server-cert.pem para este ejemplo, ejecute:

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

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

Agregado en: v0.11.3

• path <string> Valor predeterminado para options.path.
• options <Object> Ver tls.connect().
• callback <Function> Ver tls.connect().
• Devuelve: <tls.TLSSocket>

Igual que tls.connect() excepto que path se puede proporcionar como un argumento en lugar de una opción.

Una opción de ruta, si se especifica, tendrá prioridad sobre el argumento de ruta.

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

Agregado en: v0.11.3

• port <number> Valor predeterminado para options.port.
• host <string> Valor predeterminado para options.host.
• options <Object> Ver tls.connect().
• callback <Function> Ver tls.connect().
• Devuelve: <tls.TLSSocket>

Igual que tls.connect() excepto que port y host se pueden proporcionar como argumentos en lugar de opciones.

Una opción de puerto o host, si se especifica, tendrá prioridad sobre cualquier argumento de puerto o host.

tls.createSecureContext([options])

[Historial]

Versión	Cambios
v22.9.0, v20.18.0	Se ha añadido la opción allowPartialTrustChain.
v22.4.0, v20.16.0	Las opciones clientCertEngine, privateKeyEngine y privateKeyIdentifier dependen del soporte de motor personalizado en OpenSSL, que está obsoleto en OpenSSL 3.
v19.8.0, v18.16.0	La opción dhparam ahora se puede establecer en 'auto' para habilitar DHE con parámetros conocidos apropiados.
v12.12.0	Se añadieron las opciones privateKeyIdentifier y privateKeyEngine para obtener la clave privada de un motor OpenSSL.
v12.11.0	Se añadió la opción sigalgs para anular los algoritmos de firma admitidos.
v12.0.0	Se añadió la compatibilidad con TLSv1.3.
v11.5.0	La opción ca: ahora admite BEGIN TRUSTED CERTIFICATE.
v11.4.0, v10.16.0	Se pueden usar minVersion y maxVersion para restringir las versiones de protocolo TLS permitidas.
v10.0.0	ecdhCurve ya no se puede establecer en false debido a un cambio en OpenSSL.
v9.3.0	El parámetro options ahora puede incluir clientCertEngine.
v9.0.0	La opción ecdhCurve ahora puede ser varios nombres de curva separados por ':' o 'auto'.
v7.3.0	Si la opción key es una matriz, las entradas individuales ya no necesitan una propiedad passphrase. Las entradas de Array también pueden ser ahora solo string o Buffer.
v5.2.0	La opción ca ahora puede ser una sola cadena que contiene varios certificados de CA.
v0.11.13	Añadido en: v0.11.13

• options <Objeto>
  • allowPartialTrustChain <boolean> Trata los certificados intermedios (no autofirmados) en la lista de certificados de CA de confianza como de confianza.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> Anula opcionalmente los certificados de CA de confianza. De forma predeterminada, confía en las CA conocidas seleccionadas por Mozilla. Las CA de Mozilla se reemplazan completamente cuando las CA se especifican explícitamente usando esta opción. El valor puede ser una cadena o Buffer, o una Array de cadenas y/o Buffer. Cualquier cadena o Buffer puede contener varias CA PEM concatenadas. El certificado del par debe ser encadenable a una CA en la que confíe el servidor para que la conexión se autentique. Cuando se utilizan certificados que no son encadenables a una CA conocida, la CA del certificado debe especificarse explícitamente como de confianza o la conexión no se autenticará. Si el par utiliza un certificado que no coincide o no encadena con una de las CA predeterminadas, utilice la opción ca para proporcionar un certificado de CA con el que el certificado del par pueda coincidir o encadenar. Para los certificados autofirmados, el certificado es su propia CA y debe proporcionarse. Para los certificados codificados en PEM, los tipos admitidos son "TRUSTED CERTIFICATE", "X509 CERTIFICATE" y "CERTIFICATE". Consulte también tls.rootCertificates.
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> Cadenas de certificados en formato PEM. Se debe proporcionar una cadena de certificados por clave privada. Cada cadena de certificados debe constar del certificado con formato PEM para una clave privada proporcionada, seguido de los certificados intermedios con formato PEM (si los hay), en orden, y sin incluir la CA raíz (la CA raíz debe ser preconocida por el par, consulte ca). Al proporcionar varias cadenas de certificados, no tienen que estar en el mismo orden que sus claves privadas en key. Si no se proporcionan los certificados intermedios, el par no podrá validar el certificado y la negociación fallará.
  • sigalgs <string> Lista separada por dos puntos de algoritmos de firma admitidos. La lista puede contener algoritmos de resumen (SHA256, MD5, etc.), algoritmos de clave pública (RSA-PSS, ECDSA, etc.), combinación de ambos (por ejemplo, 'RSA+SHA384') o nombres de esquemas TLS v1.3 (por ejemplo, rsa_pss_pss_sha512). Consulte las páginas del manual de OpenSSL para obtener más información.
  • ciphers <string> Especificación del conjunto de cifrados, reemplazando el predeterminado. Para obtener más información, consulte Modificación del conjunto de cifrados TLS predeterminado. Los cifrados permitidos se pueden obtener a través de tls.getCiphers(). Los nombres de los cifrados deben estar en mayúsculas para que OpenSSL los acepte.
  • clientCertEngine <string> Nombre de un motor OpenSSL que puede proporcionar el certificado del cliente. Obsoleto.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> CRL (Listas de revocación de certificados) con formato PEM.
  • dhparam <string> | <Buffer> 'auto' o parámetros Diffie-Hellman personalizados, necesarios para el secreto directo perfecto que no sea ECDHE [/api/tls#perfect-forward-secrecy]. Si se omite o no es válido, los parámetros se descartan silenciosamente y los cifrados DHE no estarán disponibles. El secreto directo perfecto basado en ECDHE [/api/tls#perfect-forward-secrecy] seguirá estando disponible.
  • ecdhCurve <string> Una cadena que describe una curva nombrada o una lista separada por dos puntos de NID o nombres de curva, por ejemplo, P-521:P-384:P-256, para usar para el acuerdo de clave ECDH. Establecer en auto para seleccionar la curva automáticamente. Utilice crypto.getCurves() para obtener una lista de nombres de curva disponibles. En versiones recientes, openssl ecparam -list_curves también mostrará el nombre y la descripción de cada curva elíptica disponible. Predeterminado: tls.DEFAULT_ECDH_CURVE.
  • honorCipherOrder <boolean> Intenta utilizar las preferencias del conjunto de cifrados del servidor en lugar de las del cliente. Cuando es true, hace que se establezca SSL_OP_CIPHER_SERVER_PREFERENCE en secureOptions, consulte Opciones de OpenSSL para obtener más información.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Claves privadas en formato PEM. PEM permite la opción de que las claves privadas estén encriptadas. Las claves encriptadas se descifrarán con options.passphrase. Se pueden proporcionar varias claves que usan diferentes algoritmos como una matriz de cadenas o búferes de clave sin cifrar, o una matriz de objetos en la forma {pem: \<string|buffer\>[, passphrase: \<string\>]}. El formato de objeto solo puede ocurrir en una matriz. object.passphrase es opcional. Las claves encriptadas se descifrarán con object.passphrase si se proporciona, o con options.passphrase si no lo está.
  • privateKeyEngine <string> Nombre de un motor OpenSSL para obtener la clave privada. Debe usarse junto con privateKeyIdentifier. Obsoleto.
  • privateKeyIdentifier <string> Identificador de una clave privada administrada por un motor OpenSSL. Debe usarse junto con privateKeyEngine. No debe establecerse junto con key, porque ambas opciones definen una clave privada de diferentes maneras. Obsoleto.
  • maxVersion <string> Establece opcionalmente la versión máxima de TLS que se permitirá. Una de 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. No se puede especificar junto con la opción secureProtocol; use una u otra. Predeterminado: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> Establece opcionalmente la versión mínima de TLS que se permitirá. Una de 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. No se puede especificar junto con la opción secureProtocol; use una u otra. Evite establecer una versión inferior a TLSv1.2, pero puede ser necesario para la interoperabilidad. Las versiones anteriores a TLSv1.2 pueden requerir la degradación del Nivel de seguridad de OpenSSL. Predeterminado: tls.DEFAULT_MIN_VERSION.
  • passphrase <string> Contraseña compartida utilizada para una sola clave privada y/o un PFX.
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Clave privada y cadena de certificados codificados en PFX o PKCS12. pfx es una alternativa a proporcionar key y cert individualmente. PFX suele estar encriptado; si lo está, passphrase se utilizará para descifrarlo. Se pueden proporcionar varios PFX como una matriz de búferes PFX sin cifrar, o una matriz de objetos en la forma {buf: \<string|buffer\>[, passphrase: \<string\>]}. El formato de objeto solo puede ocurrir en una matriz. object.passphrase es opcional. Los PFX encriptados se descifrarán con object.passphrase si se proporciona, o con options.passphrase si no lo está.
  • secureOptions <number> Afecta opcionalmente el comportamiento del protocolo OpenSSL, lo que normalmente no es necesario. ¡Esto debe usarse con cuidado, si es que se usa! El valor es una máscara de bits numérica de las opciones SSL_OP_* de Opciones de OpenSSL.
  • secureProtocol <string> Mecanismo heredado para seleccionar la versión del protocolo TLS que se utilizará, no admite el control independiente de la versión mínima y máxima, y no admite la limitación del protocolo a TLSv1.3. Utilice minVersion y maxVersion en su lugar. Los valores posibles se enumeran como SSL_METHODS, utilice los nombres de las funciones como cadenas. Por ejemplo, use 'TLSv1_1_method' para forzar la versión 1.1 de TLS o 'TLS_method' para permitir cualquier versión del protocolo TLS hasta TLSv1.3. No se recomienda usar versiones de TLS inferiores a 1.2, pero puede ser necesario para la interoperabilidad. Predeterminado: ninguno, consulte minVersion.
  • sessionIdContext <string> Identificador opaco utilizado por los servidores para garantizar que el estado de la sesión no se comparta entre aplicaciones. No utilizado por los clientes.
  • ticketKeys: <Buffer> 48 bytes de datos pseudorandom criptográficamente sólidos. Consulte Reanudación de sesión para obtener más información.
  • sessionTimeout <number> El número de segundos después del cual una sesión TLS creada por el servidor ya no será reanudable. Consulte Reanudación de sesión para obtener más información. Predeterminado: 300.

tls.createServer() establece el valor predeterminado de la opción honorCipherOrder en true, otras API que crean contextos seguros lo dejan sin establecer.

tls.createServer() utiliza un valor hash SHA1 truncado de 128 bits generado a partir de process.argv como el valor predeterminado de la opción sessionIdContext; otras API que crean contextos seguros no tienen ningún valor predeterminado.

El método tls.createSecureContext() crea un objeto SecureContext. Se puede usar como argumento para varias API de tls, como server.addContext(), pero no tiene métodos públicos. El constructor tls.Server y el método tls.createServer() no admiten la opción secureContext.

Se requiere una clave para los cifrados que utilizan certificados. Se puede usar key o pfx para proporcionarla.

Si no se proporciona la opción ca, Node.js usará de forma predeterminada la lista de CA de confianza pública de Mozilla.

Se desaconseja el uso de parámetros DHE personalizados en favor de la nueva opción dhparam: 'auto'. Cuando se establece en 'auto', se seleccionarán automáticamente parámetros DHE conocidos de resistencia suficiente. De lo contrario, si es necesario, se puede usar openssl dhparam para crear parámetros personalizados. La longitud de la clave debe ser mayor o igual a 1024 bits o se producirá un error. Aunque se permiten 1024 bits, utilice 2048 bits o más para una mayor seguridad.

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

[Historial]

Versión	Cambios
v5.0.0	Ahora se admiten las opciones ALPN.
v0.11.3	Obsoleto desde: v0.11.3
v0.3.2	Añadido en: v0.3.2

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use tls.TLSSocket en su lugar.

• context <Objeto> Un objeto de contexto seguro como el devuelto por tls.createSecureContext()
• isServer <booleano> true para especificar que esta conexión TLS debe abrirse como un servidor.
• requestCert <booleano> true para especificar si un servidor debe solicitar un certificado a un cliente que se conecta. Solo se aplica cuando isServer es true.
• rejectUnauthorized <booleano> Si no es false, un servidor rechaza automáticamente los clientes con certificados inválidos. Solo se aplica cuando isServer es true.
• options
  • enableTrace: Ver tls.createServer()
  • secureContext: Un objeto de contexto TLS de tls.createSecureContext()
  • isServer: Si true, el socket TLS se instanciará en modo servidor. Predeterminado: false.
  • server <net.Server> Una instancia net.Server
  • requestCert: Ver tls.createServer()
  • rejectUnauthorized: Ver tls.createServer()
  • ALPNProtocols: Ver tls.createServer()
  • SNICallback: Ver tls.createServer()
  • session <Buffer> Una instancia Buffer que contiene una sesión TLS.
  • requestOCSP <booleano> Si true, especifica que la extensión de solicitud de estado OCSP se agregará al saludo del cliente y se emitirá un evento 'OCSPResponse' en el socket antes de establecer una comunicación segura.

Crea un nuevo objeto de par seguro con dos flujos, uno de los cuales lee y escribe los datos encriptados y el otro lee y escribe los datos en texto claro. Generalmente, el flujo encriptado se conecta a/desde un flujo de datos encriptados entrantes y el de texto claro se usa como reemplazo para el flujo encriptado inicial.

tls.createSecurePair() devuelve un objeto tls.SecurePair con las propiedades de flujo cleartext y encrypted.

Usar cleartext tiene la misma API que tls.TLSSocket.

El método tls.createSecurePair() ahora está obsoleto en favor de tls.TLSSocket(). Por ejemplo, el código:

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

puede ser reemplazado por:

secureSocket = tls.TLSSocket(socket, options)

donde secureSocket tiene la misma API que pair.cleartext.

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

[Historial]

Versión	Cambios
v22.4.0, v20.16.0	La opción clientCertEngine depende del soporte de motor personalizado en OpenSSL, que está en desuso en OpenSSL 3.
v19.0.0	Si se establece ALPNProtocols, las conexiones entrantes que envíen una extensión ALPN sin protocolos compatibles se terminarán con una alerta fatal no_application_protocol.
v20.4.0, v18.19.0	El parámetro options ahora puede incluir ALPNCallback.
v12.3.0	El parámetro options ahora admite las opciones de net.createServer().
v9.3.0	El parámetro options ahora puede incluir clientCertEngine.
v8.0.0	La opción ALPNProtocols ahora puede ser un TypedArray o DataView.
v5.0.0	Ahora se admiten las opciones ALPN.
v0.3.2	Agregado en: v0.3.2

• options <Object>

  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Un array de strings, Buffers, TypedArrays, o DataViews, o un único Buffer, TypedArray, o DataView que contiene los protocolos ALPN admitidos. Los Buffers deben tener el formato [len][name][len][name]... e.g. 0x05hello0x05world, donde el primer byte es la longitud del siguiente nombre de protocolo. Pasar un array suele ser mucho más sencillo, e.g. ['hello', 'world']. (Los protocolos deben estar ordenados por su prioridad.)
  • ALPNCallback: <Function> Si se establece, se llamará a esta función cuando un cliente abra una conexión utilizando la extensión ALPN. Se pasará un argumento a la función de retorno: un objeto que contiene los campos servername y protocols, que contienen respectivamente el nombre del servidor de la extensión SNI (si existe) y un array de strings con el nombre del protocolo ALPN. La función de retorno debe devolver uno de los strings listados en protocols, que se devolverá al cliente como el protocolo ALPN seleccionado, o undefined, para rechazar la conexión con una alerta fatal. Si se devuelve un string que no coincide con uno de los protocolos ALPN del cliente, se generará un error. Esta opción no se puede utilizar con la opción ALPNProtocols, y si se establecen ambas opciones se generará un error.
  • clientCertEngine <string> Nombre de un motor OpenSSL que puede proporcionar el certificado de cliente. En desuso.
  • enableTrace <boolean> Si es true, se llamará a tls.TLSSocket.enableTrace() en las nuevas conexiones. El seguimiento se puede habilitar después de que se establezca la conexión segura, pero esta opción debe usarse para rastrear la configuración de la conexión segura. Predeterminado: false.
  • handshakeTimeout <number> Aborta la conexión si el protocolo de enlace SSL/TLS no termina en el número de milisegundos especificado. Se emite un 'tlsClientError' en el objeto tls.Server cada vez que se agota el tiempo de espera de un protocolo de enlace. Predeterminado: 120000 (120 segundos).
  • rejectUnauthorized <boolean> Si no es false, el servidor rechazará cualquier conexión que no esté autorizada con la lista de CAs suministradas. Esta opción solo tiene efecto si requestCert es true. Predeterminado: true.
  • requestCert <boolean> Si es true, el servidor solicitará un certificado a los clientes que se conecten e intentará verificar ese certificado. Predeterminado: false.
  • sessionTimeout <number> El número de segundos después de los cuales una sesión TLS creada por el servidor ya no se podrá reanudar. Consulte Reanudación de sesión para obtener más información. Predeterminado: 300.
  • SNICallback(servername, callback) <Function> Una función a la que se llamará si el cliente admite la extensión SNI TLS. Se pasarán dos argumentos cuando se llame: servername y callback. callback es una función de retorno de llamada que recibe primero un error y que toma dos argumentos opcionales: error y ctx. ctx, si se proporciona, es una instancia de SecureContext. Se puede utilizar tls.createSecureContext() para obtener un SecureContext adecuado. Si se llama a callback con un argumento ctx falso, se utilizará el contexto seguro predeterminado del servidor. Si no se proporcionó SNICallback, se utilizará la función de retorno de llamada predeterminada con la API de alto nivel (ver más abajo).
  • ticketKeys: <Buffer> 48 bytes de datos pseudoaleatorios criptográficamente seguros. Consulte Reanudación de sesión para obtener más información.
  • pskCallback <Function> Para la negociación TLS-PSK, consulte Claves precompartidas.
  • pskIdentityHint <string> sugerencia opcional para enviar a un cliente para ayudar con la selección de la identidad durante la negociación TLS-PSK. Se ignorará en TLS 1.3. Si no se puede establecer pskIdentityHint, se emitirá 'tlsClientError' con el código 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED'.
  • ...: Se puede proporcionar cualquier opción de tls.createSecureContext(). Para los servidores, normalmente se requieren las opciones de identidad (pfx, key/cert, o pskCallback).
  • ...: Se puede proporcionar cualquier opción de net.createServer().

• secureConnectionListener <Function>

• Devuelve: <tls.Server>

Crea un nuevo tls.Server. El secureConnectionListener, si se proporciona, se establece automáticamente como un listener para el evento 'secureConnection'.

La opción ticketKeys se comparte automáticamente entre los workers del módulo node:cluster.

Lo siguiente ilustra un sencillo servidor eco:

ESM

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

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

  // Esto es necesario solo si se utiliza la autenticación de certificado de cliente.
  requestCert: true,

  // Esto es necesario solo si el cliente utiliza un certificado autofirmado.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server connected', socket.authorized ? 'authorized' : 'unauthorized')
  socket.write('¡bienvenido!\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'),

  // Esto es necesario solo si se utiliza la autenticación de certificado de cliente.
  requestCert: true,

  // Esto es necesario solo si el cliente utiliza un certificado autofirmado.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server connected', socket.authorized ? 'authorized' : 'unauthorized')
  socket.write('¡bienvenido!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('servidor vinculado')
})

Para generar el certificado y la clave para este ejemplo, ejecute:

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

Luego, para generar el certificado client-cert.pem para este ejemplo, ejecute:

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

El servidor se puede probar conectándose a él utilizando el cliente de ejemplo de tls.connect().

tls.getCiphers()

Añadido en: v0.10.2

• Devuelve: <string[]>

Devuelve un array con los nombres de los cifrados TLS soportados. Los nombres están en minúsculas por razones históricas, pero deben ponerse en mayúsculas para ser utilizados en la opción ciphers de tls.createSecureContext().

No todos los cifrados soportados están habilitados por defecto. Ver Modificación del conjunto de cifrado TLS predeterminado.

Los nombres de cifrado que empiezan por 'tls_' son para TLSv1.3, todos los demás son para TLSv1.2 e inferiores.

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

tls.rootCertificates

Añadido en: v12.3.0

• <string[]>

Un array inmutable de cadenas que representan los certificados raíz (en formato PEM) del almacén de CA de Mozilla incluido, tal y como lo proporciona la versión actual de Node.js.

El almacén de CA incluido, tal y como lo proporciona Node.js, es una instantánea del almacén de CA de Mozilla que se fija en el momento de la publicación. Es idéntico en todas las plataformas soportadas.

tls.DEFAULT_ECDH_CURVE

[Historial]

Versión	Cambios
v10.0.0	El valor predeterminado cambió a 'auto'.
v0.11.13	Añadido en: v0.11.13

El nombre de curva predeterminado para usar en el acuerdo de claves ECDH en un servidor tls. El valor predeterminado es 'auto'. Consulte tls.createSecureContext() para obtener más información.

tls.DEFAULT_MAX_VERSION

Añadido en: v11.4.0

• <string> El valor predeterminado de la opción maxVersion de tls.createSecureContext(). Se le puede asignar cualquiera de las versiones de protocolo TLS admitidas, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', o 'TLSv1'. Predeterminado: 'TLSv1.3', a menos que se cambie utilizando las opciones de la CLI. El uso de --tls-max-v1.2 establece el valor predeterminado en 'TLSv1.2'. El uso de --tls-max-v1.3 establece el valor predeterminado en 'TLSv1.3'. Si se proporcionan varias de las opciones, se utiliza el máximo más alto.

tls.DEFAULT_MIN_VERSION

Agregado en: v11.4.0

• <string> El valor predeterminado de la opción minVersion de tls.createSecureContext(). Se le puede asignar cualquiera de las versiones de protocolo TLS admitidas, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Las versiones anteriores a TLSv1.2 pueden requerir la degradación del Nivel de seguridad de OpenSSL. Predeterminado: 'TLSv1.2', a menos que se cambie usando opciones de CLI. Usar --tls-min-v1.0 establece el valor predeterminado a 'TLSv1'. Usar --tls-min-v1.1 establece el valor predeterminado a 'TLSv1.1'. Usar --tls-min-v1.3 establece el valor predeterminado a 'TLSv1.3'. Si se proporcionan varias de las opciones, se utiliza el mínimo más bajo.

tls.DEFAULT_CIPHERS

Agregado en: v19.8.0, v18.16.0

• <string> El valor predeterminado de la opción ciphers de tls.createSecureContext(). Se le puede asignar cualquier cifrado OpenSSL compatible. El valor predeterminado es el contenido de crypto.constants.defaultCoreCipherList, a menos que se cambie usando opciones de CLI con --tls-default-ciphers.