目录

• tls（安全传输层）
  • TLS/SSL 概念
    • 完全前向保密
    • ALPN 和 SNI
    • 预共享的密钥
    • 客户端发起的重协商攻击缓解
    • 会话恢复
      • 会话标识符
      • 会话票证
  • 修改默认的 TLS 加密组件
  • tls.CryptoStream 类
    • cryptoStream.bytesWritten
  • tls.SecurePair 类
    • 'secure' 事件
  • tls.Server 类
    • 'connection' 事件
    • 'keylog' 事件
    • 'newSession' 事件
    • 'OCSPRequest' 事件
    • 'resumeSession' 事件
    • 'secureConnection' 事件
    • 'tlsClientError' 事件
    • server.addContext(hostname, context)
    • server.address()
    • server.close([callback])
    • server.connections
    • server.getTicketKeys()
    • server.listen()
    • server.setSecureContext(options)
    • server.setTicketKeys(keys)
  • tls.TLSSocket 类
    • new tls.TLSSocket(socket[, options])
    • 'keylog' 事件
    • 'OCSPResponse' 事件
    • 'secureConnect' 事件
    • 'session' 事件
    • tlsSocket.address()
    • tlsSocket.authorizationError
    • tlsSocket.authorized
    • tlsSocket.disableRenegotiation()
    • tlsSocket.enableTrace()
    • tlsSocket.encrypted
    • tlsSocket.getCertificate()
    • tlsSocket.getCipher()
    • tlsSocket.getEphemeralKeyInfo()
    • tlsSocket.getFinished()
    • tlsSocket.getPeerCertificate([detailed])
      • 证书对象
    • tlsSocket.getPeerFinished()
    • tlsSocket.getProtocol()
    • tlsSocket.getSession()
    • tlsSocket.getSharedSigalgs()
    • tlsSocket.exportKeyingMaterial(length, label[, context])
    • 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.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])
  • tls.createServer([options][, secureConnectionListener])
  • tls.getCiphers()
  • tls.rootCertificates
  • tls.DEFAULT_ECDH_CURVE
  • tls.DEFAULT_MAX_VERSION
  • tls.DEFAULT_MIN_VERSION

tls（安全传输层）#

源代码: lib/tls.js

tls 模块是对安全传输层（TLS）及安全套接层（SSL）协议的实现，建立在OpenSSL的基础上。 按如下方式引用此模块:

const tls = require('tls');

TLS/SSL 概念#

TLS/SSL 是公共/私人的密钥基础设施（PKI）。 大部分情况下，每个服务器和客户端都应该有一个私钥。

私钥能有多种生成方式，下面举一个例子。 用 OpenSSL 的命令行来生成一个 2048 位的 RSA 私钥：

openssl genrsa -out ryans-key.pem 2048

通过 TLS/SSL，所有的服务器（和一些客户端）必须要一个证书。 证书是相似于私钥的公钥,它由 CA 或者私钥拥有者数字签名，特别地，私钥拥有者所签名的被称为自签名。 获取证书的第一步是生成一个证书申请文件（CSR)。

用 OpenSSL 能生成一个私钥的 CSR 文件：

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

CSR 文件被生成以后，它既能被 CA 签名也能被用户自签名。 用 OpenSSL 生成一个自签名证书的命令如下：

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

证书被生成以后，它又能用来生成一个 .pfx 或者 .p12 文件：

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

命令行参数:

• in: 被签名的证书。
• inkey: 有关的私钥。
• certfile: 签入文件的证书串，比如： cat ca1-cert.pem ca2-cert.pem > ca-cert.pem。

完全前向保密#

术语“前向保密”或“完全前向保密”是一种密钥协商（或称做密钥交换）方法。 通过这种方法,客户端与服务端在当前会话中，协商一个临时生成的密钥进行对称加密的密钥交换。 这意味着即使服务器端私钥发生泄漏，窃密者与攻击者也无法解密通信内容，除非他们能得到当前会话的临时密钥。

TLS/SSL 握手时，使用完全前向即每次会话都会随机生成一个临时密钥对用于对称加密密钥协商(区别于每次会话都是用相同的密钥)。 实现这个技术的密钥交换算法称为“ephemeral”。

当前最常用的两种实现完全前向保密的算法（注意算法结尾的"E"）：

• DHE - 使用临时密钥的 Diffie-Hellman 密钥交换算法。
• ECDHE - 使用临时密钥的椭圆曲线 Diffie-Hellman 密钥交换算法。

使用临时密钥会带来性能损失，因为密钥生成的过程十分消耗 CPU 计算性能。

如需使用完全前向加密，例如使用 tls 模块的 DHE 算法，使用之前需要生成一个 Diffie-Hellman 参数并将其用 dhparam 声明在 tls.createSecureContext() 中。 如下例子展示了如何使用 OpenSSL 命令生成参数：

openssl dhparam -outform PEM -out dhparam.pem 2048

如需使用 ECDHE 算法，则不需要生成 Diffie-Hellman 参数，因为可以使用默认的 ECDHE 曲线。 在创建 TLS Server 时，可使用 ecdhCurve 属性声明服务器支持的曲线名词，详请参见 tls.createServer()。

完全前向保密在 TLSv1.2 之前是可选的，但它不是 TLSv1.3 的可选项，因为所有 TLSv1.3 密码套件都使用 ECDHE。

ALPN 和 SNI#

ALPN（Application-Layer Protocol Negotiation Extension，应用层协议协商扩展）和SNI（Server Name Indication，服务器名称指示）是 TLS 的握手扩展：

• ALPN：允许将一个 TLS 服务器用于多种协议（HTTP、HTTP/2）。
• SNI：允许将一个 TLS 服务器用于具有不同 SSL 证书的多个主机名。

