方法和属性


tls.createServer(options[, secureConnectionListener])

创建一个新的 tls.ServerconnectionListener 参数自动设置为 ‘secureConnection’ 事件的监听器。options 对象可能包含以下字段:

  • pfx:一个字符串或 Buffer,包含服务器端 PFX 或 PKCS12 格式的私钥、证书和 CA 证书(keycertca 选项互斥)。

  • key:一个字符串或 Buffer,包含服务器端 PEM 格式的私钥。为了支持多个私钥使用不同算法。它可以是一组普通的私匙或一组 {pem: key, passphrase: passphrase} 格式的对象。(必需)

  • passphrase:一个包含私钥 或 pfx 口令的字符串。

  • cert:一个字符串、Buffer、一组字符串或一组 Buffer,包含 PEM 格式的服务器证书密钥。(必需)

  • ca:一个字符串、Buffer、一组字符串或一组 Buffer,PEM 格式的受信任的证书。如果省略,则会使用几个著名的“根”的 CA(例如 VeriSign)。这些用于授权的连接。

  • crl:一个字符串或一组 PEM 编码的 CRLs(证书吊销列表)的字符串。

  • ciphers:描述要使用或排除的加密字符串,使用 : 分隔。默认的加密套件是:

  1. ECDHE-RSA-AES128-GCM-SHA256:
  2. ECDHE-ECDSA-AES128-GCM-SHA256:
  3. ECDHE-RSA-AES256-GCM-SHA384:
  4. ECDHE-ECDSA-AES256-GCM-SHA384:
  5. DHE-RSA-AES128-GCM-SHA256:
  6. ECDHE-RSA-AES128-SHA256:
  7. DHE-RSA-AES128-SHA256:
  8. ECDHE-RSA-AES256-SHA384:
  9. DHE-RSA-AES256-SHA384:
  10. ECDHE-RSA-AES256-SHA256:
  11. DHE-RSA-AES256-SHA256:
  12. HIGH:
  13. !aNULL:
  14. !eNULL:
  15. !EXPORT:
  16. !DES:
  17. !RC4:
  18. !MD5:
  19. !PSK:
  20. !SRP:
  21. !CAMELLIA

默认加密套件偏好 GCM 加密,Chrome 的“现代密码学”设置,同时也偏好 ECDHE 和 DHE 加密,完全正向加密,同时提供一些向后兼容性。

128 位 AES 优于 192 和 256 位 AES,特定攻击对更大的 AES 密钥大小影响更小

老的客户端依靠不安全、不推荐使用的 RC4 或基于 DES 的加密算法(如 Internet Explorer 6)是无法完成默认配置的握手过程。如果客户端必须支持这些TLS 建议可以提供一个兼容的加密套件。有关格式方面的更多细节,详见 OpenSSL 加密列表格式文档

  • ecdhCurve:描述了一个名为曲线的字符串用于 ECDH 密钥协议或使用 false 禁用 ECDH。

默认为 prime256v1(NIST P-256)。使用 crypto.getCurves() 来获得可用的曲线名称列表。在最近的版本中,openssl ecparam -list_curves 也将显示名称和每个可用椭圆曲线的描述。

  • dhparam:一个字符串或 Buffer,包含 Diffie Hellman 参数,需要完全正向加密。使用 openssl dhparam 来创建它。它的密钥长度应大于或等于 1024 位,否则它将抛出一个错误。强烈建议使用 2048 位或以上来加强安全性。如果省略或无效,它被静默丢弃并且 DHE 加密将无法使用。

  • handshakeTimeout:如果 SSL/TLS 握手无法在指定毫秒数内完成将会中止连接。默认值是 120 秒。

每当一个握手超时,就会在 tls.Server 对象上发出一个 'clientError' 事件。

  • honorCipherOrder:当选择一个加密时,使用服务器端偏好代替客户端偏好。默认为 true

  • requestCert:如果为 true,服务器将请求所连接的客户端的证书,并尝试验证证书。默认为 false

  • rejectUnauthorized:如果为 true,服务器将拒绝未在提供的授权 CA 列表中的任何连接。此选项仅当 requestCerttrue 时有效。默认为 false

  • NPNProtocols:一个可能的 NPN 协议数组或 Buffers。(协议应该由它们的优先级进行排序。)

  • ALPNProtocols:一个可能的 ALPNP 协议数组或 Buffers。(协议应该由它们的优先级进行排序。)当服务器从客户端同时接收 NPN 和 ALPN 扩展时,ALPN 优先于 NPN 并且服务器不会发送一个 NPN 扩展到客户端。

  • SNICallback(servername, cb):如果客户端支持 SNI TLS 扩展,函数将被调用。两个参数将被传递给它:servernamecbSNICallback 应该调用 cb(null, ctx),其中,ctx 一个是 SecureContext 实例。(tls.createSecureContext(...) 可以用来得到适当的 SecureContext)。如果未提供 SNICallback,将使用带有高级 API 的默认回调(见下文)。

  • sessionTimeout:一个整数,指定在服务器创建 TLS 会话标识符之后的秒数并且服务器创建 TLS 会话凭证将超时。详见 SSL_CTX_set_timeout 了解更多细节。

  • ticketKeys:一个 48 字节的 Buffer 实例由一个 16 字节的前缀,16 字节的 HMAC 密钥,和一个 16 字节的 AES 密钥组成。这可以用来接受多个 TLS 服务器上的 TLS 会话凭证。

