Exports

The default value of the ciphers option of {@link createSecureContext()}. It can be assigned any of the supported OpenSSL ciphers. Defaults to the content of crypto.constants.defaultCoreCipherList, unless changed using CLI options using --tls-default-ciphers.

@since v0.11.3

The default curve name to use for ECDH key agreement in a tls server. The default value is 'auto'. See {@link createSecureContext()} for further information.

@since v0.11.13

The default value of the maxVersion option of {@link createSecureContext()}. It can be assigned any of the supported TLS protocol versions, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Default:'TLSv1.3', unless changed using CLI options. Using --tls-max-v1.2 sets the default to 'TLSv1.2'. Using --tls-max-v1.3 sets the default to 'TLSv1.3'. If multiple of the options are provided, the highest maximum is used.

@since v11.4.0

The default value of the minVersion option of {@link createSecureContext()}. It can be assigned any of the supported TLS protocol versions, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Default:'TLSv1.2', unless changed using CLI options. Using --tls-min-v1.0 sets the default to 'TLSv1'. Using --tls-min-v1.1 sets the default to 'TLSv1.1'. Using --tls-min-v1.3 sets the default to 'TLSv1.3'. If multiple of the options are provided, the lowest minimum is used.

@since v11.4.0

An immutable array of strings representing the root certificates (in PEM format) from the bundled Mozilla CA store as supplied by the current Node.js version.

The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store that is fixed at release time. It is identical on all supported platforms.

@since v12.3.0

Accepts encrypted connections using TLS or SSL.

@since v0.3.2

Accepts encrypted connections using TLS or SSL.

@since v0.3.2

Performs transparent encryption of written data and all required TLS negotiation.

Instances of tls.TLSSocket implement the duplex Stream interface.

Methods that return TLS connection metadata (e.g.TLSSocket.getPeerCertificate) will only return data while the connection is open.

@since v0.11.4

Verifies the certificate cert is issued to hostname.

Returns Error object, populating it with reason, host, and cert on failure. On success, returns undefined.

This function is intended to be used in combination with thecheckServerIdentity option that can be passed to connect and as such operates on a certificate object. For other purposes, consider using x509.checkHost() instead.

This function can be overwritten by providing an alternative function as the options.checkServerIdentity option that is passed to tls.connect(). The overwriting function can call tls.checkServerIdentity() of course, to augment the checks done with additional verification.

This function is only called if the certificate passed all other checks, such as being issued by trusted CA (options.ca).

Earlier versions of Node.js incorrectly accepted certificates for a givenhostname if a matching uniformResourceIdentifier subject alternative name was present (see CVE-2021-44531). Applications that wish to acceptuniformResourceIdentifier subject alternative names can use a custom options.checkServerIdentity function that implements the desired behavior.

@since v0.8.4

The callback function, if specified, will be added as a listener for the 'secureConnect' event.

tls.connect() returns a TLSSocket object.

Unlike the https API, tls.connect() does not enable the SNI (Server Name Indication) extension by default, which may cause some servers to return an incorrect certificate or reject the connection altogether. To enable SNI, set the servername option in addition to host.

The following illustrates a client for the echo server example from createServer:

// Assumes an echo server that is listening on port 8000.
import tls from 'node:tls';
import fs from 'node:fs';

const options = {
// Necessary only if the server requires client certificate authentication.
key: fs.readFileSync('client-key.pem'),
cert: fs.readFileSync('client-cert.pem'),

// Necessary only if the server uses a self-signed certificate.
ca: [ fs.readFileSync('server-cert.pem') ],

// Necessary only if the server's cert isn't for "localhost".
checkServerIdentity: () => { return null; },
};

const socket = tls.connect(8000, options, () => {
console.log('client connected',
socket.authorized ? 'authorized' : 'unauthorized');
process.stdin.pipe(socket);
process.stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
console.log(data);
});
socket.on('end', () => {
console.log('server ends connection');
});

@since v0.11.3