预共享的密钥#

TLS-PSK(Pre-Shared-Key:预共享密钥)是一种身份认证方式，有别于普通的基于证书认证的身份认证， TLS握手中，PSK使用预共享密钥来代替证书认证，提供多样化的认证手段。TLS-PSK和PKI（公钥基础设施） 不是互斥的，客户端和服务器端在密钥套件的协商过程中，可以共用两种或者使用其中一种方式来完成协商。

仅当通信双方有安全的密钥共享信道时，才考虑使用TLS-PSK来进行身份认证。基于这个原因，PSK 不会替换PKI在TLS中的重要用途。近年来，在OpenSSL的实现中发现了许多TLS-PSK的安全缺陷，因为 它仅仅在少数的应用中使用，所以，在使用PSK密钥套件前，请充分考虑替代方案。在RFC 4086 中讨论了生成PSK过程中，充分无序的密钥是非常重要的，从固定密码和低无序性源中获取预共享密钥 是不安全的。

默认情况下，PSK相关的密钥套件是被禁用的，如果需要使用基于TLS-PSK密钥套件，需要使用ciphers参数显式声明。 使用openssl ciphers -v 'PSK'可以查询到所有可用的基于PSK密钥套件。所有TLS 1.3协议支持的密钥套件均是 合法的PSK密钥套件，但当前仅支持SHA256摘要算法的套件，可以通过openssl ciphers -v -s -tls1_3 -psk 查询符合要求的密钥套件。

根据RFC 4279，PSK标识符最大长度应大于128bytes，PSK密钥最大长度应大于64bytes。 在OpenSSL 1.1.0版本中，最大PSK标识符长度为128byte，最大PSK密钥长度为256btyes。

因为底层OpenSSL API的限制，当前的实现不支持异步PSK回调。

客户端发起的重协商攻击缓解#

TLS 协议允许客户端在 TLS 会话中进行重协商，用于安全因素的考量。 不幸的是，会话重协商需要消耗大量的服务器端资源，这将导致服务器存在潜在的被 DDoS 攻击的可能。

为了减轻这个风险，限制每十分钟只能使用三次重协商，超过这个限制将会在 tls.TLSSocket 实例中产生一个 error 事件。 这个限制是可配置的:

• tls.CLIENT_RENEG_LIMIT <number> 指定重协商请求的次数限制，默认为 3。
• tls.CLIENT_RENEG_WINDOW <number> 指定限制次数的生效时间段，默认为 600（10 分钟）。

不应在未充分理解其含义与影响的情况下修改上述参数。

TLSv1.3 不支持重协商。

会话恢复#

建立一个TLS会话是比较耗时的，会话复用通过保存会话和复用会话状态加快TLS会话建立过程。 这里讨论老的（Session ID会话复用）和新的（Session Ticket会话复用，当前推荐的） 两种会话复用机制。

会话标识符#

服务器在与客户端新建连接的时候生成一个唯一的Session ID发送给客户端，客户端与服务器均保存这个 会话的状态。当需要重新建立SSL会话时，客户端发送保存的ID和会话状态给服务器，如果服务器 也有这个ID的会话状态，则可以复用这个ID的会话信息，否则就会创建新的会话。祥见RFC 2246 第23-30页。

绝大多数浏览器支持在HTTPS中使用Session ID会话复用技术来恢复已有会话。

在Node.js中，客户端通过等待 'session'事件来获取会话信息，并提供tls.connect()中的 session选项来复用会话。服务器必须实现'newSession'和'resumeSession'事件的 hander，并使用会话ID作为查找的key来保存和恢复会话信息。在负载均衡和集群下，想要复用会话需要使用 类似Redis的共享缓存机制来存储会话信息。

会话票证#

服务器加密整个会话状态，并将其发送给客户端，被称为“票据（ticket）”。当需要复用会话时，客户端 在握手阶段将ticket发送给服务器。这种机制的优点是服务器端不需要缓存会话状态。如果基于任何 原因（包括解密ticket内容失败，ticket信息超时等情况），服务器不使用ticket，则会新建一个会话，并 发送新的ticket给客户端，详见RFC 5077。

基于tickets的会话复用方式正在被越来越多的主流浏览器支持。

在Node.js中，客户端的两种会话复用使用相同的API。在调试时，如果tls.TLSSocket.getTLSTicket() 返回了会话信息，并且会话信息中包含ticket，则使用了Session Ticket会话复用， 否则使用了Session ID会话复用。

在TLS1.3中，需要注意服务器可能会发送多个ticket，这会触发多个'session'事件，详见'session' 事件中的介绍。

单个服务器使用session ticket会话复用不需要特别的实现，但如果需要在服务器重启后或者在使用 负载均衡的情况下，任然能够复用成功，则所有服务器必须要使用相同的密钥来生成ticket。这个密钥 由三个16字节的密钥组成，但在API实现中，为了方便使用了一个48字节的缓存保存。

服务器实例使用server.getTicketKeys()可以获取ticket密钥，并将其分发给其他服务器。 但出于安全考虑，最好是生成48字节随机的数据并通过tls.createServer()的ticketKeys 参数来设置。密钥最好定时重新生成并通过server.setTicketKeys()在服务器中更新。

Session ticket是TLS协商过程的加密密钥之一，因此ticket必须安全的存储。在TLS1.2及TLS1.2以下版本， 如果为了妥协而使用相同的ticket加密所有会话，则最好不要将ticket存储在磁盘上，并且应该定期更新ticket的生成密钥。

如果客户端支持ticket，则服务器会在TLS协商过程中发送。如果服务器端需要禁用ticket，需要在 secureOptions提供require('constants').SSL_OP_NO_TICKET来禁用。

Session ID和session ticket会话复用都有超时，超时后服务器将创建新的会话。可以通过tls.createServer() 的sessionTimeout来设置超时时间。

