Node.js v26.11.1 documentation

Client-initiated renegotiation attack mitigation#

The TLS protocol allows clients to renegotiate certain aspects of the TLS session. Unfortunately, session renegotiation requires a disproportionate amount of server-side resources, making it a potential vector for denial-of-service attacks.

To mitigate the risk, renegotiation is limited to three times every ten minutes. An 'error' event is emitted on the tls.TLSSocket instance when this threshold is exceeded. The limits are configurable:

• tls.CLIENT_RENEG_LIMIT  Specifies the number of renegotiation requests. Default: 3.
• tls.CLIENT_RENEG_WINDOW  Specifies the time renegotiation window in seconds. Default: 600 (10 minutes).

The default renegotiation limits should not be modified without a full understanding of the implications and risks.

TLSv1.3 does not support renegotiation.

Session resumption#

Establishing a TLS session can be relatively slow. The process can be sped up by saving and later reusing the session state. There are several mechanisms to do so, discussed here from oldest to newest (and preferred).

Session identifiers#

Servers generate a unique ID for new connections and send it to the client. Clients and servers save the session state. When reconnecting, clients send the ID of their saved session state and if the server also has the state for that ID, it can agree to use it. Otherwise, the server will create a new session. See RFC 2246 for more information, page 23 and 30.

Resumption using session identifiers is supported by most web browsers when making HTTPS requests.

For Node.js, clients wait for the 'session' event to get the session data, and provide the data to the session option of a subsequent tls.connect() to reuse the session. Servers must implement handlers for the 'newSession' and 'resumeSession' events to save and restore the session data using the session ID as the lookup key to reuse sessions. To reuse sessions across load balancers or cluster workers, servers must use a shared session cache (such as Redis) in their session handlers.

Session tickets#

The servers encrypt the entire session state and send it to the client as a "ticket". When reconnecting, the state is sent to the server in the initial connection. This mechanism avoids the need for a server-side session cache. If the server doesn't use the ticket, for any reason (failure to decrypt it, it's too old, etc.), it will create a new session and send a new ticket. See RFC 5077 for more information.

Resumption using session tickets is becoming commonly supported by many web browsers when making HTTPS requests.

For Node.js, clients use the same APIs for resumption with session identifiers as for resumption with session tickets. For debugging, if tls.TLSSocket.getTLSTicket() returns a value, the session data contains a ticket, otherwise it contains client-side session state.

With TLSv1.3, be aware that multiple tickets may be sent by the server, resulting in multiple 'session' events, see 'session' for more information.

Single process servers need no specific implementation to use session tickets. To use session tickets across server restarts or load balancers, servers must all have the same ticket keys. There are three 16-byte keys internally, but the tls API exposes them as a single 48-byte buffer for convenience.

It's possible to get the ticket keys by calling server.getTicketKeys() on one server instance and then distribute them, but it is more reasonable to securely generate 48 bytes of secure random data and set them with the ticketKeys option of tls.createServer(). The keys should be regularly regenerated and server's keys can be reset with server.setTicketKeys().

Session ticket keys are cryptographic keys, and they must be stored securely. With TLS 1.2 and below, if they are compromised all sessions that used tickets encrypted with them can be decrypted. They should not be stored on disk, and they should be regenerated regularly.

If clients advertise support for tickets, the server will send them. The server can disable tickets by supplying require('node:constants').SSL_OP_NO_TICKET in secureOptions.

Both session identifiers and session tickets timeout, causing the server to create new sessions. The timeout can be configured with the sessionTimeout option of tls.createServer().

For all the mechanisms, when resumption fails, servers will create new sessions. Since failing to resume the session does not cause TLS/HTTPS connection failures, it is easy to not notice unnecessarily poor TLS performance. The OpenSSL CLI can be used to verify that servers are resuming sessions. Use the -reconnect option to openssl s_client, for example:

openssl s_client -connect localhost:443 -reconnect
bashcopy

Read through the debug output. The first connection should say "New", for example:

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

Subsequent connections should say "Reused", for example:

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

Modifying the default TLS cipher suite#