The callback function, if specified, will be added as a listener for the 'secureConnect' event.

tls.connect() returns a TLSSocket object.

Unlike the https API, tls.connect() does not enable the SNI (Server Name Indication) extension by default, which may cause some servers to return an incorrect certificate or reject the connection altogether. To enable SNI, set the servername option in addition to host.

The following illustrates a client for the echo server example from createServer:

// Assumes an echo server that is listening on port 8000.
import tls from 'node:tls';
import fs from 'node:fs';

const options = {
// Necessary only if the server requires client certificate authentication.
key: fs.readFileSync('client-key.pem'),
cert: fs.readFileSync('client-cert.pem'),

// Necessary only if the server uses a self-signed certificate.
ca: [ fs.readFileSync('server-cert.pem') ],

// Necessary only if the server's cert isn't for "localhost".
checkServerIdentity: () => { return null; },
};

const socket = tls.connect(8000, options, () => {
console.log('client connected',
socket.authorized ? 'authorized' : 'unauthorized');
process.stdin.pipe(socket);
process.stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
console.log(data);
});
socket.on('end', () => {
console.log('server ends connection');
});

@since v0.11.3

The callback function, if specified, will be added as a listener for the 'secureConnect' event.

tls.connect() returns a TLSSocket object.

Unlike the https API, tls.connect() does not enable the SNI (Server Name Indication) extension by default, which may cause some servers to return an incorrect certificate or reject the connection altogether. To enable SNI, set the servername option in addition to host.

The following illustrates a client for the echo server example from createServer:

// Assumes an echo server that is listening on port 8000.
import tls from 'node:tls';
import fs from 'node:fs';

const options = {
// Necessary only if the server requires client certificate authentication.
key: fs.readFileSync('client-key.pem'),
cert: fs.readFileSync('client-cert.pem'),

// Necessary only if the server uses a self-signed certificate.
ca: [ fs.readFileSync('server-cert.pem') ],

// Necessary only if the server's cert isn't for "localhost".
checkServerIdentity: () => { return null; },
};

const socket = tls.connect(8000, options, () => {
console.log('client connected',
socket.authorized ? 'authorized' : 'unauthorized');
process.stdin.pipe(socket);
process.stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
console.log(data);
});
socket.on('end', () => {
console.log('server ends connection');
});

@since v0.11.3

{@link createServer} sets the default value of the honorCipherOrder option to true, other APIs that create secure contexts leave it unset.

{@link createServer} uses a 128 bit truncated SHA1 hash value generated from process.argv as the default value of the sessionIdContext option, other APIs that create secure contexts have no default value.

The tls.createSecureContext() method creates a SecureContext object. It is usable as an argument to several tls APIs, such as server.addContext(), but has no public methods. The Server constructor and the createServer method do not support the secureContext option.

A key is required for ciphers that use certificates. Either key or pfx can be used to provide it.

If the ca option is not given, then Node.js will default to using Mozilla's publicly trusted list of CAs.

Custom DHE parameters are discouraged in favor of the new dhparam: 'auto' option. When set to 'auto', well-known DHE parameters of sufficient strength will be selected automatically. Otherwise, if necessary, openssl dhparam can be used to create custom parameters. The key length must be greater than or equal to 1024 bits or else an error will be thrown. Although 1024 bits is permissible, use 2048 bits or larger for stronger security.

@since v0.11.13

Creates a new secure pair object with two streams, one of which reads and writes the encrypted data and the other of which reads and writes the cleartext data. Generally, the encrypted stream is piped to/from an incoming encrypted data stream and the cleartext one is used as a replacement for the initial encrypted stream.

tls.createSecurePair() returns a tls.SecurePair object with cleartext and encrypted stream properties.

Using cleartext has the same API as TLSSocket.

The tls.createSecurePair() method is now deprecated in favor oftls.TLSSocket(). For example, the code:

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

can be replaced by:

secureSocket = tls.TLSSocket(socket, options);