对上述所有机制，当会话复用失败时，服务器会创建一个新的会话，这不会导致TLS/HTTPS连接失败，因为TLS性能的影响，这显然不需要通知到TLS/HTTPS连接层面。 在Openssl命令行中，可以通过如下方式验证服务器是否支持会话复用。可以使用openssl s_client的-reconnect参数, 例如：

$ openssl s_client -connect localhost:443 -reconnect

查看调试输出，第一条连接应该包括一个"New"字段，例如：

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

接下来的连接应该包括"Reused"字段，例如：

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

修改默认的 TLS 加密组件#

Node.js 构造时包含了默认的 TLS 开启和关闭的加密套件。在构建自己的Node.js分发版本时， 可以配置默认支持的加密套件列表。

下表中的命令可以查看默认的加密套件：

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

默认加密组件可以使用 --tls-cipher-list 命令进行替换（直接或通过 NODE_OPTIONS 环境变量）。 比如，生成 ECDHE-RSA-AES128-GCM-SHA256:!RC4 的 TLS 加密组件：

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

默认的加密组件也可以通过客户端或者服务器的 tls.createSecureContext() 方法的 ciphers 选项来进行替换，tls.createServer() 方法和 tls.connect() 方法也可以使用 ciphers 选项进行设置，当然也可以在创建一个 tls.TLSSocket 时设置。

密码列表可以包含 TLSv1.3 密码套件名称的混合，以 'TLS_' 开头的密码，以及 TLSv1.2 及以下密码套件的规范。 TLSv1.2 密码支持传统规范格式，有关详细信息，请参见 OpenSSL 密码列表格式文档，但这些规范不适用于 TLSv1.3 密码。 只能通过在密码列表中包含其全名来启用 TLSv1.3 套件。 例如，它们不能通过使用传统的 TLSv1.2 'EECDH'或 '!EECDH' 规范来启用或禁用。

尽管 TLSv1.3 和 TLSv1.2 密码套件的相对顺序，TLSv1.3 协议明显比 TLSv1.2 更安全，并且如果握手表明它受支持，并且如果有任何 TLSv1.3 密码套件已启用，将始终选择 TLSv1.2 以上。

Node.js 包含的默认的加密组件是经过精心挑选，能体现目前最好的安全实践和最低风险。 改变默认的加密组件可以对应用的安全性有重大的影响。 --tls-cipher-list 开关和 ciphers 选项应该只在必要的时候使用。

默认加密组件倾向使用 GCM 加密作为 Chrome 现代加密设置的选项，也倾向使用 ECDHE 和 DHE 加密算法实现完美的前向安全，同时向后兼容。

依据特殊攻击影响更大位数的 AES 密钥，128 位的 AES 密钥优先于 192 位和 256 位的 AES 密钥。

老的客户端依赖不安全的 RC4 或者基于 DES 的加密（比如 IE6）不能用默认配置完成握手的过程。 如果必须支持这些客户端，TLS 推荐规范也许可以提供兼容的加密组件。 欲知更多的格式的细节请参见 OpenSSL 加密列表格式文档。

只有 5 种 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'

默认情况下启用前 3 个。 TLSv1.3 支持最后 2 个基于 CCM 的套件，因为它们在受约束的系统上可能有更好的性能，但默认情况下它们不会启用，因为它们提供的安全性较低。

tls.CryptoStream 类#

The tls.CryptoStream class represents a stream of encrypted data. This class is deprecated and should no longer be used.

cryptoStream.bytesWritten#

The cryptoStream.bytesWritten property returns the total number of bytes written to the underlying socket including the bytes required for the implementation of the TLS protocol.

tls.SecurePair 类#

Returned by tls.createSecurePair().

'secure' 事件#

The 'secure' event is emitted by the SecurePair object once a secure connection has been established.

As with checking for the server 'secureConnection' event, pair.cleartext.authorized should be inspected to confirm whether the certificate used is properly authorized.

tls.Server 类#

• 继承自: <net.Server>

接受使用 TLS 或 SSL 的加密连接。

'connection' 事件#

• socket <stream.Duplex>

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. 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.

'keylog' 事件#

• line <Buffer> Line of ASCII text, in NSS SSLKEYLOGFILE format.
• tlsSocket <tls.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);
});

'newSession' 事件#

'newSession' 事件在创建一个新的 TLS 会话时触发。 这可能用于在外部存储保存会话。 数据会被提供给 'resumeSession' 回调。

监听器回调被调用时传入三个参数：

• sessionId <Buffer> TLS 会话识别符。
• sessionData <Buffer> TLS 会话数据。
• callback <Function> 在安全连接时为了发送或者接收数据，无参的回调函数必须被调用。

添加监听器后，监听器只在连接建立后生效。

'OCSPRequest' 事件#

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

• certificate <Buffer> The server certificate
• issuer <Buffer> The issuer's certificate
• callback <Function> 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.

'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 <Buffer> The TLS session identifier
• callback <Function> A callback function to be called when the prior session has been recovered: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

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

'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 <tls.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.

'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 <Error> The Error object describing the error
• tlsSocket <tls.TLSSocket> The tls.TLSSocket instance from which the error originated.

server.addContext(hostname, context)#

• hostname <string> A SNI host name or wildcard (e.g. '*')
• context <Object> An object containing any of the possible properties from the tls.createSecureContext() options arguments (e.g. key, cert, ca, etc).

The server.addContext() method adds a secure context that will be used if the client request's SNI name matches the supplied hostname (or wildcard).

server.address()#

• Returns: <Object>

Returns the bound address, the address family name, and port of the server as reported by the operating system. See net.Server.address() for more information.

server.close([callback])#

