tls模块 翻译

tls.Server 类

继承自: <net.Server>

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

'keylog' 事件

line <Buffer> NSS SSLKEYLOGFILE格式的ASCII文本行。
tlsSocket <tls.TLSSocket> 生成它的tls.TLSSocket实例。

当与此服务器的连接生成或接收密钥材料时（通常在握手完成之前，但不一定），将发出keylog事件。可以存储此密钥材料以进行调试，因为它允许对捕获的TLS通信进行解密。每个socket可能会发出多次。

典型的用例是将接收到的行附加到公共文本文件，该文件随后由软件（例如Wireshark）用于解密流量：

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' 事件

客户端发送证书状态请求时，将发出“ OCSPRequest”事件。调用时，侦听器回调将传递三个参数：

certificate <Buffer> 服务器证书
issuer <Buffer> 发行人证书
callback <Function> 必须调用此回调函数以提供OCSP请求的结果。

可以解析服务器的当前证书以获得OCSP URL和证书ID。在获得OCSP响应之后，然后调用callback（null，resp），其中resp是包含OCSP响应的Buffer实例。证书和颁发者都是主证书和颁发者的缓冲区DER表示。这些可用于获取OCSP证书ID和OCSP端点URL。

或者，可以调用callback（null，null），指示没有OCSP响应。

调用callback（err）将导致socket.destroy（err）调用。

OCSP请求的典型流程如下：

客户端连接到服务器并发送“ OCSPRequest”（通过ClientHello中的状态信息扩展名）。

服务器收到请求并发出“ OCSPRequest”事件，如果已注册，则调用侦听器。

服务器从证书或作者提取的OCSP URL，并向CA执行OCSP请求。

服务器从CA接收“ OCSPResponse”，并通过回调参数将其发送回客户端。

客户端验证响应并销毁套接字或执行握手。

如果证书是自签名的或颁发者不在根证书列表中，则颁发者可以为null。 （建立TLS连接时，可以通过ca选项提供颁发者。）

侦听此事件仅对添加事件侦听器后建立的连接有影响。

像asn1.js这样的npm模块可以用来解析证书。

'resumeSession' 事件

当客户端请求恢复上一个TLS会话时，将发出“ resumeSession”事件。调用时，侦听器回调将传递两个参数：

sessionId <Buffer> TLS会话标识符
callback <Function> 恢复先前的会话后要调用的回调函数： callback([err[, sessionData]])

err <Error>
sessionData <Buffer>

事件侦听器应使用给定的sessionId在外部存储中查找“ newSession”事件处理程序保存的sessionData。如果找到，则调用callback（null，sessionData）以恢复会话。如果找不到，则无法恢复会话。必须在没有sessionData的情况下调用callback（），以便握手可以继续并可以创建新的会话。可以调用callback（err）终止传入的连接并销毁套接字。

 

侦听此事件仅对添加事件侦听器后建立的连接有影响。

下图说明了恢复TLS会话：

const tlsSessionStore = {};
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data;
  cb();
});
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null);
});

'secureConnection' 事件

新连接的握手过程成功完成后，将发出“ secureConnection”事件。调用时，侦听器回调将传递一个参数：

tlsSocket <tls.TLSSocket> 已建立的TLS套接字。

tlsSocket.authorized属性是一个布尔值，指示客户端是否已通过服务器提供的证书提交机构之一的验证。如果tlsSocket.authorized为false，则设置socket.authorizationError以描述授权失败的方式。根据TLS服务器的设置，未经授权的连接可能仍会被接受。

tlsSocket.alpnProtocol属性是一个包含所选ALPN协议的字符串。当ALPN没有选定的协议时，tlsSocket.alpnProtocol等于false。

tlsSocket.servername属性是一个字符串，其中包含通过SNI请求的服务器名称。

'tlsClientError' 事件

在建立安全连接之前发生错误时，将发出“ tlsClientError”事件。调用时，侦听器回调将传递两个参数：

exception <Error> 描述错误的Error对象
tlsSocket <tls.TLSSocket> 产生错误的tls.TLSSocket实例。

server.addContext(hostname, context)

hostname <string>   SNI主机名或通配符（例如'*'） 
context <Object> 包含tls.createSecureContext（）选项参数中任何可能属性的对象 (e.g. key, cert, ca, etc).