Node.js is built with a default suite of enabled and disabled TLS ciphers. This default cipher list can be configured when building Node.js to allow distributions to provide their own default list.

The following command can be used to show the default cipher suite:

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
consolecopy

This default can be replaced entirely using the --tls-cipher-list command-line switch (directly, or via the NODE_OPTIONS environment variable). For instance, the following makes ECDHE-RSA-AES128-GCM-SHA256:!RC4 the default TLS cipher suite:

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
bashcopy

To verify, use the following command to show the set cipher list, note the difference between defaultCoreCipherList and defaultCipherList:

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

i.e. the defaultCoreCipherList list is set at compilation time and the defaultCipherList is set at runtime.

To modify the default cipher suites from within the runtime, modify the tls.DEFAULT_CIPHERS variable, this must be performed before listening on any sockets, it will not affect sockets already opened. For example:

// Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy
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';
jscopy

The default can also be replaced on a per client or server basis using the ciphers option from tls.createSecureContext(), which is also available in tls.createServer(), tls.connect(), and when creating new tls.TLSSockets.

The ciphers list can contain a mixture of TLSv1.3 cipher suite names, the ones that start with 'TLS_', and specifications for TLSv1.2 and below cipher suites. The TLSv1.2 ciphers support a legacy specification format, consult the OpenSSL cipher list format documentation for details, but those specifications do not apply to TLSv1.3 ciphers. The TLSv1.3 suites can only be enabled by including their full name in the cipher list. They cannot, for example, be enabled or disabled by using the legacy TLSv1.2 'EECDH' or '!EECDH' specification.

Despite the relative order of TLSv1.3 and TLSv1.2 cipher suites, the TLSv1.3 protocol is significantly more secure than TLSv1.2, and will always be chosen over TLSv1.2 if the handshake indicates it is supported, and if any TLSv1.3 cipher suites are enabled.

The default cipher suite included within Node.js has been carefully selected to reflect current security best practices and risk mitigation. Changing the default cipher suite can have a significant impact on the security of an application. The --tls-cipher-list switch and ciphers option should by used only if absolutely necessary.

The default cipher suite prefers GCM ciphers for Chrome's 'modern cryptography' setting and also prefers ECDHE and DHE ciphers for perfect forward secrecy, while offering some backward compatibility.

Old clients that rely on insecure and deprecated RC4 or DES-based ciphers (like Internet Explorer 6) cannot complete the handshaking process with the default configuration. If these clients must be supported, the TLS recommendations may offer a compatible cipher suite. For more details on the format, see the OpenSSL cipher list format documentation.

There are only five TLSv1.3 cipher suites:

• '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'

The first three are enabled by default. The two CCM-based suites are supported by TLSv1.3 because they may be more performant on constrained systems, but they are not enabled by default since they offer less security.

OpenSSL security level#

The OpenSSL library enforces security levels to control the minimum acceptable level of security for cryptographic operations. OpenSSL's security levels range from 0 to 5, with each level imposing stricter security requirements. The default security level is 2, which is generally suitable for most modern applications. However, some legacy features and protocols, such as TLSv1, require a lower security level (SECLEVEL=0) to function properly. For more detailed information, please refer to the OpenSSL documentation on security levels.

Setting security levels#

To adjust the security level in your Node.js application, you can include @SECLEVEL=X within a cipher string, where X is the desired security level. For example, to set the security level to 0 while using the default OpenSSL cipher list, you could use:

import { createServer, connect } from 'node:tls';
import { readFileSync } from 'node:fs';
const port = 8000;

createServer({
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),
  ciphers: 'DEFAULT@SECLEVEL=0',
  minVersion: 'TLSv1',
}, function(socket) {
  console.log('Client connected with protocol:', socket.getProtocol());
  socket.end();
  this.close();
})
.listen(port, () => {
  connect(port, {
    ciphers: 'DEFAULT@SECLEVEL=0',
    minVersion: 'TLSv1',
    maxVersion: 'TLSv1',
    ca: [ readFileSync('server-cert.pem') ],
  });
});
const { createServer, connect } = require('node:tls');
const { readFileSync } = require('node:fs');
const port = 8000;