• callback <Function> A listener callback that will be registered to listen for the server instance's 'close' event.
• Returns: <tls.Server>

The server.close() method stops the server from accepting new connections.

This function operates asynchronously. The 'close' event will be emitted when the server has no more open connections.

server.connections#

• <number>

Returns the current number of concurrent connections on the server.

server.getTicketKeys()#

• Returns: <Buffer> A 48-byte buffer containing the session ticket keys.

Returns the session ticket keys.

See Session Resumption for more information.

server.listen()#

Starts the server listening for encrypted connections. This method is identical to server.listen() from net.Server.

server.setSecureContext(options)#

• options <Object> An object containing any of the possible properties from the tls.createSecureContext() options arguments (e.g. key, cert, ca, etc).

The server.setSecureContext() method replaces the secure context of an existing server. Existing connections to the server are not interrupted.

server.setTicketKeys(keys)#

• keys <Buffer> A 48-byte buffer containing the session ticket keys.

Sets the session ticket keys.

Changes to the ticket keys are effective only for future server connections. Existing or currently pending server connections will use the previous keys.

See Session Resumption for more information.

tls.TLSSocket 类#

• 继承自: <net.Socket>

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. tls.TLSSocket.getPeerCertificate() will only return data while the connection is open.

new tls.TLSSocket(socket[, options])#

• socket <net.Socket> | <stream.Duplex> On the server side, any Duplex stream. On the client side, any instance of net.Socket (for generic Duplex stream support on the client side, tls.connect() must be used).
• options <Object>
  • enableTrace: See tls.createServer()
  • isServer: The SSL/TLS protocol is asymmetrical, TLSSockets must know if they are to behave as a server or a client. If true the TLS socket will be instantiated as a server. Default: false.
  • server <net.Server> A net.Server instance.
  • requestCert: Whether to authenticate the remote peer by requesting a certificate. Clients always request a server certificate. Servers (isServer is true) may set requestCert to true to request a client certificate.
  • rejectUnauthorized: See tls.createServer()
  • ALPNProtocols: See tls.createServer()
  • SNICallback: See tls.createServer()
  • session <Buffer> A Buffer instance containing a TLS session.
  • requestOCSP <boolean> If true, specifies that the OCSP status request extension will be added to the client hello and an 'OCSPResponse' event will be emitted on the socket before establishing a secure communication
  • secureContext: TLS context object created with tls.createSecureContext(). If a secureContext is not provided, one will be created by passing the entire options object to tls.createSecureContext().
  • ...: tls.createSecureContext() options that are used if the secureContext option is missing. Otherwise, they are ignored.

Construct a new tls.TLSSocket object from an existing TCP socket.

'keylog' 事件#

• line <Buffer> Line of ASCII text, in NSS SSLKEYLOGFILE format.

The keylog event is emitted on a tls.TLSSocket when key material is generated or received by the socket. This keying material can be stored for debugging, as it allows captured TLS traffic to be decrypted. It may be emitted multiple times, before or after the handshake completes.

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' });
// ...
tlsSocket.on('keylog', (line) => logFile.write(line));

'OCSPResponse' 事件#

The 'OCSPResponse' event is emitted if the requestOCSP option was set when the tls.TLSSocket was created and an OCSP response has been received. The listener callback is passed a single argument when called:

• response <Buffer> The server's OCSP response

Typically, the response is a digitally signed object from the server's CA that contains information about server's certificate revocation status.

'secureConnect' 事件#

The 'secureConnect' event is emitted after the handshaking process for a new connection has successfully completed. The listener callback will be called regardless of whether or not the server's certificate has been authorized. It is the client's responsibility to check the tlsSocket.authorized property to determine if the server certificate was signed by one of the specified CAs. If tlsSocket.authorized === false, then the error can be found by examining the tlsSocket.authorizationError property. If ALPN was used, the tlsSocket.alpnProtocol property can be checked to determine the negotiated protocol.

'session' 事件#

• session <Buffer>

The 'session' event is emitted on a client tls.TLSSocket when a new session or TLS ticket is available. This may or may not be before the handshake is complete, depending on the TLS protocol version that was negotiated. The event is not emitted on the server, or if a new session was not created, for example, when the connection was resumed. For some TLS protocol versions the event may be emitted multiple times, in which case all the sessions can be used for resumption.

On the client, the session can be provided to the session option of tls.connect() to resume the connection.

See Session Resumption for more information.

For TLSv1.2 and below, tls.TLSSocket.getSession() can be called once the handshake is complete. For TLSv1.3, only ticket-based resumption is allowed by the protocol, multiple tickets are sent, and the tickets aren't sent until after the handshake completes. So it is necessary to wait for the 'session' event to get a resumable session. Applications should use the 'session' event instead of getSession() to ensure they will work for all TLS versions. Applications that only expect to get or use one session should listen for this event only once:

tlsSocket.once('session', (session) => {
  // The session can be used immediately or later.
  tls.connect({
    session: session,
    // Other connect options...
  });
});

tlsSocket.address()#

• Returns: <Object>

Returns the bound address, the address family name, and port of the underlying socket as reported by the operating system: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError#

Returns the reason why the peer's certificate was not been verified. This property is set only when tlsSocket.authorized === false.

tlsSocket.authorized#

• Returns: <boolean>

Returns true if the peer certificate was signed by one of the CAs specified when creating the tls.TLSSocket instance, otherwise false.

tlsSocket.disableRenegotiation()#

Disables TLS renegotiation for this TLSSocket instance. Once called, attempts to renegotiate will trigger an 'error' event on the TLSSocket.

tlsSocket.enableTrace()#

When enabled, TLS packet trace information is written to stderr. This can be used to debug TLS connection problems.

