Node.js v12.16.2 Documentation TLS (SSL)

Index View on single page View as JSON View another version ▼ 

Edit on GitHub 

Table of Contents

TLS (SSL)

    TLS/SSL Concepts
        Perfect Forward Secrecy
        ALPN and SNI
        Pre-shared keys
        Client-initiated renegotiation attack mitigation
        Session Resumption
    Modifying the Default TLS Cipher suite

    Class: tls.Server
        Event: 'keylog'
        Event: 'newSession'
        Event: 'OCSPRequest'
        Event: 'resumeSession'
        Event: 'secureConnection'
        Event: 'tlsClientError'
        server.addContext(hostname, context)
        server.address()
        server.close([callback])
        server.connections
        server.getTicketKeys()
        server.listen()
        server.setSecureContext(options)
        server.setTicketKeys(keys)

    Class: tls.TLSSocket
        new tls.TLSSocket(socket[, options])
        Event: 'keylog'
        Event: 'OCSPResponse'
        Event: 'secureConnect'
        Event: 'session'
        tlsSocket.address()
        tlsSocket.authorizationError
        tlsSocket.authorized
        tlsSocket.disableRenegotiation()
        tlsSocket.enableTrace()
        tlsSocket.encrypted
        tlsSocket.getCertificate()
        tlsSocket.getCipher()
        tlsSocket.getEphemeralKeyInfo()
        tlsSocket.getFinished()

        tlsSocket.getPeerCertificate([detailed])
            Certificate Object
        tlsSocket.getPeerFinished()
        tlsSocket.getProtocol()
        tlsSocket.getSession()
        tlsSocket.getSharedSigalgs()
        tlsSocket.getTLSTicket()
        tlsSocket.isSessionReused()
        tlsSocket.localAddress
        tlsSocket.localPort
        tlsSocket.remoteAddress
        tlsSocket.remoteFamily
        tlsSocket.remotePort
        tlsSocket.renegotiate(options, callback)
        tlsSocket.setMaxSendFragment(size)
    tls.checkServerIdentity(hostname, cert)
    tls.connect(options[, callback])
    tls.connect(path[, options][, callback])
    tls.connect(port[, host][, options][, callback])
    tls.createSecureContext([options])
    tls.createServer([options][, secureConnectionListener])
    tls.getCiphers()
    tls.rootCertificates
    tls.DEFAULT_ECDH_CURVE
    tls.DEFAULT_MAX_VERSION
    tls.DEFAULT_MIN_VERSION

    Deprecated APIs

        Class: CryptoStream
            cryptoStream.bytesWritten

        Class: SecurePair
            Event: 'secure'
        tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])

TLS (SSL)

Stability: 2 - Stable