createServer({
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),
  ciphers: 'DEFAULT@SECLEVEL=0',
  minVersion: 'TLSv1',
}, function(socket) {
  console.log('Client connected with protocol:', socket.getProtocol());
  socket.end();
  this.close();
})
.listen(port, () => {
  connect(port, {
    ciphers: 'DEFAULT@SECLEVEL=0',
    minVersion: 'TLSv1',
    maxVersion: 'TLSv1',
    ca: [ readFileSync('server-cert.pem') ],
  });
});
javascriptcopy

This approach sets the security level to 0, allowing the use of legacy features while still leveraging the default OpenSSL ciphers.

To generate the certificate and key for this example, run:

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

Using --tls-cipher-list#

You can also set the security level and ciphers from the command line using the --tls-cipher-list=DEFAULT@SECLEVEL=X as described in Modifying the default TLS cipher suite. However, it is generally discouraged to use the command line option for setting ciphers and it is preferable to configure the ciphers for individual contexts within your application code, as this approach provides finer control and reduces the risk of globally downgrading the security level.

X509 certificate error codes#

Multiple functions can fail due to certificate errors that are reported by OpenSSL. In such a case, the function provides an via its callback that has the property code which can take one of the following values:

• 'UNABLE_TO_GET_ISSUER_CERT': Unable to get issuer certificate.
• 'UNABLE_TO_GET_CRL': Unable to get certificate CRL.
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': Unable to decrypt certificate's signature.
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': Unable to decrypt CRL's signature.
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': Unable to decode issuer public key.
• 'CERT_SIGNATURE_FAILURE': Certificate signature failure.
• 'CRL_SIGNATURE_FAILURE': CRL signature failure.
• 'CERT_NOT_YET_VALID': Certificate is not yet valid.
• 'CERT_HAS_EXPIRED': Certificate has expired.
• 'CRL_NOT_YET_VALID': CRL is not yet valid.
• 'CRL_HAS_EXPIRED': CRL has expired.
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD': Format error in certificate's notBefore field.
• 'ERROR_IN_CERT_NOT_AFTER_FIELD': Format error in certificate's notAfter field.
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD': Format error in CRL's lastUpdate field.
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': Format error in CRL's nextUpdate field.
• 'OUT_OF_MEM': Out of memory.
• 'DEPTH_ZERO_SELF_SIGNED_CERT': Self signed certificate.
• 'SELF_SIGNED_CERT_IN_CHAIN': Self signed certificate in certificate chain.
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': Unable to get local issuer certificate.
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': Unable to verify the first certificate.
• 'CERT_CHAIN_TOO_LONG': Certificate chain too long.
• 'CERT_REVOKED': Certificate revoked.
• 'INVALID_CA': Invalid CA certificate.
• 'PATH_LENGTH_EXCEEDED': Path length constraint exceeded.
• 'INVALID_PURPOSE': Unsupported certificate purpose.
• 'CERT_UNTRUSTED': Certificate not trusted.
• 'CERT_REJECTED': Certificate rejected.
• 'HOSTNAME_MISMATCH': Hostname mismatch.

When certificate errors like UNABLE_TO_VERIFY_LEAF_SIGNATURE, DEPTH_ZERO_SELF_SIGNED_CERT, or UNABLE_TO_GET_ISSUER_CERT occur, Node.js appends a hint suggesting that if the root CA is installed locally, try running with the --use-system-ca flag to direct developers towards a secure solution, to prevent unsafe workarounds.

Class: tls.Server#

• Extends:

Accepts encrypted connections using TLS or SSL.

Event: 'connection'#

• socket 

This event is emitted when a new TCP stream is established, before the TLS handshake begins. socket is typically an object of type net.Socket but will not receive events unlike the socket created from the net.Server 'connection' event. Usually users will not want to access this event.

This event can also be explicitly emitted by users to inject connections into the TLS server. In that case, any Duplex stream can be passed.

Event: 'keylog'#

• line  Line of ASCII text, in NSS SSLKEYLOGFILE format.
• tlsSocket  The tls.TLSSocket instance on which it was generated.

