{ "source": "tls.markdown", "modules": [ { "textRaw": "TLS (SSL)", "name": "tls_(ssl)", "desc": "
稳定度: 3 - 稳定
\n

Use require('tls') to access this module.\n\n

\n

使用 require('tls') 来访问此模块。\n\n

\n

The tls module uses OpenSSL to provide Transport Layer Security and/or\nSecure Socket Layer: encrypted stream communication.\n\n

\n

tls 模块使用 OpenSSL 来提供传输层安全协议（Transport Layer Security）和/或安全套接层（Secure Socket Layer）：加密过的流通讯。\n\n

\n

TLS/SSL is a public/private key infrastructure. Each client and each\nserver must have a private key. A private key is created like this\n\n

\n

TLS/SSL 是一种公钥/私钥架构。每个客户端和服务器都必有一个私钥。一个私钥使用类似的方式创建：\n\n

\n
openssl genrsa -out ryans-key.pem 1024
\n

All severs and some clients need to have a certificate. Certificates are public\nkeys signed by a Certificate Authority or self-signed. The first step to\ngetting a certificate is to create a "Certificate Signing Request" (CSR)\nfile. This is done with:\n\n

\n

所有服务器和某些客户端需要具备证书。证书是证书办法机构签发或自签发的公钥。获取证书的第一步是创建一个“证书签发申请”（CSR）文件。使用这条命令完成：\n\n

\n
openssl req -new -key ryans-key.pem -out ryans-csr.pem
\n

To create a self-signed certificate with the CSR, do this:\n\n

\n

像这样使用 CSR 创建一个自签名证书：\n\n

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

Alternatively you can send the CSR to a Certificate Authority for signing.\n\n

\n

又或者你可以将 CSR 发送给一个数字证书认证机构请求签名。\n\n

\n

(TODO: docs on creating a CA, for now interested users should just look at\ntest/fixtures/keys/Makefile in the Node source code)\n\n

\n

To create .pfx or .p12, do this:\n\n

\n

像这样创建 .pfx 或 .p12：\n\n

\n
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \\\n    -certfile ca-cert.pem -out agent5.pfx
\n\n", "miscs": [ { "textRaw": "Client-initiated renegotiation attack mitigation", "name": "Client-initiated renegotiation attack mitigation", "type": "misc", "desc": "

The TLS protocol lets the client renegotiate certain aspects of the TLS session.\nUnfortunately, session renegotiation requires a disproportional amount of\nserver-side resources, which makes it a potential vector for denial-of-service\nattacks.\n\n

\n

TLS协议会令客户端可以重新协商TLS会话的某些方面。但是，会话的重新协商是需要相应量的服务器端资源的，所以导致其变成一个阻断服务攻击（denial-of-service）的潜在媒介。\n\n

\n

To mitigate this, renegotiations are limited to three times every 10 minutes. An\nerror is emitted on the [tls.TLSSocket][] instance when the threshold is\nexceeded. The limits are configurable:\n\n

\n

为了减低这种情况的发生，重新协商被限制在每10分钟三次。如果超过这个数目，那么在[tls.TLSSocket][]实例上就会分发一个错误。这个限制是可设置的：\n\n

\n\n

Don't change the defaults unless you know what you are doing.\n\n

\n

除非你完全理解整个机制和清楚自己要干什么，否则不要改变这个默认值。\n\n

\n

To test your server, connect to it with openssl s_client -connect address:port\nand tap R<CR> (that's the letter R followed by a carriage return) a few\ntimes.\n\n

\n

要测试你的服务器的话，用命令 openssl s_client -connect 地址:端口连接上服务器，然后敲击R<CR>（字母键R加回车键）几次。\n\n

\n" }, { "textRaw": "NPN 和 SNI", "name": "NPN 和 SNI", "type": "misc", "desc": "

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS\nhandshake extensions allowing you:\n\n

\n\n" } ], "methods": [ { "textRaw": "tls.getCiphers()", "type": "method", "name": "getCiphers", "desc": "

Returns an array with the names of the supported SSL ciphers.\n\n

\n

返回一个数组，其中包含了所支持的SSL加密器的名字。\n\n

\n

Example:\n\n

\n

示例：\n\n

\n
var ciphers = tls.getCiphers();\nconsole.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...]
\n", "signatures": [ { "params": [] } ] }, { "textRaw": "tls.createServer(options, [secureConnectionListener])", "type": "method", "name": "createServer", "desc": "

Creates a new [tls.Server][]. The connectionListener argument is\nautomatically set as a listener for the [secureConnection][] event. The\noptions object has these possibilities:\n\n

\n

新建一个新的 [tls.Server][]. The connectionListener 参数会自动设置为 [secureConnection][] 事件的监听器. 这个 options 对象有这些可能性:\n\n

\n\n

Here is a simple example echo server:\n\n

\n

这是一个简单的应答服务器例子：\n\n

\n
var server = tls.createServer(options, function(socket) {\n  console.log('服务器已连接',\n              socket.authorized ? '已授权' : '未授权');\n  socket.write("欢迎！\\n");\n  socket.setEncoding('utf8');\n  socket.pipe(socket);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

Or\n\n

\n

或者\n\n

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

You can test this server by connecting to it with openssl s_client:\n\n

\n
var server = tls.createServer(options, function(socket) {\n  console.log('服务器已连接',\n              socket.authorized ? '已授权' : '未授权');\n  socket.write("欢迎！\\n");\n  socket.setEncoding('utf8');\n  socket.pipe(socket);\n});\nserver.listen(8000, function() {\n  console.log('服务器已绑定');\n});
\n

您可以使用 openssl s_client 连接这个服务器来测试：\n\n

\n
openssl s_client -connect 127.0.0.1:8000
\n", "signatures": [ { "params": [ { "name": "options" }, { "name": "secureConnectionListener", "optional": true } ] } ] }, { "textRaw": "tls.connect(options, [callback])", "type": "method", "name": "connect", "desc": "

Creates a new client connection to the given port and host (old API) or\noptions.port and options.host. (If host is omitted, it defaults to\nlocalhost.) options should be an object which specifies:\n\n

\n\n

The callback parameter will be added as a listener for the\n['secureConnect'][] event.\n\n

\n

callback参数会被作为监听器添加到['secureConnect'][]事件。\n\n

\n

tls.connect() returns a [tls.TLSSocket][] object.\n\n

\n

tls.connect()返回一个[tls.TLSSocket][]对象。\n\n

\n

Here is an example of a client of echo server as described previously:\n\n

\n

下面是一个上述应答服务器的客户端的例子：\n\n

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

Or\n\n

\n

或者\n\n

\n
var socket = tls.connect(8000, options, function() {\n  console.log('client connected',\n              socket.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(socket);\n  process.stdin.resume();\n});\nsocket.setEncoding('utf8');\nsocket.on('data', function(data) {\n  console.log(data);\n});\nsocket.on('end', function() {\n  server.close();\n});
\n", "signatures": [ { "params": [ { "name": "port" }, { "name": "host", "optional": true }, { "name": "options", "optional": true }, { "name": "callback", "optional": true } ] }, { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ] }, { "textRaw": "tls.connect(port, [host], [options], [callback])", "type": "method", "name": "connect", "desc": "

Creates a new client connection to the given port and host (old API) or\noptions.port and options.host. (If host is omitted, it defaults to\nlocalhost.) options should be an object which specifies:\n\n

\n\n

The callback parameter will be added as a listener for the\n['secureConnect'][] event.\n\n

\n

callback参数会被作为监听器添加到['secureConnect'][]事件。\n\n

\n

tls.connect() returns a [tls.TLSSocket][] object.\n\n

\n

tls.connect()返回一个[tls.TLSSocket][]对象。\n\n

\n

Here is an example of a client of echo server as described previously:\n\n

\n

下面是一个上述应答服务器的客户端的例子：\n\n

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

Or\n\n

\n

或者\n\n

\n
var socket = tls.connect(8000, options, function() {\n  console.log('client connected',\n              socket.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(socket);\n  process.stdin.resume();\n});\nsocket.setEncoding('utf8');\nsocket.on('data', function(data) {\n  console.log(data);\n});\nsocket.on('end', function() {\n  server.close();\n});
\n", "signatures": [ { "params": [ { "name": "port" }, { "name": "host", "optional": true }, { "name": "options", "optional": true }, { "name": "callback", "optional": true } ] } ] }, { "textRaw": "new tls.TLSSocket(socket, options)", "type": "method", "name": "TLSSocket", "desc": "

Construct a new TLSSocket object from existing TCP socket.\n\n

\n

socket is an instance of [net.Socket][]\n\n

\n

socket是一个[net.Socket][]示例。\n\n

\n

options is an object that might contain following properties:\n\n

\n

options是一个可能包含以下属性的对象：\n\n

\n\n", "signatures": [ { "params": [ { "name": "socket" }, { "name": "options" } ] } ] }, { "textRaw": "tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])", "type": "method", "name": "createSecurePair", "desc": "
稳定性: 0 - 已废弃。使用 tls.TLSSocket 替代。
\n

Creates a new secure pair object with two streams, one of which reads/writes\nencrypted data, and one reads/writes cleartext data.\nGenerally the encrypted one is piped to/from an incoming encrypted data stream,\nand the cleartext one is used as a replacement for the initial encrypted stream.\n\n

\n\n

tls.createSecurePair() returns a SecurePair object with cleartext and\nencrypted stream properties.\n\n

\n

NOTE: cleartext has the same APIs as [tls.TLSSocket][]\n\n

\n", "signatures": [ { "params": [ { "name": "credentials", "optional": true }, { "name": "isServer", "optional": true }, { "name": "requestCert", "optional": true }, { "name": "rejectUnauthorized", "optional": true } ] } ] } ], "properties": [ { "textRaw": "类: tls.TLSSocket", "name": "TLSSocket", "desc": "

Wrapper for instance of [net.Socket][], replaces internal socket read/write\nroutines to perform transparent encryption/decryption of incoming/outgoing data.\n\n

\n" }, { "textRaw": "类: tls.Server", "name": "Server", "desc": "

This class is a subclass of net.Server and has the same methods on it.\nInstead of accepting just raw TCP connections, this accepts encrypted\nconnections using TLS or SSL.\n\n

\n", "modules": [ { "textRaw": "事件: 'secureConnection'", "name": "事件:_'secureconnection'", "desc": "

function (tlsSocket) {}\n\n

\n

function (tlsSocket) {}\n\n

\n

This event is emitted after a new connection has been successfully\nhandshaked. The argument is a instance of [tls.TLSSocket][]. It has all the\ncommon stream methods and events.\n\n

\n

socket.authorized is a boolean value which indicates if the\nclient has verified by one of the supplied certificate authorities for the\nserver. If socket.authorized is false, then\nsocket.authorizationError is set to describe how authorization\nfailed. Implied but worth mentioning: depending on the settings of the TLS\nserver, you unauthorized connections may be accepted.\nsocket.npnProtocol is a string containing selected NPN protocol.\nsocket.servername is a string containing servername requested with\nSNI.\n\n

\n", "type": "module", "displayName": "事件: 'secureConnection'" }, { "textRaw": "事件: 'newSession'", "name": "事件:_'newsession'", "desc": "

function (sessionId, sessionData) { }\n\n

\n

function (sessionId, sessionData) { }\n\n

\n

Emitted on creation of TLS session. May be used to store sessions in external\nstorage.\n\n

\n

NOTE: adding this event listener will have an effect only on connections\nestablished after addition of event listener.\n\n

\n", "type": "module", "displayName": "事件: 'newSession'" }, { "textRaw": "事件: 'resumeSession'", "name": "事件:_'resumesession'", "desc": "

function (sessionId, callback) { }\n\n

\n

function (sessionId, callback) { }\n\n

\n

Emitted when client wants to resume previous TLS session. Event listener may\nperform lookup in external storage using given sessionId, and invoke\ncallback(null, sessionData) once finished. If session can't be resumed\n(i.e. doesn't exist in storage) one may call callback(null, null). Calling\ncallback(err) will terminate incoming connection and destroy socket.\n\n

\n

NOTE: adding this event listener will have an effect only on connections\nestablished after addition of event listener.\n\n

\n", "type": "module", "displayName": "事件: 'resumeSession'" } ], "events": [ { "textRaw": "Event: 'clientError'", "type": "event", "name": "clientError", "desc": "

function (exception, tlsSocket) { }\n\n

\n

function (exception, tlsSocket) { }\n\n

\n

When a client connection emits an 'error' event before secure connection is\nestablished - it will be forwarded here.\n\n

\n

tlsSocket is the [tls.TLSSocket][] that the error originated from.\n\n

\n", "params": [] } ], "methods": [ { "textRaw": "server.listen(port, [host], [callback])", "type": "method", "name": "listen", "desc": "

Begin accepting connections on the specified port and host. If the\nhost is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

This function is asynchronous. The last parameter callback will be called\nwhen the server has been bound.\n\n

\n

See net.Server for more information.\n\n

\n

更多信息见net.Server。\n\n

\n", "signatures": [ { "params": [ { "name": "port" }, { "name": "host", "optional": true }, { "name": "callback", "optional": true } ] } ] }, { "textRaw": "server.close()", "type": "method", "name": "close", "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "server.address()", "type": "method", "name": "address", "desc": "

Returns the bound address, the address family name and port of the\nserver as reported by the operating system. See [net.Server.address()][] for\nmore information.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "server.addContext(hostname, credentials)", "type": "method", "name": "addContext", "desc": "

Add secure context that will be used if client request's SNI hostname is\nmatching passed hostname (wildcards can be used). credentials can contain\nkey, cert and ca.\n\n

\n", "signatures": [ { "params": [ { "name": "hostname" }, { "name": "credentials" } ] } ] } ], "properties": [ { "textRaw": "server.maxConnections", "name": "maxConnections", "desc": "

Set this property to reject connections when the server's connection count\ngets high.\n\n

\n" }, { "textRaw": "server.connections", "name": "connections", "desc": "

The number of concurrent connections on the server.\n\n

\n

服务器的并发连接数.\n\n

\n" } ] }, { "textRaw": "类: tls.TLSSocket", "name": "TLSSocket", "desc": "

This is a wrapped version of [net.Socket][] that does transparent encryption\nof written data and all required TLS negotiation.\n\n

\n

This instance implements a duplex [Stream][] interfaces. It has all the\ncommon stream methods and events.\n\n

\n", "modules": [ { "textRaw": "事件: 'secureConnect'", "name": "事件:_'secureconnect'", "desc": "

This event is emitted after a new connection has been successfully handshaked.\nThe listener will be called no matter if the server's certificate was\nauthorized or not. It is up to the user to test tlsSocket.authorized\nto see if the server certificate was signed by one of the specified CAs.\nIf tlsSocket.authorized === false then the error can be found in\ntlsSocket.authorizationError. Also if NPN was used - you can check\ntlsSocket.npnProtocol for negotiated protocol.\n\n

\n", "type": "module", "displayName": "事件: 'secureConnect'" } ], "properties": [ { "textRaw": "tlsSocket.authorized", "name": "authorized", "desc": "

A boolean that is true if the peer certificate was signed by one of the\nspecified CAs, otherwise false\n\n

\n" }, { "textRaw": "tlsSocket.authorizationError", "name": "authorizationError", "desc": "

The reason why the peer's certificate has not been verified. This property\nbecomes available only when tlsSocket.authorized === false.\n\n

\n" }, { "textRaw": "tlsSocket.remoteAddress", "name": "remoteAddress", "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n

远程IP地址的字符串表示。例如，'74.125.127.100'或 '2001:4860:a005::68'。\n\n

\n" }, { "textRaw": "tlsSocket.remotePort", "name": "remotePort", "desc": "

The numeric representation of the remote port. For example, 443.\n\n

\n

远程端口的数值表示。例如， 443。\n\n

\n" }, { "textRaw": "tlsSocket.localAddress", "name": "localAddress", "desc": "

The string representation of the local IP address.\n\n

\n

本地IP地址的字符串表达。\n\n

\n" }, { "textRaw": "tlsSocket.localPort", "name": "localPort", "desc": "

The numeric representation of the local port.\n\n

\n

本地端口的数值表示。\n\n

\n" } ], "methods": [ { "textRaw": "tlsSocket.getPeerCertificate()", "type": "method", "name": "getPeerCertificate", "desc": "

Returns an object representing the peer's certificate. The returned object has\nsome properties corresponding to the field of the certificate.\n\n

\n

Example:\n\n

\n

示例：\n\n

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

If the peer does not provide a certificate, it returns null or an empty\nobject.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "tlsSocket.getCipher()", "type": "method", "name": "getCipher", "desc": "

Returns an object representing the cipher name and the SSL/TLS\nprotocol version of the current connection.\n\n

\n

Example:\n{ name: 'AES256-SHA', version: 'TLSv1/SSLv3' }\n\n

\n

Example:\n{ name: 'AES256-SHA', version: 'TLSv1/SSLv3' }\n\n

\n

See SSL_CIPHER_get_name() and SSL_CIPHER_get_version() in\nhttp://www.openssl.org/docs/ssl/ssl.html#DEALING_WITH_CIPHERS for more\ninformation.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "tlsSocket.renegotiate(options, callback)", "type": "method", "name": "renegotiate", "desc": "

Initiate TLS renegotiation process. The options may contain the following\nfields: rejectUnauthorized, requestCert (See [tls.createServer][]\nfor details). callback(err) will be executed with null as err,\nonce the renegotiation is successfully completed.\n\n

\n

NOTE: Can be used to request peer's certificate after the secure connection\nhas been established.\n\n

\n

ANOTHER NOTE: When running as the server, socket will be destroyed\nwith an error after handshakeTimeout timeout.\n\n

\n", "signatures": [ { "params": [ { "name": "options" }, { "name": "callback" } ] } ] }, { "textRaw": "tlsSocket.address()", "type": "method", "name": "address", "desc": "

Returns the bound address, the address family name and port of the\nunderlying socket as reported by the operating system. Returns an\nobject with three properties, e.g.\n{ port: 12346, family: 'IPv4', address: '127.0.0.1' }\n\n

\n", "signatures": [ { "params": [] } ] } ] } ], "modules": [ { "textRaw": "类: SecurePair", "name": "类:_securepair", "desc": "

Returned by tls.createSecurePair.\n\n

\n

由tls.createSecurePair返回。\n\n

\n", "modules": [ { "textRaw": "事件: 'secure'", "name": "事件:_'secure'", "desc": "

The event is emitted from the SecurePair once the pair has successfully\nestablished a secure connection.\n\n

\n

Similarly to the checking for the server 'secureConnection' event,\npair.cleartext.authorized should be checked to confirm whether the certificate\nused properly authorized.\n\n

\n", "type": "module", "displayName": "事件: 'secure'" } ], "type": "module", "displayName": "类: SecurePair" }, { "textRaw": "类: CryptoStream", "name": "类:_cryptostream", "desc": "
稳定性: 0 - 已废弃。使用 tls.TLSSocket 替代。
\n

This is an encrypted stream.\n\n

\n

这是一个被加密的流。\n\n

\n", "properties": [ { "textRaw": "cryptoStream.bytesWritten", "name": "bytesWritten", "desc": "

A proxy to the underlying socket's bytesWritten accessor, this will return\nthe total bytes written to the socket, including the TLS overhead.\n\n

\n" } ], "type": "module", "displayName": "类: CryptoStream" } ], "type": "module", "displayName": "TLS (SSL)" } ] }