Node.js TLS/SSL

TLS/SSL

Stability: 3 - Stable

Node.js可以使用require('tls')来访问TLS/SSL模块：

const tls = require('tls'

tls模块使用OpenSSL来提供传输层安全性（Transport Layer Security，TLS）和安全套接层（Secure Socket Layer，SSL）：加密过的流通讯。

TLS/SSL是一种公钥/私钥基础架构，每个客户端和服务端都需要一个私钥。私钥的创建方法如下：

openssl genrsa -out ryans-key.pem 2048

你还需要为所有服务器和某些客户端添加证书。证书由认证中心（Certificate Authority）签名，或者自签名。获得证书第一步是创建一个证书签名请求"Certificate Signing Request" (CSR)文件。证书的创建方法如下：

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

使用CSR创建一个自签名的证书：

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

或者你可以发送CSR给认证中心（Certificate Authority）来签名。

(TODO: 创建CA的文档，感兴趣的读者可以在Node源码test/fixtures/keys/Makefile里查看)

创建.pfx或.p12，可以这么做：

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

in: 签名证书

协议支持

Node.js默认遵循SSLv2和SSLv3协议，不过这些协议被禁用。因为他们不太可靠，很容易受到威胁，参见CVE-2014-3566。某些情况下，旧版本客户端/服务器（比如 IE6）可能会产生问题。如果你想启用SSLv2或SSLv3 ，使用参数--enable-ssl2或--enable-ssl3运行Node。Node.js的未来版本中不会再默认编译SSLv2 和SSLv3。

有一个办法可以强制node进入仅使用SSLv3或SSLv2模式，分别指定secureProtocol为'SSLv3_method'或'SSLv2_method'。

Node.js使用的默认协议方法准确名字是AutoNegotiate_method，这个方法会尝试并协商客户端支持的从高到底协议。为了提供默认的安全级别，Node.js(v0.10.33 版本之后)通过将secureOptions设为SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2 ，明确的禁用了SSLv3和SSLv2（除非你给secureProtocol 传值--enable-ssl3，或--enable-ssl2，或SSLv3_method）。

如果你设置了secureOptions，我们不会重新这个参数。

改变这个行为的后果：

如果你的应用被当做为安全服务器，SSLv3客户端不能协商建立连接，会被拒绝。这种情况下，你的服务器会触发clientError事件。错误消息会包含错误版本数字('wrong version number')。

Client-initiated renegotiation attack mitigation

TLS协议让客户端协商TLS会话的某些方法内容。但是，会话协商需要服务器端响应的资源，这回让它成为阻断服务攻击（denial-of-service attacks）的潜在媒介。

为了降低这种情况的发生，重新协商被限制为每10分钟3次。当超出这个界限时，在tls.TLSSocket实例上会触发错误。这个限制可设置：

tls.CLIENT_RENEG_LIMIT: 重新协商limit，默认是3。

除非你明确知道自己在干什么，否则不要改变默认值。

要测试你的服务器的话，使用openssl s_client -connect address:port连接服务器，并敲R<CR>（字母 R 键加回车）几次。

NPN 和 SNI

NPN(Next Protocol Negotiation 下次协议协商)和SNI (Server Name Indication 域名指示)都是TLS握手扩展：

NPN - 同一个TLS服务器使用多种协议 (HTTP, SPDY)

完全正向保密

"Forward Secrecy"或"Perfect Forward Secrecy-完全正向保密"协议描述了秘钥协商（比如秘钥交换）方法的特点。实际上这意味着及时你的服务器的秘钥有危险，通讯仅有可能被一类人窃听，他们必须设法获的每次会话都会生成的秘钥对。

完全正向保密是通过每次握手时为秘钥协商随机生成密钥对来完成（和所有会话一个key相反）。实现这个技术（提供完全正向保密-Perfect Forward Secrecy）的方法被称为"ephemeral"。

通常目前有2个方法用于完成完全正向保密（Perfect Forward Secrecy）:

DHE - 一个迪菲-赫尔曼密钥交换密钥协议（Diffie Hellman key-agreement protocol）短暂（ephemeral）版本。

短暂（ephemeral）方法有性能缺点，因为生成 key 非常耗费资源。

tls.getCiphers()

返回支持的SSL密码名数组。

例子：

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

tls.createServer(options, secureConnectionListener)

创建一个新的tls.Server。参数connectionListener会自动设置为secureConnection事件的监听器。参数options对象有以下可能性：

pfx: 包含私钥，证书和服务器的CA证书（PFX或PKCS12 格式）字符串或缓存Buffer。（key，cert和ca互斥）。

响应服务器的简单例子：

var tls = require('tls'
var fs = require('fs'

var options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),

  // This is necessary only if using the client certificate authentication.
  requestCert: true,

  // This is necessary only if the client uses the self-signed certificate.
  ca: [ fs.readFileSync('client-cert.pem') ]
};

var server = tls.createServer(options, function(socket) {
  console.log('server connected',
              socket.authorized ? 'authorized' : 'unauthorized'
  socket.write("welcome!\n"
  socket.setEncoding('utf8'
  socket.pipe(socket
}
server.listen(8000, function() {
  console.log('server bound'
}

或者：

var tls = require('tls'
var fs = require('fs'

var options = {
  pfx: fs.readFileSync('server.pfx'),

  // This is necessary only if using the client certificate authentication.
  requestCert: true,

};

var server = tls.createServer(options, function(socket) {
  console.log('server connected',
              socket.authorized ? 'authorized' : 'unauthorized'
  socket.write("welcome!\n"
  socket.setEncoding('utf8'
  socket.pipe(socket
}
server.listen(8000, function() {
  console.log('server bound'
}

你可以通过openssl s_client连接服务器来测试：

openssl s_client -connect 127.0.0.1:8000

tls.connect(options, callback)

tls.connect(port, host, callback)

创建一个新的客户端连接到指定的端口和主机（port and host）（老版本API），或者options.port和options.host（如果忽略host，默认为 localhost）。options是一个包含以下值得对象：

host: 客户端需要连接到的主机。

将参数callback添加到'secureConnect'事件上，其效果如同监听器。

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

这是一个简单的客户端应答服务器例子：

var tls = require('tls'
var fs = require('fs'

var options = {
  // These are necessary only if using the client certificate authentication
  key: fs.readFileSync('client-key.pem'),
  cert: fs.readFileSync('client-cert.pem'),

  // This is necessary only if the server uses the self-signed certificate
  ca: [ fs.readFileSync('server-cert.pem') ]
};

var socket = tls.connect(8000, options, function() {
  console.log('client connected',
              socket.authorized ? 'authorized' : 'unauthorized'
  process.stdin.pipe(socket
  process.stdin.resume(
}
socket.setEncoding('utf8'
socket.on('data', function(data) {
  console.log(data
}
socket.on('end', function() {
  server.close(
}

或者：

var tls = require('tls'
var fs = require('fs'

var options = {
  pfx: fs.readFileSync('client.pfx')
};

var socket = tls.connect(8000, options, function() {
  console.log('client connected',
              socket.authorized ? 'authorized' : 'unauthorized'
  process.stdin.pipe(socket
  process.stdin.resume(
}
socket.setEncoding('utf8'
socket.on('data', function(data) {
  console.log(data
}
socket.on('end', function() {
  server.close(
}

类: tls.TLSSocket

net.Socket实例的封装，取代内部socket读写程序，执行透明的输入/输出数据的加密/解密。

new tls.TLSSocket(socket, options)

从现有的TCP socket里构造一个新的TLSSocket对象。

socket一个net.Socket的实例

options一个包含以下属性的对象:

secureContext: 来自tls.createSecureContext( ... )的可选TLS上下文对象。

tls.createSecureContext(details)

创建一个凭证（credentials）对象，包含字典有以下的key：

pfx : 包含PFX或PKCS12加密的私钥，证书和服务器的CA证书（PFX或PKCS12格式）字符串或缓存Buffer。（key，cert和ca互斥）。

如果没给 'ca' 细节，node.js 将会使用默认的公开信任的 CAs 列表（参见http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt）。

tls.createSecurePair(context, requestCert)

创建一个新的安全对（secure pair）对象，包含2个流，其中一个读/写加密过的数据，另外一个读/写明文数据。通常加密端数据来自是从输入的加密数据流，另一端被当做初始加密流。

credentials: 来自tls.createSecureContext( ... )的安全上下文对象。

tls.createSecurePair()返回一个安全对（SecurePair）对象，包含明文cleartext和密文encrypted流。

注意: cleartext和tls.TLSSocket拥有相同的 API。

类: SecurePair

通过tls.createSecurePair返回。

事件: 'secure'

一旦安全对（SecurePair）成功建立一个安全连接，安全对（SecurePair）将会触发这个事件。

和检查服务器'secureConnection'事件一样，pair.cleartext.authorized必须检查确认是否适用的证书是授权过的。

类: tls.Server

这是net.Server的子类，拥有相同的方法。这个类接受适用TLS或SSL的加密连接，而不是接受原始TCP连接。

事件: 'secureConnection'

function (tlsSocket) {}

新的连接握手成功后回触发这个事件。参数是tls.TLSSocket实例。它拥有常用的流方法和事件。

socket.authorized是否客户端被证书（服务器提供）授权。如果socket.authorized为false，socket.authorizationError是如何授权失败。值得一提的是，依赖于TLS服务器的设置，你的未授权连接可能也会被接受。socket.authorizationError如何授权失败。值得一提的是，依赖于TLS服务器的设置，你的未授权连接可能也会被接受。socket.npnProtocol包含选择的NPN协议的字符串。socket.servername包含SNI请求的服务器名的字符串。

事件: 'clientError'

function (exception, tlsSocket) { }

在安全连接建立前，客户端连接触发'error'事件会转发到这里来。

tlsSocket是tls.TLSSocket，错误是从这里触发的。

事件: 'newSession'

function (sessionId, sessionData, callback) { }

创建TLS会话的时候会触发。可能用来在外部存储器里存储会话。callback必须最后调用，否则没法从安全连接发送/接收数据。

注意：添加这个事件监听器仅会在连接连接时有效果。

事件: 'resumeSession'

function (sessionId, callback) { }

当客户端想恢复之前的TLS会话时会触发。事件监听器可能会使用sessionId到外部存储器里查找，一旦结束会触发callback(null, sessionData)。如果会话不能恢复（比如不存在这个会话），可能会调用callback(null, null)。调用callback(err)将会终止连接，并销毁socket。

注意：添加这个事件监听器仅会在连接连接时有效果。

事件: 'OCSPRequest'

function (certificate, issuer, callback) { }

当客户端发送证书状态请求时会触发。你可以解析服务器当前的证书，来获取OCSP网址和证书id，获取OCSP响应调用callback(null, resp)，其中resp是 Buffer实例。证书（certificate）和发行者（issuer）都是初级表达式缓存（BufferDER-representations of the primary）和证书的发行者。它可以用来获取OCSP证书和OCSP终点网址。

可以调用callback(null, null)，表示没有OCSP响应。

调用callback(err)可能会导致调用socket.destroy(err)。

典型流程:

客户端连接服务器，并发送OCSPRequest(通过 ClientHello 里的状态信息扩展)。

注意: 如果证书是自签名的，或者如果发行者不再根证书列表里（你可以通过参数提供一个发行者）。issuer就可能为null。

注意：添加这个事件监听器仅会在连接连接时有效果。

注意：你可以能想要使用npm模块（比如asn1.js）来解析证书。

server.listen(port, host)

在指定的端口和主机上开始接收连接。如果host参数没传，服务接受通过IPv4地址(INADDR_ANY)的直连。

这是异步函数。当服务器已经绑定后回调用最后一个参数callback。

更多信息参见net.Server。

server.close()

停止服务器，不再接收新连接。这是异步函数，当服务器触发'close'事件后回最终关闭。

server.address()

返回绑定的地址，地址家族名和服务器端口。更多信息参见net.Server.address()

server.addContext(hostname, context)

如果客户端请求SNI主机名和传入的hostname相匹配，将会用到安全上下文（secure context）。context可以包含key，cert，ca和/或tls.createSecureContextoptions参数的其他任何属性。

server.maxConnections

设置这个属性可以在服务器的连接数达到最大值时拒绝连接。

server.connections

当前服务器连接数。

类: CryptoStream

稳定性: 0 - 抛弃. 使用 tls.TLSSocket 替代.

这是一个加密的流

cryptoStream.bytesWritten

底层socket写字节访问器（bytesWritten accessor）的代理，将会返回写到socket的全部字节数。包括 TLS 的开销。

类: tls.TLSSocket

net.Socket实例的封装，透明的加密写数据和所有必须的TLS协商。

这个接口实现了一个双工流接口。它包含所有常用的流方法和事件。

事件: 'secureConnect'

新的连接成功握手后回触发这个事件。无论服务器证书是否授权，都会调用监听器。用于用户测试tlsSocket.authorized看看如果服务器证书已经被指定的CAs签名。如果tlsSocket.authorized === false ，可以在tlsSocket.authorizationError里找到错误。如果使用了NPN，你可以检tlsSocket.npnProtocol获取协商协议（negotiated protocol）。

事件: 'OCSPResponse'

function (response) { }

如果启用requestOCSP参赛会触发这个事件。response是缓存对象，包含服务器的OCSP响应。

一般来说，response是服务器CA签名的对象，它包含服务器撤销证书状态的信息。

tlsSocket.encrypted

静态boolean变量，一直是true。可以用来区别TLS socket和常规对象。

tlsSocket.authorized

boolean变量，如果对等实体证书（peer's certificate）被指定的某个CAs签名，返回true，否则false。

tlsSocket.authorizationError

对等实体证书（peer's certificate）没有验证通过的原因。当tlsSocket.authorized === false时，这个属性才可用。

tlsSocket.getPeerCertificate( detailed )

返回一个代表对等实体证书（ peer's certificate）的对象。这个返回对象有一些属性和证书内容相对应。如果参数detailed是true，将会返回包含发行者issuer完整链。如果false，仅有顶级证书没有发行者issuer属性。

例子：

{ subject:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuerInfo:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuer:
   { ... another certificate ... },
  raw: < RAW DER buffer >,
  valid_from: 'Nov 11 09:52:22 2009 GMT',
  valid_to: 'Nov  6 09:52:22 2029 GMT',
  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF',
  serialNumber: 'B9B0D332A1AA5635' }

如果peer没有提供证书，返回null或空对象。

tlsSocket.getCipher()

返回一个对象，它代表了密码名和当前连接的SSL/TLS协议的版本。

例子：{ name: 'AES256-SHA', version: 'TLSv1/SSLv3' }

tlsSocket.renegotiate(options, callback)

初始化 TLS 重新协商进程。参数options可能包含以下内容：rejectUnauthorized，requestCert(细节参见tls.createServer)。一旦重新协商成（renegotiation）功完成，将会执行callback(err)，其中err为null。

注意：当安全连接建立后，可以用这来请求对等实体证书（peer's certificate）。

注意：作为服务器运行时，handshakeTimeout超时后，socket将会被销毁。

tlsSocket.setMaxSendFragment(size)

设置最大的TLS碎片大小（默认最大值为：16384，最小值为：512）。成功的话，返回true，否则返回false。

小的碎片包会减少客户端的缓存延迟：大的碎片直到接收完毕后才能被TLS层完全缓存，并且验证过完整性；大的碎片可能会有多次往返，并且可能会因为丢包或重新排序导致延迟。而小的碎片会增加额外的TLS帧字节和CPU负载，这会减少CPU的吞吐量。

tlsSocket.getSession()

返回ASN.1编码的TLS会话，如果没有协商，会返回。连接到服务器时，可以用来加速握手的建立。

tlsSocket.getTLSTicket()

注意：仅和客户端TLS socket打交道。仅在调试时有用，会话重用是，提供session参数给tls.connect。

返回TLS会话票据（ticket），或如果没有协商（negotiated），返回undefined。

tlsSocket.address()

返回绑定的地址，地址家族名和服务器端口。更多信息参见net.Server.address()。返回三个属性, 比如：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }

tlsSocket.remoteAddress

表示远程IP地址（字符串表示），例如：'74.125.127.100'或'2001:4860:a005::68'.

tlsSocket.remoteFamily

表示远程 IP 家族，'IPv4'或'IPv6'。

tlsSocket.remotePort

远程端口（数字表示），例如，443。

tlsSocket.localAddress

本地IP地址（字符串表示）。

tlsSocket.localPort

本地端口号（数字表示）。