Note: The format of the output is identical to the output of openssl s_client -trace or openssl s_server -trace. While it is produced by OpenSSL's SSL_trace() function, the format is undocumented, can change without notice, and should not be relied on.

tlsSocket.encrypted#

Always returns true. This may be used to distinguish TLS sockets from regular net.Socket instances.

tlsSocket.getCertificate()#

• Returns: <Object>

Returns an object representing the local certificate. The returned object has some properties corresponding to the fields of the certificate.

See tls.TLSSocket.getPeerCertificate() for an example of the certificate structure.

If there is no local certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

tlsSocket.getCipher()#

• Returns: <Object>
  • name <string> OpenSSL name for the cipher suite.
  • standardName <string> IETF name for the cipher suite.
  • version <string> The minimum TLS protocol version supported by this cipher suite.

Returns an object containing information on the negotiated cipher suite.

For example:

{
    "name": "AES128-SHA256",
    "standardName": "TLS_RSA_WITH_AES_128_CBC_SHA256",
    "version": "TLSv1.2"
}

See SSL_CIPHER_get_name for more information.

tlsSocket.getEphemeralKeyInfo()#

• Returns: <Object>

Returns an object representing the type, name, and size of parameter of an ephemeral key exchange in perfect forward secrecy on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; null is returned if called on a server socket. The supported types are 'DH' and 'ECDH'. The name property is available only when type is 'ECDH'.

For example: { type: 'ECDH', name: 'prime256v1', size: 256 }.

tlsSocket.getFinished()#

• Returns: <Buffer> | <undefined> The latest Finished message that has been sent to the socket as part of a SSL/TLS handshake, or undefined if no Finished message has been sent yet.

As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

Corresponds to the SSL_get_finished routine in OpenSSL and may be used to implement the tls-unique channel binding from RFC 5929.

tlsSocket.getPeerCertificate([detailed])#

• detailed <boolean> Include the full certificate chain if true, otherwise include just the peer's certificate.
• Returns: <Object> A certificate object.

Returns an object representing the peer's certificate. If the peer does not provide a certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

If the full certificate chain was requested, each certificate will include an issuerCertificate property containing an object representing its issuer's certificate.

证书对象#

A certificate object has properties corresponding to the fields of the certificate.

• raw <Buffer> The DER encoded X.509 certificate data.
• subject <Object> The certificate subject, described in terms of Country (C:), StateOrProvince (ST), Locality (L), Organization (O), OrganizationalUnit (OU), and CommonName (CN). The CommonName is typically a DNS name with TLS certificates. Example: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> The certificate issuer, described in the same terms as the subject.
• valid_from <string> The date-time the certificate is valid from.
• valid_to <string> The date-time the certificate is valid to.
• serialNumber <string> The certificate serial number, as a hex string. Example: 'B9B0D332A1AA5635'.
• fingerprint <string> The SHA-1 digest of the DER encoded certificate. It is returned as a : separated hexadecimal string. Example: '2A:7A:C2:DD:...'.
• fingerprint256 <string> The SHA-256 digest of the DER encoded certificate. It is returned as a : separated hexadecimal string. Example: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (Optional) The extended key usage, a set of OIDs.
• subjectaltname <string> (Optional) A string containing concatenated names for the subject, an alternative to the subject names.
• infoAccess <Array> (Optional) An array describing the AuthorityInfoAccess, used with OCSP.
• issuerCertificate <Object> (Optional) The issuer certificate object. For self-signed certificates, this may be a circular reference.

The certificate may contain information about the public key, depending on the key type.

For RSA keys, the following properties may be defined:

• bits <number> The RSA bit size. Example: 1024.
• exponent <string> The RSA exponent, as a string in hexadecimal number notation. Example: '0x010001'.
• modulus <string> The RSA modulus, as a hexadecimal string. Example: 'B56CE45CB7...'.
• pubkey <Buffer> The public key.

For EC keys, the following properties may be defined:

• pubkey <Buffer> The public key.
• bits <number> The key size in bits. Example: 256.
• asn1Curve <string> (Optional) The ASN.1 name of the OID of the elliptic curve. Well-known curves are identified by an OID. While it is unusual, it is possible that the curve is identified by its mathematical properties, in which case it will not have an OID. Example: 'prime256v1'.
• nistCurve <string> (Optional) The NIST name for the elliptic curve, if it has one (not all well-known curves have been assigned names by NIST). Example: 'P-256'.

Example certificate:

{ 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',
  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()#

• Returns: <Buffer> | <undefined> The latest Finished message that is expected or has actually been received from the socket as part of a SSL/TLS handshake, or undefined if there is no Finished message so far.

As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

Corresponds to the SSL_get_peer_finished routine in OpenSSL and may be used to implement the tls-unique channel binding from RFC 5929.

tlsSocket.getProtocol()#

• Returns: <string> | <null>

Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value 'unknown' will be returned for connected sockets that have not completed the handshaking process. The value null will be returned for server sockets or disconnected client sockets.

Protocol versions are:

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

See the OpenSSL SSL_get_version documentation for more information.

tlsSocket.getSession()#

• <Buffer>

Returns the TLS session data or undefined if no session was negotiated. On the client, the data can be provided to the session option of tls.connect() to resume the connection. On the server, it may be useful for debugging.

See Session Resumption for more information.

Note: getSession() works only for TLSv1.2 and below. For TLSv1.3, applications must use the 'session' event (it also works for TLSv1.2 and below).

tlsSocket.getSharedSigalgs()#

• Returns: <Array> List of signature algorithms shared between the server and the client in the order of decreasing preference.

See SSL_get_shared_sigalgs for more information.

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

• length <number> number of bytes to retrieve from keying material

• label <string> an application specific label, typically this will be a value from the IANA Exporter Label Registry.

• context <Buffer> Optionally provide a context.

• Returns: <Buffer> requested bytes of the keying material

Keying material is used for validations to prevent different kind of attacks in network protocols, for example in the specifications of IEEE 802.1X.

Example

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

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

See the OpenSSL SSL_export_keying_material documentation for more information.

tlsSocket.getTLSTicket()#

• <Buffer>

For a client, returns the TLS session ticket if one is available, or undefined. For a server, always returns undefined.

It may be useful for debugging.

See Session Resumption for more information.

tlsSocket.isSessionReused()#

• Returns: <boolean> true if the session was reused, false otherwise.

See Session Resumption for more information.

tlsSocket.localAddress#

• <string>

Returns the string representation of the local IP address.

tlsSocket.localPort#

• <number>

Returns the numeric representation of the local port.

tlsSocket.remoteAddress#

• <string>

Returns the string representation of the remote IP address. For example, '74.125.127.100' or '2001:4860:a005::68'.

tlsSocket.remoteFamily#

• <string>

Returns the string representation of the remote IP family. 'IPv4' or 'IPv6'.

tlsSocket.remotePort#

• <number>

Returns the numeric representation of the remote port. For example, 443.

tlsSocket.renegotiate(options, callback)#

• options <Object>

  • rejectUnauthorized <boolean> If not false, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails; err.code contains the OpenSSL error code. Default: true.
  • requestCert

• callback <Function> If renegotiate() returned true, callback is attached once to the 'secure' event. If renegotiate() returned false, callback will be called in the next tick with an error, unless the tlsSocket has been destroyed, in which case callback will not be called at all.

• Returns: <boolean> true if renegotiation was initiated, false otherwise.

The tlsSocket.renegotiate() method initiates a TLS renegotiation process. Upon completion, the callback function will be passed a single argument that is either an Error (if the request failed) or null.

This method can be used to request a peer's certificate after the secure connection has been established.

When running as the server, the socket will be destroyed with an error after handshakeTimeout timeout.

For TLSv1.3, renegotiation cannot be initiated, it is not supported by the protocol.

tlsSocket.setMaxSendFragment(size)#

• size <number> The maximum TLS fragment size. The maximum value is 16384. Default: 16384.
• Returns: <boolean>

The tlsSocket.setMaxSendFragment() method sets the maximum TLS fragment size. Returns true if setting the limit succeeded; false otherwise.

Smaller fragment sizes decrease the buffering latency on the client: larger fragments are buffered by the TLS layer until the entire fragment is received and its integrity is verified; large fragments can span multiple roundtrips and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput.

tls.checkServerIdentity(hostname, cert)#

• hostname <string> The host name or IP address to verify the certificate against.
• cert <Object> A certificate object representing the peer's certificate.
• Returns: <Error> | <undefined>

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 can be overwritten by providing alternative function as part of the options.checkServerIdentity option 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).

tls.connect(options[, callback])#

• options <Object>
  • enableTrace: See tls.createServer()
  • host <string> Host the client should connect to. Default: 'localhost'.
  • port <number> Port the client should connect to.
  • path <string> Creates Unix socket connection to path. If this option is specified, host and port are ignored.
  • socket <stream.Duplex> Establish secure connection on a given socket rather than creating a new socket. Typically, this is an instance of net.Socket, but any Duplex stream is allowed. If this option is specified, path, host and port are ignored, except for certificate validation. Usually, a socket is already connected when passed to tls.connect(), but it can be connected later. Connection/disconnection/destruction of socket is the user's responsibility; calling tls.connect() will not cause net.connect() to be called.
  • allowHalfOpen <boolean> If the socket option is missing, indicates whether or not to allow the internally created socket to be half-open, otherwise the option is ignored. See the allowHalfOpen option of net.Socket for details. Default: false.
  • rejectUnauthorized <boolean> If not false, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails; err.code contains the OpenSSL error code. Default: true.
  • pskCallback <Function>
    • hint: <string> optional message sent from the server to help client decide which identity to use during negotiation. Always null if TLS 1.3 is used.
    • Returns: <Object> in the form { psk: <Buffer|TypedArray|DataView>, identity: <string> } or null to stop the negotiation process. psk must be compatible with the selected cipher's digest. identity must use UTF-8 encoding. When negotiating TLS-PSK (pre-shared keys), this function is called with optional identity hint provided by the server or null in case of TLS 1.3 where hint was removed. It will be necessary to provide a custom tls.checkServerIdentity() for the connection as the default one will try to check host name/IP of the server against the certificate but that's not applicable for PSK because there won't be a certificate present. More information can be found in the RFC 4279.
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> An array of strings, Buffers or TypedArrays or DataViews, or a single Buffer or TypedArray or DataView containing the supported ALPN protocols. Buffers should have the format [len][name][len][name]... e.g. '\x08http/1.1\x08http/1.0', where the len byte is the length of the next protocol name. Passing an array is usually much simpler, e.g. ['http/1.1', 'http/1.0']. Protocols earlier in the list have higher preference than those later.
  • servername: <string> Server name for the SNI (Server Name Indication) TLS extension. It is the name of the host being connected to, and must be a host name, and not an IP address. It can be used by a multi-homed server to choose the correct certificate to present to the client, see the SNICallback option to tls.createServer().
  • checkServerIdentity(servername, cert) <Function> A callback function to be used (instead of the builtin tls.checkServerIdentity() function) when checking the server's host name (or the provided servername when explicitly set) against the certificate. This should return an <Error> if verification fails. The method should return undefined if the servername and cert are verified.
  • session <Buffer> A Buffer instance, containing TLS session.
  • minDHSize <number> Minimum size of the DH parameter in bits to accept a TLS connection. When a server offers a DH parameter with a size less than minDHSize, the TLS connection is destroyed and an error is thrown. Default: 1024.
  • highWaterMark: <number> Consistent with the readable stream highWaterMark parameter. Default: 16 * 1024.
  • secureContext: TLS context object created with tls.createSecureContext(). If a secureContext is not provided, one will be created by passing the entire options object to tls.createSecureContext().
  • ...: tls.createSecureContext() options that are used if the secureContext option is missing, otherwise they are ignored.
  • ...: Any socket.connect() option not already listed.