where secureSocket has the same API as pair.cleartext.

@since v0.3.2

Creates a new Server. The secureConnectionListener, if provided, is automatically set as a listener for the 'secureConnection' event.

The ticketKeys options is automatically shared between node:cluster module workers.

The following illustrates a simple echo server:

import tls from 'node:tls';
import fs from 'node:fs';

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

// This is necessary only if using client certificate authentication.
requestCert: true,

// This is necessary only if the client uses a self-signed certificate.
ca: [ fs.readFileSync('client-cert.pem') ],
};

const server = tls.createServer(options, (socket) => {
console.log('server connected',
socket.authorized ? 'authorized' : 'unauthorized');
socket.write('welcome!\n');
socket.setEncoding('utf8');
socket.pipe(socket);
});
server.listen(8000, () => {
console.log('server bound');
});

The server can be tested by connecting to it using the example client from connect.

@since v0.3.2

Creates a new Server. The secureConnectionListener, if provided, is automatically set as a listener for the 'secureConnection' event.

The ticketKeys options is automatically shared between node:cluster module workers.

The following illustrates a simple echo server:

import tls from 'node:tls';
import fs from 'node:fs';

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

// This is necessary only if using client certificate authentication.
requestCert: true,

// This is necessary only if the client uses a self-signed certificate.
ca: [ fs.readFileSync('client-cert.pem') ],
};

const server = tls.createServer(options, (socket) => {
console.log('server connected',
socket.authorized ? 'authorized' : 'unauthorized');
socket.write('welcome!\n');
socket.setEncoding('utf8');
socket.pipe(socket);
});
server.listen(8000, () => {
console.log('server bound');
});

The server can be tested by connecting to it using the example client from connect.

@since v0.3.2

Returns an array containing the CA certificates from various sources, depending on type:

• "default": return the CA certificates that will be used by the Node.js TLS clients by default.
• When --use-bundled-ca is enabled (default), or --use-openssl-ca is not enabled, this would include CA certificates from the bundled Mozilla CA store.
• When --use-system-ca is enabled, this would also include certificates from the system's trusted store.
• When NODE_EXTRA_CA_CERTS is used, this would also include certificates loaded from the specified file.
• "system": return the CA certificates that are loaded from the system's trusted store, according to rules set by --use-system-ca. This can be used to get the certificates from the system when --use-system-ca is not enabled.
• "bundled": return the CA certificates from the bundled Mozilla CA store. This would be the same as tls.rootCertificates.
• "extra": return the CA certificates loaded from NODE_EXTRA_CA_CERTS. It's an empty array if NODE_EXTRA_CA_CERTS is not set.

@since v22.15.0

Returns. An array of PEM-encoded certificates. The array may contain duplicates if the same certificate is repeatedly stored in multiple sources.

Returns an array with the names of the supported TLS ciphers. The names are lower-case for historical reasons, but must be uppercased to be used in the ciphers option of {@link createSecureContext}.

Not all supported ciphers are enabled by default. See Modifying the default TLS cipher suite.

Cipher names that start with 'tls_' are for TLSv1.3, all the others are for TLSv1.2 and below.

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

@since v0.10.2

Sets the default CA certificates used by Node.js TLS clients. If the provided certificates are parsed successfully, they will become the default CA certificate list returned by getCACertificates and used by subsequent TLS connections that don't specify their own CA certificates. The certificates will be deduplicated before being set as the default.

This function only affects the current Node.js thread. Previous sessions cached by the HTTPS agent won't be affected by this change, so this method should be called before any unwanted cachable TLS connections are made.

To use system CA certificates as the default:

import tls from 'node:tls';
tls.setDefaultCACertificates(tls.getCACertificates('system'));

This function completely replaces the default CA certificate list. To add additional certificates to the existing defaults, get the current certificates and append to them:

import tls from 'node:tls';
const currentCerts = tls.getCACertificates('default');
const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);

@since v22.19.0