The tls module provides an implementation of the Transport Layer Security (TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL. The module can be accessed using:

const tls = require(‘tls’);

TLS/SSL Concepts

The TLS/SSL is a public/private key infrastructure (PKI). For most common cases, each client and server must have a private key.

Private keys can be generated in multiple ways. The example below illustrates use of the OpenSSL command-line interface to generate a 2048-bit RSA private key:

openssl genrsa -out ryans-key.pem 2048

With TLS/SSL, all servers (and some clients) must have a certificate. Certificates are public keys that correspond to a private key, and that are digitally signed either by a Certificate Authority or by the owner of the private key (such certificates are referred to as “self-signed”). The first step to obtaining a certificate is to create a Certificate Signing Request (CSR) file.

The OpenSSL command-line interface can be used to generate a CSR for a private key:

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

Once the CSR file is generated, it can either be sent to a Certificate Authority for signing or used to generate a self-signed certificate.

Creating a self-signed certificate using the OpenSSL command-line interface is illustrated in the example below:

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

Once the certificate is generated, it can be used to generate a .pfx or .p12 file:

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

Where:

in: is the signed certificate
inkey: is the associated private key
certfile: is a concatenation of all Certificate Authority (CA) certs into a single file, e.g. cat ca1-cert.pem ca2-cert.pem > ca-cert.pem

Perfect Forward Secrecy

The term “Forward Secrecy” or “Perfect Forward Secrecy” describes a feature of key-agreement (i.e., key-exchange) methods. That is, the server and client keys are used to negotiate new temporary keys that are used specifically and only for the current communication session. Practically, this means that even if the server’s private key is compromised, communication can only be decrypted by eavesdroppers if the attacker manages to obtain the key-pair specifically generated for the session.

Perfect Forward Secrecy is achieved by randomly generating a key pair for key-agreement on every TLS/SSL handshake (in contrast to using the same key for all sessions). Methods implementing this technique are called “ephemeral”.

Currently two methods are commonly used to achieve Perfect Forward Secrecy (note the character “E” appended to the traditional abbreviations):

DHE: An ephemeral version of the Diffie Hellman key-agreement protocol.
ECDHE: An ephemeral version of the Elliptic Curve Diffie Hellman key-agreement protocol.

Ephemeral methods may have some performance drawbacks, because key generation is expensive.

To use Perfect Forward Secrecy using DHE with the tls module, it is required to generate Diffie-Hellman parameters and specify them with the dhparam option to tls.createSecureContext(). The following illustrates the use of the OpenSSL command-line interface to generate such parameters:

openssl dhparam -outform PEM -out dhparam.pem 2048

If using Perfect Forward Secrecy using ECDHE, Diffie-Hellman parameters are not required and a default ECDHE curve will be used. The ecdhCurve property can be used when creating a TLS Server to specify the list of names of supported curves to use, see tls.createServer() for more info.

Perfect Forward Secrecy was optional up to TLSv1.2, but it is not optional for TLSv1.3, because all TLSv1.3 cipher suites use ECDHE.
ALPN and SNI

ALPN (Application-Layer Protocol Negotiation Extension) and SNI (Server Name Indication) are TLS handshake extensions:

ALPN: Allows the use of one TLS server for multiple protocols (HTTP, HTTP/2)
SNI: Allows the use of one TLS server for multiple hostnames with different SSL certificates.

Pre-shared keys

TLS-PSK support is available as an alternative to normal certificate-based authentication. It uses a pre-shared key instead of certificates to authenticate a TLS connection, providing mutual authentication. TLS-PSK and public key infrastructure are not mutually exclusive. Clients and servers can accommodate both, choosing either of them during the normal cipher negotiation step.

TLS-PSK is only a good choice where means exist to securely share a key with every connecting machine, so it does not replace PKI (Public Key Infrastructure) for the majority of TLS uses. The TLS-PSK implementation in OpenSSL has seen many security flaws in recent years, mostly because it is used only by a minority of applications. Please consider all alternative solutions before switching to PSK ciphers. Upon generating PSK it is of critical importance to use sufficient entropy as discussed in RFC 4086. Deriving a shared secret from a password or other low-entropy sources is not secure.

PSK ciphers are disabled by default, and using TLS-PSK thus requires explicitly specifying a cipher suite with the ciphers option. The list of available ciphers can be retrieved via openssl ciphers -v ‘PSK’. All TLS 1.3 ciphers are eligible for PSK but currently only those that use SHA256 digest are supported they can be retrieved via openssl ciphers -v -s -tls1_3 -psk.

According to the RFC 4279, PSK identities up to 128 bytes in length and PSKs up to 64 bytes in length must be supported. As of OpenSSL 1.1.0 maximum identity size is 128 bytes, and maximum PSK length is 256 bytes.

The current implementation doesn’t support asynchronous PSK callbacks due to the limitations of the underlying OpenSSL API.
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 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.

Its 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(‘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

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

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

Subsequent connections should say “Reused”, for example:

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

Modifying the Default TLS Cipher suite

Node.js is built with a default suite of enabled and disabled TLS ciphers. Currently, the default cipher suite is:

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

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

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.

128 bit AES is preferred over 192 and 256 bit AES in light of specific attacks affecting larger AES key sizes.

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 5 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 3 are enabled by default. The last 2 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.
Class: tls.Server

Added in: v0.3.2

Extends: 

Accepts encrypted connections using TLS or SSL.
Event: ‘keylog’

Added in: v12.3.0

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

Event: ‘newSession’

Added in: v0.9.2

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’

Added in: v0.11.13

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:

Client connects to the server and sends an 'OCSPRequest' (via the status info extension in ClientHello).
Server receives the request and emits the 'OCSPRequest' event, calling the listener if registered.
Server extracts the OCSP URL from either the certificate or issuer and performs an OCSP request to the CA.
Server receives 'OCSPResponse' from the CA and sends it back to the client via the callback argument
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’

Added in: v0.9.2

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

Event: ‘secureConnection’

Added in: v0.3.2

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 tlsSocket.alpnProtocol property is a string that contains the selected ALPN protocol. When ALPN has no selected protocol, tlsSocket.alpnProtocol equals false.

The tlsSocket.servername property is a string containing the server name requested via SNI.
Event: ‘tlsClientError’

Added in: v6.0.0

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)

Added in: v0.5.3

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