注意cluster 模块的工作进程之间自动共享。

  • sessionIdContext:一个字符串包含一个用于会话恢复的不透明的标识符。如果 requestCerttrue。默认值是来自命令行产生一个 MD5 哈希值。(在 FIPS 模式中用一个截断的 SHA1 哈希代替。)否则,不提供默认值。

  • secureProtocol:要使用的 SSL 方法,如,SSLv3_method 强制 SSL 版本 3。可能的值取决于你安装的 OpenSSL 并定义不变的 SSL_METHODS

下面是一个简单的响应服务器例子:

  1. const tls = require('tls');
  2. const fs = require('fs');
  3. const options = {
  4. key: fs.readFileSync('server-key.pem'),
  5. cert: fs.readFileSync('server-cert.pem'),
  6. // This is necessary only if using the client certificate authentication.
  7. requestCert: true,
  8. // This is necessary only if the client uses the self-signed certificate.
  9. ca: [fs.readFileSync('client-cert.pem')]
  10. };
  11. var server = tls.createServer(options, (socket) => {
  12. console.log('server connected',
  13. socket.authorized ? 'authorized' : 'unauthorized');
  14. socket.write('welcome!\n');
  15. socket.setEncoding('utf8');
  16. socket.pipe(socket);
  17. });
  18. server.listen(8000, () => {
  19. console.log('server bound');
  20. });

  1. const tls = require('tls');
  2. const fs = require('fs');
  3. const options = {
  4. pfx: fs.readFileSync('server.pfx'),
  5. // This is necessary only if using the client certificate authentication.
  6. requestCert: true,
  7. };
  8. var server = tls.createServer(options, (socket) => {
  9. console.log('server connected',
  10. socket.authorized ? 'authorized' : 'unauthorized');
  11. socket.write('welcome!\n');
  12. socket.setEncoding('utf8');
  13. socket.pipe(socket);
  14. });
  15. server.listen(8000, () => {
  16. console.log('server bound');
  17. });

你可以通过使用 openssl s_client 连接到这台服务器来做测试:

  1. openssl s_client -connect 127.0.0.1:8000

tls.connect(options[, callback])

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

