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属性,该属性包含一个代表其颁发者证书的对象。
证书对象具有与证书字段相对应的属性。