server.addContext（）方法添加一个安全上下文，如果客户端请求的SNI名称与提供的主机名（或通配符）匹配，则将使用该上下文。

server.address()

Returns: <Object>

返回操作系统报告的绑定地址，地址系列名称和服务器端口。有关更多信息，请参见net.Server.address（）。

server.close([callback])

callback <Function>将注册一个侦听器回调以侦听服务器实例的“ close”事件。
Returns: <tls.Server>

server.close（）方法停止服务器接受新连接。

此功能异步运行。服务器不再具有打开的连接时，将发出“关闭”事件。

server.getTicketKeys()

Returns: <Buffer> 一个包含会话票证密钥的48字节缓冲区。

返回会话票证密钥。

有关更多信息，请参见会话恢复。

server.listen()

启动服务器以侦听加密的连接。此方法与net.Server中的server.listen（）相同。

server.setSecureContext(options)

options <Object> 包含tls.createSecureContext（）选项参数中任何可能属性的对象(e.g. key, cert, ca, etc).

server.setSecureContext（）方法替换现有服务器的安全上下文。与服务器的现有连接不会中断。

server.setTicketKeys(keys)

keys <Buffer> 一个包含会话票证密钥的48字节缓冲区。

设置会话票证密钥。

更改票证密钥仅对以后的服务器连接有效。现有或当前挂起的服务器连接将使用以前的密钥。

有关更多信息，请参见会话恢复。

tls.TLSSocket 类

Extends: <net.Socket>

对书面数据和所有必需的TLS协商执行透明加密。

tls.TLSSocket的实例实现双工Stream接口。

返回TLS连接元数据的方法（例如tls.TLSSocket.getPeerCertificate（））仅在连接打开时返回数据。

new tls.TLSSocket(socket[, options])