• callback <Function>
• Returns: <tls.TLSSocket>

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

tls.connect() returns a tls.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 tls.createServer():

// Assumes an echo server that is listening on port 8000.
const tls = require('tls');
const fs = require('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');
});

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

• path <string> Default value for options.path.
• options <Object> See tls.connect().
• callback <Function> See tls.connect().
• Returns: <tls.TLSSocket>

Same as tls.connect() except that path can be provided as an argument instead of an option.

A path option, if specified, will take precedence over the path argument.

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

• port <number> Default value for options.port.
• host <string> Default value for options.host.
• options <Object> See tls.connect().
• callback <Function> See tls.connect().
• Returns: <tls.TLSSocket>

Same as tls.connect() except that port and host can be provided as arguments instead of options.

A port or host option, if specified, will take precedence over any port or host argument.

tls.createSecureContext([options])#

• options <Object>
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CAs are explicitly specified using this option. The value can be a string or Buffer, or an Array of strings and/or Buffers. Any string or Buffer can contain multiple PEM CAs concatenated together. The peer's certificate must be chainable to a CA trusted by the server for the connection to be authenticated. When using certificates that are not chainable to a well-known CA, the certificate's CA must be explicitly specified as a trusted or the connection will fail to authenticate. If the peer uses a certificate that doesn't match or chain to one of the default CAs, use the ca option to provide a CA certificate that the peer's certificate can match or chain to. For self-signed certificates, the certificate is its own CA, and must be provided. For PEM encoded certificates, supported types are "TRUSTED CERTIFICATE", "X509 CERTIFICATE", and "CERTIFICATE". See also tls.rootCertificates.
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> Cert chains in PEM format. One cert chain should be provided per private key. Each cert chain should consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, see ca). When providing multiple cert chains, they do not have to be in the same order as their private keys in key. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.
  • sigalgs <string> Colon-separated list of supported signature algorithms. The list can contain digest algorithms (SHA256, MD5 etc.), public key algorithms (RSA-PSS, ECDSA etc.), combination of both (e.g 'RSA+SHA384') or TLS v1.3 scheme names (e.g. rsa_pss_pss_sha512). See OpenSSL man pages for more info.
  • ciphers <string> Cipher suite specification, replacing the default. For more information, see modifying the default cipher suite. Permitted ciphers can be obtained via tls.getCiphers(). Cipher names must be uppercased in order for OpenSSL to accept them.
  • clientCertEngine <string> Name of an OpenSSL engine which can provide the client certificate.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> PEM formatted CRLs (Certificate Revocation Lists).
  • dhparam <string> | <Buffer> Diffie-Hellman parameters, required for perfect forward secrecy. Use openssl dhparam to create the 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. If omitted or invalid, the parameters are silently discarded and DHE ciphers will not be available.
  • ecdhCurve <string> A string describing a named curve or a colon separated list of curve NIDs or names, for example P-521:P-384:P-256, to use for ECDH key agreement. Set to auto to select the curve automatically. Use crypto.getCurves() to obtain a list of available curve names. On recent releases, openssl ecparam -list_curves will also display the name and description of each available elliptic curve. Default: tls.DEFAULT_ECDH_CURVE.
  • honorCipherOrder <boolean> Attempt to use the server's cipher suite preferences instead of the client's. When true, causes SSL_OP_CIPHER_SERVER_PREFERENCE to be set in secureOptions, see OpenSSL Options for more information.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with options.passphrase. Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form {pem: <string|buffer>[, passphrase: <string>]}. The object form can only occur in an array. object.passphrase is optional. Encrypted keys will be decrypted with object.passphrase if provided, or options.passphrase if it is not.
  • privateKeyEngine <string> Name of an OpenSSL engine to get private key from. Should be used together with privateKeyIdentifier.
  • privateKeyIdentifier <string> Identifier of a private key managed by an OpenSSL engine. Should be used together with privateKeyEngine. Should not be set together with key, because both options define a private key in different ways.
  • maxVersion <string> Optionally set the maximum TLS version to allow. One of 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Cannot be specified along with the secureProtocol option, use one or the other. Default: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> Optionally set the minimum TLS version to allow. One of 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Cannot be specified along with the secureProtocol option, use one or the other. It is not recommended to use less than TLSv1.2, but it may be required for interoperability. Default: tls.DEFAULT_MIN_VERSION.
  • passphrase <string> Shared passphrase used for a single private key and/or a PFX.
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> PFX or PKCS12 encoded private key and certificate chain. pfx is an alternative to providing key and cert individually. PFX is usually encrypted, if it is, passphrase will be used to decrypt it. Multiple PFX can be provided either as an array of unencrypted PFX buffers, or an array of objects in the form {buf: <string|buffer>[, passphrase: <string>]}. The object form can only occur in an array. object.passphrase is optional. Encrypted PFX will be decrypted with object.passphrase if provided, or options.passphrase if it is not.
  • secureOptions <number> Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all! Value is a numeric bitmask of the SSL_OP_* options from OpenSSL Options.
  • secureProtocol <string> Legacy mechanism to select the TLS protocol version to use, it does not support independent control of the minimum and maximum version, and does not support limiting the protocol to TLSv1.3. Use minVersion and maxVersion instead. The possible values are listed as SSL_METHODS, use the function names as strings. For example, use 'TLSv1_1_method' to force TLS version 1.1, or 'TLS_method' to allow any TLS protocol version up to TLSv1.3. It is not recommended to use TLS versions less than 1.2, but it may be required for interoperability. Default: none, see minVersion.
  • sessionIdContext <string> Opaque identifier used by servers to ensure session state is not shared between applications. Unused by clients.
  • ticketKeys: <Buffer> 48-bytes of cryptographically strong pseudo-random data. See Session Resumption for more information.
  • sessionTimeout <number> The number of seconds after which a TLS session created by the server will no longer be resumable. See Session Resumption for more information. Default: 300.

