Node.js v16.18.1 文档


目录

tls 安全传输层#

中英对照

node:tls 模块提供了构建在 OpenSSL 之上的传输层安全 (TLS) 和安全套接字层 (SSL) 协议的实现。 该模块可以使用以下方式访问:


确定加密支持是否不可用#

中英对照

可以在不支持 node:crypto 模块的情况下构建 Node.js。 在这种情况下,尝试 import tls 或调用 require('node:tls') 将导致抛出错误。



TLS/SSL 概念#

中英对照

TLS/SSL 是一组协议,它依赖于公钥基础设施 (PKI) 来实现客户端和服务器之间的安全通信。 对于最常见的情况,每个服务器都必须有私钥。





    完美前向保密#

    中英对照

    术语 前向保密完美前向保密 描述了密钥协议(即密钥交换)方法的一个特征。 也就是说,服务器和客户端密钥用于协商新的临时密钥,这些密钥专门用于且仅用于当前通信会话。 实际上,这意味着即使服务器的私钥被泄露,如果攻击者设法获得专门为会话生成的密钥对,通信也只能被窃听者解密。

      
      

      ALPN 和 SNI#

      中英对照

      ALPN(应用层协议协商扩展)和 SNI(服务器名称指示)是 TLS 握手扩展:

        预共享的密钥#

        中英对照

        TLS-PSK 支持可作为普通基于证书的身份验证的替代方法。 它使用预共享密钥而不是证书来验证 TLS 连接,提供相互验证。 TLS-PSK 和公钥基础设施并不相互排斥。 客户端和服务器可以同时容纳两者,在正常的密码协商步骤中选择它们中的任何一个。

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

        中英对照

        TLS 协议允许客户端重新协商 TLS 会话的某些方面。 不幸的是,会话重新协商需要不成比例的服务器端资源,使其成为拒绝服务攻击的潜在载体。

          会话恢复#

          中英对照

          建立 TLS 会话可能相对较慢。 可以通过保存并稍后重用会话状态来加快进程。 有几种机制可以做到这一点,这里从最旧到最新(和首选)进行了讨论。

          会话标识符#

          中英对照

          服务器为新连接生成唯一的 ID 并将其发送给客户端。 客户端和服务器保存会话状态。 当重新连接时,客户端发送其保存的会话状态的 ID,如果服务器也有该 ID 的状态,它可以同意使用它。 否则,服务器将创建新的会话。 请参阅 RFC 2246 了解更多信息,第 23 和 30 页\。

          会话票证#

          中英对照

          服务器加密整个会话状态并将其作为"票证"发送给客户端。 当重新连接时,在初始连接时将状态发送到服务器。 此机制避免了对服务器端会话缓存的需要。 如果服务器不使用票证,出于任何原因(无法解密、太旧等),则它将创建新的会话并发送新的票证。 请参阅 RFC 5077 了解更多信息。

          
          

          
          

          
          

          修改默认的 TLS 加密组件#

          中英对照

          Node.js 是使用默认的启用和禁用 TLS 密码套件构建的。 这个默认密码列表可以在构建 Node.js 时配置,以允许发行版提供自己的默认列表。

          
          

          
          

            X509 证书的错误码#

            中英对照

            由于 OpenSSL 报告的证书错误,多个功能可能会失败。 在这种情况下,该函数通过其回调提供 <Error>,该回调具有属性 code,该属性可以采用以下值之一:

              tls.CryptoStream#

              中英对照

              tls.CryptoStream 类表示加密数据流。 此类已弃用,不应再使用。

              cryptoStream.bytesWritten#

              中英对照

              cryptoStream.bytesWritten 属性返回写入底层套接字的总字节数_包括_实现 TLS 协议所需的字节数。

              tls.SecurePair#

              中英对照

              tls.createSecurePair() 返回。

              'secure' 事件#

              中英对照

              一旦建立了安全连接,则 SecurePair 对象就会触发 'secure' 事件。

              tls.Server#

              中英对照

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

                'connection' 事件#

                中英对照

                  此事件在建立新的 TCP 流时触发,在 TLS 握手开始之前。 socket 通常是 net.Socket 类型的对象,但不会像从 net.Server 'connection' 事件创建的套接字那样接收事件。 通常用户不会想访问这个事件。

                  'keylog' 事件#

                  中英对照

                    keylog 事件在生成或通过与此服务器的连接接收密钥材料时触发(通常在握手完成之前,但不一定)。 该密钥材料可以存储用于调试,因为它允许对捕获的 TLS 流量进行解密。 它可以为每个套接字多次触发。

                    
                    

                    'newSession' 事件#

                    中英对照

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

                      'OCSPRequest' 事件#

                      中英对照

                      当客户端发送证书状态请求时会触发 'OCSPRequest' 事件。 监听器回调在调用时传入三个参数:

                          'resumeSession' 事件#

                          中英对照

                          当客户端请求恢复之前的 TLS 会话时,则会触发 'resumeSession' 事件。 监听器回调在调用时传入两个参数:

                            
                            

                            'secureConnection' 事件#

                            中英对照

                            'secureConnection' 事件在新连接的握手过程成功完成后触发。 监听器回调在调用时传入一个参数:

                              'tlsClientError' 事件#

                              中英对照

                              在建立安全连接之前发生错误时会触发 'tlsClientError' 事件。 监听器回调在调用时传入两个参数:

                                server.addContext(hostname, context)#

                                中英对照

                                  server.addContext() 方法添加了安全的上下文,如果客户端请求的 SNI 名称与提供的 hostname(或通配符)匹配,则将使用该上下文。

                                  server.address()#

                                  中英对照

                                    返回操作系统报告的绑定地址、地址族名称和服务器端口。 有关详细信息,请参阅 net.Server.address()

                                    server.close([callback])#

                                    中英对照

                                      server.close() 方法阻止服务器接受新连接。

                                      server.getTicketKeys()#

                                      中英对照

                                        返回会话票证密钥。

                                        server.listen()#

                                        中英对照

                                        启动服务器监听加密连接。 此方法与 net.Server 中的 server.listen() 相同。

                                        server.setSecureContext(options)#

                                        中英对照

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

                                          server.setTicketKeys(keys)#

                                          中英对照

                                            设置会话票证密钥。

                                            tls.TLSSocket#

                                            中英对照

                                              对写入的数据和所有必需的 TLS 协商进行透明加密。

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

                                              中英对照

                                                从现有的 TCP 套接字构造新的 tls.TLSSocket 对象。

                                                'keylog' 事件#

                                                中英对照

                                                  当套接字生成或接收密钥材料时,keylog 事件在 tls.TLSSocket 上触发。 该密钥材料可以存储用于调试,因为它允许对捕获的 TLS 流量进行解密。 它可能会在握手完成之前或之后多次触发。

                                                  
                                                  

                                                  'OCSPResponse' 事件#

                                                  中英对照

                                                  如果在创建 tls.TLSSocket 并收到 OCSP 响应时设置了 requestOCSP 选项,则会触发 'OCSPResponse' 事件。 监听器回调在调用时传入一个参数:

                                                    'secureConnect' 事件#

                                                    中英对照

                                                    'secureConnect' 事件在新连接的握手过程成功完成后触发。 无论服务器的证书是否被授权,都会调用监听回调。 客户端有责任检查 tlsSocket.authorized 属性以确定服务器证书是否由指定的 CA 之一签名。 如果为 tlsSocket.authorized === false,则可以通过检查 tlsSocket.authorizationError 属性来发现错误。 如果使用了 ALPN,可以检查 tlsSocket.alpnProtocol 属性来确定协商的协议。

                                                    'session' 事件#

                                                    中英对照

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

                                                      
                                                      

                                                      tlsSocket.address()#

                                                      中英对照

                                                        返回操作系统报告的底层套接字的绑定 address、地址 family 名称和 port{ port: 12346, family: 'IPv4', address: '127.0.0.1' }

                                                        tlsSocket.authorizationError#

                                                        中英对照

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

                                                        tlsSocket.authorized#

                                                        中英对照

                                                          如果对等证书由创建 tls.TLSSocket 实例时指定的 CA 之一签名,则此属性为 true,否则为 false

                                                          tlsSocket.disableRenegotiation()#

                                                          中英对照

                                                          禁用此 TLSSocket 实例的 TLS 重新协商。 一旦调用,则尝试重新协商将在 TLSSocket 上触发 'error' 事件。

                                                          tlsSocket.enableTrace()#

                                                          中英对照

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

                                                          tlsSocket.encrypted#

                                                          中英对照

                                                          总是返回 true。 这可用于将 TLS 套接字与常规 net.Socket 实例区分开来。

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

                                                          中英对照

                                                            密钥材料用于验证以防止网络协议中的不同类型的攻击,例如在 IEEE 802.1X 的规范中。

                                                            
                                                            

                                                            tlsSocket.getCertificate()#

                                                            中英对照

                                                              返回表示本地证书的对象。 返回的对象有一些与证书字段对应的属性。

                                                              tlsSocket.getCipher()#

                                                              中英对照

                                                                返回包含协商密码套件信息的对象。

                                                                
                                                                

                                                                tlsSocket.getEphemeralKeyInfo()#

                                                                中英对照

                                                                  返回一个对象,表示客户端连接上完美前向保密中临时密钥交换的参数的类型、名称和大小。 当密钥交换不是短暂的时,则它返回空对象。 因为这仅在客户端套接字上受支持;如果在服务器套接字上调用,则返回 null。 支持的类型是 'DH''ECDH'name 属性仅在类型为 'ECDH' 时可用。

                                                                  tlsSocket.getFinished()#

                                                                  中英对照

                                                                    由于 Finished 消息是完整握手的消息摘要(对于 TLS 1.0 总共有 192 位,对于 SSL 3.0 则更多),当不需要或不需要 SSL/TLS 提供的身份验证时,它们可用于外部身份验证程序不够。

                                                                    tlsSocket.getPeerCertificate([detailed])#

                                                                    中英对照

                                                                      返回代表对等方证书的对象。 如果对端没有提供证书,则将返回空对象。 如果套接字被销毁,则返回 null

                                                                      证书对象#

                                                                      中英对照

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

                                                                            
                                                                            

                                                                            tlsSocket.getPeerFinished()#

                                                                            中英对照

                                                                              由于 Finished 消息是完整握手的消息摘要(对于 TLS 1.0 总共有 192 位,对于 SSL 3.0 则更多),当不需要或不需要 SSL/TLS 提供的身份验证时,它们可用于外部身份验证程序不够。

                                                                              tlsSocket.getPeerX509Certificate()#

                                                                              中英对照

                                                                                返回对等证书作为 <X509Certificate> 对象。

                                                                                tlsSocket.getProtocol()#

                                                                                中英对照

                                                                                  返回包含当前连接的协商 SSL/TLS 协议版本的字符串。 对于尚未完成握手过程的已连接套接字,将返回值 'unknown'。 服务器套接字或断开的客户端套接字将返回值 null

                                                                                    tlsSocket.getSession()#

                                                                                    中英对照

                                                                                      如果没有协商会话,则返回 TLS 会话数据或 undefined。 在客户端,可以将数据提供给 tls.connect()session 选项来恢复连接。 在服务器上,它可能对调试有用。

                                                                                      tlsSocket.getSharedSigalgs()#

                                                                                      中英对照

                                                                                        有关详细信息,请参阅 SSL_get_shared_sigalgs

                                                                                        tlsSocket.getTLSTicket()#

                                                                                        中英对照

                                                                                          对于客户端,如果可用,则返回 TLS 会话票证,或 undefined。 对于服务器,总是返回 undefined

                                                                                          tlsSocket.getX509Certificate()#

                                                                                          中英对照

                                                                                            将本地证书作为 <X509Certificate> 对象返回。

                                                                                            tlsSocket.isSessionReused()#

                                                                                            中英对照

                                                                                              请参阅会话恢复了解更多信息。

                                                                                              tlsSocket.localAddress#

                                                                                              中英对照

                                                                                                返回本地 IP 地址的字符串表示形式。

                                                                                                tlsSocket.localPort#

                                                                                                中英对照

                                                                                                  返回本地端口的数字表示。

                                                                                                  tlsSocket.remoteAddress#

                                                                                                  中英对照

                                                                                                    返回远程 IP 地址的字符串表示形式。 例如,'74.125.127.100''2001:4860:a005::68'

                                                                                                    tlsSocket.remoteFamily#

                                                                                                    中英对照

                                                                                                      返回远程 IP 族的字符串表示形式。 'IPv4''IPv6'

                                                                                                      tlsSocket.remotePort#

                                                                                                      中英对照

                                                                                                        返回远程端口的数字表示。 例如,443

                                                                                                        tlsSocket.renegotiate(options, callback)#

                                                                                                        中英对照

                                                                                                          tlsSocket.renegotiate() 方法启动 TLS 重新协商过程。 当完成后,callback 函数将传入一个参数,该参数是 Error(如果请求失败)或 null

                                                                                                          tlsSocket.setMaxSendFragment(size)#

                                                                                                          中英对照

                                                                                                            tlsSocket.setMaxSendFragment() 方法设置最大 TLS 片段大小。 如果设置限制成功,则返回 true;否则返回 false

                                                                                                            tls.checkServerIdentity(hostname, cert)#

                                                                                                            中英对照

                                                                                                              验证证书 cert 颁发给 hostname

                                                                                                              tls.connect(options[, callback])#

                                                                                                              中英对照

                                                                                                                callback 函数,如果指定,则将被添加为 'secureConnect' 事件的监听器。

                                                                                                                
                                                                                                                

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

                                                                                                                中英对照

                                                                                                                  tls.connect() 相同,除了 path 可以作为参数而不是选项提供。

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

                                                                                                                  中英对照

                                                                                                                    tls.connect() 相同,除了 porthost 可以作为参数而不是选项提供。

                                                                                                                    tls.createSecureContext([options])#

                                                                                                                    中英对照

                                                                                                                      tls.createServer()honorCipherOrder 选项的默认值设置为 true,创建安全上下文的其他 API 未设置。

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

                                                                                                                      中英对照

                                                                                                                        使用两个流创建新的安全对对象,其中一个读取和写入加密数据,另一个读取和写入明文数据。 通常,加密流通过管道传输到/从传入的加密数据流,明文用作初始加密流的替代。

                                                                                                                        
                                                                                                                        

                                                                                                                        
                                                                                                                        

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

                                                                                                                        中英对照

                                                                                                                          创建新的 tls.ServersecureConnectionListener,如果提供,将自动设置为 'secureConnection' 事件的监听器。

                                                                                                                          
                                                                                                                          

                                                                                                                          tls.getCiphers()#

                                                                                                                          中英对照

                                                                                                                            返回包含支持的 TLS 密码名称的数组。 由于历史原因,名称为小写,但必须大写才能在 tls.createSecureContext()ciphers 选项中使用。

                                                                                                                            
                                                                                                                            

                                                                                                                            tls.rootCertificates#

                                                                                                                            中英对照

                                                                                                                              不可变的字符串数组,代表当前 Node.js 版本提供的捆绑 Mozilla CA 存储中的根证书(PEM 格式)。

                                                                                                                              tls.DEFAULT_ECDH_CURVE#

                                                                                                                              中英对照

                                                                                                                              tls 服务器中用于 ECDH 密钥协议的默认曲线名称。 默认值为 'auto'。 请参阅 tls.createSecureContext() 了解更多信息。

                                                                                                                              tls.DEFAULT_MAX_VERSION#

                                                                                                                              中英对照

                                                                                                                                tls.DEFAULT_MIN_VERSION#

                                                                                                                                中英对照

                                                                                                                                  返回顶部