socket <net.Socket> | <stream.Duplex> 在服务器端，任何双工流。在客户端，net.Socket的任何实例
(对于客户端上的通用双工流支持，必须使用tls.connect()

options <Object>

enableTrace: 看到 tls.createServer ()
isServer: SSL/TLS协议是不对称的，TLSSockets必须知道它们是作为服务器还是作为客户端。如果为真，将把TLS套接字实例化为服务器。默认值:false。
server <net.Server> A net.Server instance.
requestCert: 是否通过请求证书来认证远程对等方。客户端总是请求服务器证书。服务器（isServer为true）可以将requestCert设置为true以请求客户端证书。
rejectUnauthorized: See tls.createServer()
ALPNProtocols: See tls.createServer()
SNICallback: See tls.createServer()
session <Buffer> 包含TLS会话的Buffer实例。
requestOCSP <boolean> 如果为true，则指定将OCSP状态请求扩展名添加到客户端问候中，并在建立安全通信之前在套接字上发出“ OCSPResponse”事件
secureContext:使用tls.createSecureContext（）创建的TLS上下文对象。如果未提供secureContext，则将整个选项对象传递给tls.createSecureContext（）来创建一个。
...: tls.createSecureContext() 如果缺少secureContext选项，则使用的选项。否则，它们将被忽略。
从现有的TCP套接字构造一个新的tls.TLSSocket对象。

'keylog'事件

line <Buffer> NSS SSLKEYLOGFILE格式的ASCII文本行。

当套接字生成或接收密钥材料时，将在客户端tls.TLSSocket上发出keylog事件。可以存储此密钥材料以进行调试，因为它允许对捕获的TLS通信进行解密。在握手完成之前或之后，它可能会发出多次。

典型的用例是将接收到的行附加到公共文本文件，该文件随后由软件（例如Wireshark）用于解密流量：

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

'OCSPResponse' 事件

response <Buffer> 服务器的OCSP响应

通常，响应是来自服务器CA的经过数字签名的对象，其中包含有关服务器证书吊销状态的信息。

'secureConnect' 事件

新连接的握手过程成功完成后，将发出“ secureConnect”事件。无论服务器的证书是否已被授权，都将调用侦听器回调。客户有责任检查tlsSocket.authorized属性，以确定服务器证书是否由指定的CA之一签名。如果tlsSocket.authorized === false，则可以通过检查tlsSocket.authorizationError属性找到错误。如果使用ALPN，则可以检查tlsSocket.alpnProtocol属性以确定协商的协议。

'session' 事件

session <Buffer>

当新的会话或TLS票证可用时，在客户端tls.TLSSocket上发出“会话”事件。握手完成之前或之后，可能取决于协商的TLS协议版本。该事件不会在服务器上发出，或者例如在恢复连接时是否未创建新的会话。对于某些TLS协议版本，该事件可能会多次发出，在这种情况下，所有会话都可以用于恢复。

在客户端上，可以将会话提供给tls.connect（）的会话选项以恢复连接。

 

对于TLSv1.2及以下版本，握手完成后即可调用tls.TLSSocket.getSession（）。对于TLSv1.3，协议仅允许基于票证的恢复，发送多个票证，并且直到握手完成后才发送票证。因此，有必要等待“会话”事件获得可恢复的会话。应用程序应使用'session'事件而不是getSession（）来确保它们适用于所有TLS版本。仅希望获得或使用一个会话的应用程序应仅侦听此事件一次：

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

tlsSocket.address()

Returns: <Object>

返回操作系统报告的绑定地址，地址系列名称和基础套接字的端口{ port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError

返回未验证对等方证书的原因。仅当tlsSocket.authorized === false时才设置此属性。

tlsSocket.authorized

Returns: <boolean>

如果对等证书由创建tls.TLSSocket实例时指定的CA之一签名，则返回true，否则返回false。

tlsSocket.disableRenegotiation()

禁用此TLSSocket实例的TLS重新协商。一旦调用，重新协商的尝试将在TLSSocket上触发“错误”事件。

tlsSocket.enableTrace()

 启用后，TLS数据包跟踪信息将写入stderr。这可用于调试TLS连接问题。

注意：输出的格式与openssl s_client -trace或openssl s_server -trace的输出相同。尽管它是由OpenSSL的SSL_trace（）函数生成的，但该格式未记录在案，可以随时更改，恕不另行通知，并且不应依赖该格式。

tlsSocket.encrypted

始终返回true。这可以用来区分TLS套接字和常规的net.Socket实例。

tlsSocket.getCertificate()

Returns: <Object>

返回表示本地证书的对象。返回的对象具有一些与证书字段相对应的属性。有关证书结构的示例，请参阅tls.TLSSocket.getPeerCertificate（）。如果没有本地证书，将返回一个空对象。如果套接字已被破坏，则将返回null。

tlsSocket.getCipher()

Returns: <Object>

name <string> 密码套件的OpenSSL名称。
standardName <string> 密码套件的IETF名称.
version <string> 此密码套件支持的最低TLS协议版本。

返回一个对象，该对象包含有关共识的密码套件的信息。

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

有关更多信息，请参见SSL_CIPHER_get_name。

tlsSocket.getEphemeralKeyInfo()

Returns: <Object>

返回一个对象，该对象表示客户端连接上“ Perfect Forward Secrecy”中临时密钥交换的参数的类型，名称和大小。当密钥交换不是临时的时，它将返回一个空对象。因为这仅在客户端套接字上受支持；如果在服务器套接字上调用，则返回null。支持的类型为“ DH”和“ ECDH”。仅当类型为“ ECDH”时，名称属性才可用。

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

tlsSocket.getFinished()

Returns: <Buffer> | <undefined> 作为SSL / TLS握手的一部分发送到套接字的最新的Finished消息，如果尚未发送Finished消息，则为undefined。

由于“完成”消息是完整握手的消息摘要（TLS 1.0总共192位，SSL 3.0总共192位），因此当不需要或不需要SSL / TLS提供的身份验证时，它们可用于外部身份验证过程足够。对应于OpenSSL中的SSL_get_finished例程，可用于实现RFC 5929中的tls唯一通道绑定。

tlsSocket.getPeerCertificate([detailed])

detailed <boolean> 如果为true，则包括完整的证书链，否则仅包括对等方的证书。
Returns: <Object> 证书对象。

返回表示对等方证书的对象。如果对等方不提供证书，则将返回一个空对象。如果套接字已被破坏，则将返回null。

如果请求了完整的证书链，则每个证书将包括一个issuerCertificate属性，该属性包含一个代表其颁发者证书的对象。

证书对象具有与证书字段相对应的属性。