The keylog event is emitted when key material is generated or received by a connection to this server (typically before handshake has completed, but not necessarily). This keying material can be stored for debugging, as it allows captured TLS traffic to be decrypted. It may be emitted multiple times for each socket.

A typical use case is to append received lines to a common text file, which is later used by software (such as Wireshark) to decrypt the traffic:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' });
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...')
    return; // Only log keys for a particular IP
  logFile.write(line);
});
jscopy

Event: 'newSession'#

The 'newSession' event is emitted upon creation of a new TLS session. This may be used to store sessions in external storage. The data should be provided to the 'resumeSession' callback.

The listener callback is passed three arguments when called:

• sessionId  The TLS session identifier
• sessionData  The TLS session data
• callback  A callback function taking no arguments that must be invoked in order for data to be sent or received over the secure connection.

Listening for this event will have an effect only on connections established after the addition of the event listener.

Event: 'OCSPRequest'#

The 'OCSPRequest' event is emitted when the client sends a certificate status request. The listener callback is passed three arguments when called:

• certificate  The server certificate
• issuer  The issuer's certificate
• callback  A callback function that must be invoked to provide the results of the OCSP request.

The server's current certificate can be parsed to obtain the OCSP URL and certificate ID; after obtaining an OCSP response, callback(null, resp) is then invoked, where resp is a Buffer instance containing the OCSP response. Both certificate and issuer are Buffer DER-representations of the primary and issuer's certificates. These can be used to obtain the OCSP certificate ID and OCSP endpoint URL.

Alternatively, callback(null, null) may be called, indicating that there was no OCSP response.

Calling callback(err) will result in a socket.destroy(err) call.

The typical flow of an OCSP request is as follows:

1. Client connects to the server and sends an 'OCSPRequest' (via the status info extension in ClientHello).
2. Server receives the request and emits the 'OCSPRequest' event, calling the listener if registered.
3. Server extracts the OCSP URL from either the certificate or issuer and performs an OCSP request to the CA.
4. Server receives 'OCSPResponse' from the CA and sends it back to the client via the callback argument
5. Client validates the response and either destroys the socket or performs a handshake.

The issuer can be null if the certificate is either self-signed or the issuer is not in the root certificates list. (An issuer may be provided via the ca option when establishing the TLS connection.)

Listening for this event will have an effect only on connections established after the addition of the event listener.

An npm module like asn1.js may be used to parse the certificates.

Event: 'resumeSession'#

The 'resumeSession' event is emitted when the client requests to resume a previous TLS session. The listener callback is passed two arguments when called:

• sessionId  The TLS session identifier
• callback  A callback function to be called when the prior session has been recovered: callback([err[, sessionData]])
  • err 
  • sessionData 

The event listener should perform a lookup in external storage for the sessionData saved by the 'newSession' event handler using the given sessionId. If found, call callback(null, sessionData) to resume the session. If not found, the session cannot be resumed. callback() must be called without sessionData so that the handshake can continue and a new session can be created. It is possible to call callback(err) to terminate the incoming connection and destroy the socket.

Listening for this event will have an effect only on connections established after the addition of the event listener.

The following illustrates resuming a TLS session:

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);
});
jscopy

Event: 'secureConnection'#

The 'secureConnection' event is emitted after the handshaking process for a new connection has successfully completed. The listener callback is passed a single argument when called:

• tlsSocket  The established TLS socket.

The tlsSocket.authorized property is a boolean indicating whether the client has been verified by one of the supplied Certificate Authorities for the server. If tlsSocket.authorized is false, then socket.authorizationError is set to describe how authorization failed. Depending on the settings of the TLS server, unauthorized connections may still be accepted.

The tls.TLSSocket.servername and tls.TLSSocket.alpnProtocol properties can be used to check which server name was requested, and which protocol was negotiated.

Event: 'tlsClientError'#

The 'tlsClientError' event is emitted when an error occurs before a secure connection is established. The listener callback is passed two arguments when called:

• exception  The Error object describing the error
• tlsSocket  The tls.TLSSocket instance from which the error originated.

server.addContext(hostname, context)#

• hostname  A SNI host name or wildcard (e.g. '*')
• context