tls.createServer() sets the default value of the honorCipherOrder option to true, other APIs that create secure contexts leave it unset.

tls.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 tls.createServer() and server.addContext(), but has no public methods.

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.

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

• context <Object> A secure context object as returned by tls.createSecureContext()
• isServer <boolean> true to specify that this TLS connection should be opened as a server.
• requestCert <boolean> true to specify whether a server should request a certificate from a connecting client. Only applies when isServer is true.
• rejectUnauthorized <boolean> If not false a server automatically reject clients with invalid certificates. Only applies when isServer is true.
• options
  • enableTrace: See tls.createServer()
  • secureContext: A TLS context object from tls.createSecureContext()
  • isServer: If true the TLS socket will be instantiated in server-mode. Default: false.
  • server <net.Server> A net.Server instance
  • requestCert: See tls.createServer()
  • rejectUnauthorized: See tls.createServer()
  • ALPNProtocols: See tls.createServer()
  • SNICallback: See tls.createServer()
  • session <Buffer> A Buffer instance containing a TLS session.
  • requestOCSP <boolean> If true, specifies that the OCSP status request extension will be added to the client hello and an 'OCSPResponse' event will be emitted on the socket before establishing a secure communication.

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 tls.TLSSocket.

The tls.createSecurePair() method is now deprecated in favor of tls.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.

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

• options <Object>
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> An array of strings, Buffers or TypedArrays or DataViews, or a single Buffer or TypedArray or DataView containing the supported ALPN protocols. Buffers should have the format [len][name][len][name]... e.g. 0x05hello0x05world, where the first byte is the length of the next protocol name. Passing an array is usually much simpler, e.g. ['hello', 'world']. (Protocols should be ordered by their priority.)
  • clientCertEngine <string> Name of an OpenSSL engine which can provide the client certificate.
  • enableTrace <boolean> If true, tls.TLSSocket.enableTrace() will be called on new connections. Tracing can be enabled after the secure connection is established, but this option must be used to trace the secure connection setup. Default: false.
  • handshakeTimeout <number> Abort the connection if the SSL/TLS handshake does not finish in the specified number of milliseconds. A 'tlsClientError' is emitted on the tls.Server object whenever a handshake times out. Default: 120000 (120 seconds).
  • rejectUnauthorized <boolean> If not false the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if requestCert is true. Default: true.
  • requestCert <boolean> If true the server will request a certificate from clients that connect and attempt to verify that certificate. Default: false.
  • sessionTimeout <number> The number of seconds after which a TLS session created by the server will no longer be resumable. See Session Resumption for more information. Default: 300.
  • SNICallback(servername, callback) <Function> A function that will be called if the client supports SNI TLS extension. Two arguments will be passed when called: servername and callback. callback is an error-first callback that takes two optional arguments: error and ctx. ctx, if provided, is a SecureContext instance. tls.createSecureContext() can be used to get a proper SecureContext. If callback is called with a falsy ctx argument, the default secure context of the server will be used. If SNICallback wasn't provided the default callback with high-level API will be used (see below).
  • ticketKeys: <Buffer> 48-bytes of cryptographically strong pseudo-random data. See Session Resumption for more information.
  • pskCallback <Function>
    • socket: <tls.TLSSocket> the server tls.TLSSocket instance for this connection.
    • identity: <string> identity parameter sent from the client.
    • Returns: <Buffer> | <TypedArray> | <DataView> pre-shared key that must either be a buffer or null to stop the negotiation process. Returned PSK must be compatible with the selected cipher's digest. When negotiating TLS-PSK (pre-shared keys), this function is called with the identity provided by the client. If the return value is null the negotiation process will stop and an "unknown_psk_identity" alert message will be sent to the other party. If the server wishes to hide the fact that the PSK identity was not known, the callback must provide some random data as psk to make the connection fail with "decrypt_error" before negotiation is finished. PSK ciphers are disabled by default, and using TLS-PSK thus requires explicitly specifying a cipher suite with the ciphers option. More information can be found in the RFC 4279.
  • pskIdentityHint <string> optional hint to send to a client to help with selecting the identity during TLS-PSK negotiation. Will be ignored in TLS 1.3. Upon failing to set pskIdentityHint 'tlsClientError' will be emitted with 'ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED' code.
  • ...: Any tls.createSecureContext() option can be provided. For servers, the identity options (pfx, key/cert or pskCallback) are usually required.
  • ...: Any net.createServer() option can be provided.
• secureConnectionListener <Function>
• Returns: <tls.Server>

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

The ticketKeys options is automatically shared between cluster module workers.

The following illustrates a simple echo server:

const tls = require('tls');
const fs = require('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 tls.connect().

tls.getCiphers()#

• Returns: <string[]>

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 tls.createSecureContext().

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', ...]

tls.rootCertificates#

• <string[]>

An immutable array of strings representing the root certificates (in PEM format) from the bundled Mozilla CA store as supplied by 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.

tls.DEFAULT_ECDH_CURVE#

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

tls.DEFAULT_MAX_VERSION#

• <string> The default value of the maxVersion option of tls.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.

tls.DEFAULT_MIN_VERSION#

• <string> The default value of the minVersion option of tls.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.