使用给定的 porthost(老 API)或 options.portoptions.host 创建一个新的客户端连接。(如果省略 host,它默认为 localhost。)options 应该是一个可以指定以下属性的对象:

  • host:客户端应该连接到主机。

  • port:客户端应该连接到端口。

  • socket:在一个给定的套接字上建立安全连接,而不是创建一个新的套接字。如果指定了此选项,会忽略 hostport

  • path:创建 Unix 套接字连接路径。如果指定了此选项,会忽略 hostport

  • pfx:一个字符串或 Buffer,包含服务器端 PFX 或 PKCS12 格式的私钥、证书和 CA 证书。

  • key:一个字符串、Buffer、一组字符串或一组 Buffer,包含 PEM 格式的客户端私钥。

  • passphrase:一个包含私钥 或 pfx 口令的字符串。

  • cert:一个字符串、Buffer、一组字符串或一组 Buffer,包含 PEM 格式的客户端证书密钥。

  • ca:一个字符串、Buffer、一组字符串或一组 Buffer,PEM 格式的受信任的证书。如果省略,则会使用几个著名的“根”的 CA(例如 VeriSign)。这些用于授权的连接。

  • ciphers:描述要使用或排除的加密字符串,使用 : 分隔。默认的加密套件和 tls.createServer() 相同。

  • rejectUnauthorized:如果为 true,服务器将拒绝未在提供的授权 CA 列表中的任何连接。如果验证失败,会发出一个 'error' 事件;err.code 包含 OpenSSL 错误码。默认为 true

  • NPNProtocols:一个可能的 NPN 协议字符串数组或 Buffers。Buffers 应该有以下格式:0x05hello0x05world,其中第一个字节是下一个协议的名称的长度。(传递一个数组通常会简单得多:['hello', 'world']

  • ALPNProtocols:一个可能的 ALPNP 协议字符串数组或 Buffers。Buffers 应该有以下格式:0x05hello0x05world,其中第一个字节是下一个协议的名称的长度。(传递一个数组通常会简单得多:['hello', 'world']

  • servername:用于 SNI(服务器名称指示)TLS 扩展的服务器名称。

  • checkServerIdentity(servername, cert):对服务器名称针对的证书提供覆盖检查。如果验证失败应该返回一个错误。如果通过,返回 undefined

  • secureProtocol:要使用的 SSL 方法,如,SSLv3_method 强制 SSL 版本 3。可能的值取决于你安装的 OpenSSL 并定义不变的 SSL_METHODS

  • secureContext:从 tls.createSecureContext( ... ) 获取的一个可选的 TLS 上下文对象。它可以被用于缓存客户端证书、密钥和 CA 证书。

  • session:一个 Buffer 实例,包含 TLS 会话。

  • minDHSize:可接受的 TLS 连接的 DH 参数的最小值(以“位”为单位)。当一台服务器提供了一个尺寸小于该值的 DH 参数,该 TLS 连接会被销毁,并抛出错误。默认:1024

callback 参数会被添加作为 ‘secureConnect’ 事件的一个监听器。

tls.connect() 返回一个 tls.TLSSocket 对象。

这里有一个之前描述的响应服务器的客户端例子:

  1. const tls = require('tls');
  2. const fs = require('fs');
  3. const options = {
  4. // These are necessary only if using the client certificate authentication
  5. key: fs.readFileSync('client-key.pem'),
  6. cert: fs.readFileSync('client-cert.pem'),
  7. // This is necessary only if the server uses the self-signed certificate
  8. ca: [fs.readFileSync('server-cert.pem')]
  9. };
  10. var socket = tls.connect(8000, options, () => {
  11. console.log('client connected',
  12. socket.authorized ? 'authorized' : 'unauthorized');
  13. process.stdin.pipe(socket);
  14. process.stdin.resume();
  15. });
  16. socket.setEncoding('utf8');
  17. socket.on('data', (data) => {
  18. console.log(data);
  19. });
  20. socket.on('end', () => {
  21. server.close();
  22. });

  1. const tls = require('tls');
  2. const fs = require('fs');
  3. const options = {
  4. pfx: fs.readFileSync('client.pfx')
  5. };
  6. var socket = tls.connect(8000, options, () => {
  7. console.log('client connected',
  8. socket.authorized ? 'authorized' : 'unauthorized');
  9. process.stdin.pipe(socket);
  10. process.stdin.resume();
  11. });
  12. socket.setEncoding('utf8');
  13. socket.on('data', (data) => {
  14. console.log(data);
  15. });
  16. socket.on('end', () => {
  17. server.close();
  18. });

tls.createSecureContext(options)

创建一个凭据对象;该 options 对象可能包含以下字段:

  • pfx:一个字符串或 Buffer,包含服务器端 PFX 或 PKCS12 格式的私钥、证书和 CA 证书。

  • key:一个字符串或 Buffer,包含服务器端 PEM 格式的私钥。为了支持多个私钥使用不同算法。它可以是一组普通的私匙或一组 {pem: key, passphrase: passphrase} 格式的对象。(必需)

  • passphrase:一个包含私钥 或 pfx 口令的字符串。

  • cert:一个包含 PEM 编码的证书。

  • ca:一个字符串、Buffer、一组字符串或一组 Buffer,PEM 格式的受信任的证书。如果省略,则会使用几个著名的“根”的 CA(例如 VeriSign)。这些用于授权的连接。

  • crl:一个字符串或一组 PEM 编码的 CRLs(证书吊销列表)的字符串。

  • ciphers:一个描述使用或排除的加密方式的字符串。在 https://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT 上参考格式细节。

  • honorCipherOrder:当选择一种加密时,请使用服务器的偏好,而不是客户端的偏好。详见 tls 模块文档。

如果没有给出 ‘CA’ 细节,那么 Node.js 就会使用 CA 在 http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt 上给出的默认公众信任列表。

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

创建一个新的具有两个流的安全对对象,其中一个读写经过加密数据和另一个读写明文数据。通常,已加密流通过管道输送到加密数据流,或从加密数据流输入并且明文被用作最初加密流的替代品。

  • credentials:从 tls.createSecureContext( ... ) 获取的一个安全的上下文对象。

  • isServer:布尔值,指示此 TLS 连接是否应该被打开作为服务器或客户端。

  • requestCert:布尔值,指示服务器是否应该从客户端连接请求证书。只适用于服务器的连接。

  • rejectUnauthorized:布尔值,指示服务器是否应自动拒绝客户提供无效证书。只适用于服务器 requestCert 可用时。

  • options:普通的 SSL 选项对象。详见 tls.TLSSocket

tls.createSecurePair() 返回一个安全对对象,带有 cleartextencrypted 流属性。

注意cleartexttls.TLSSocket 有着相同的 API。

tls.getCiphers()

返回一个支持的 SSL 加密的名称数组。

示例:

  1. var ciphers = tls.getCiphers();
  2. console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...]