TLS (SSL) · Node.js 中文API文檔 0.10.18

# TLS (SSL) ~~~ 穩定度: 3 - 穩定 ~~~ 使用 `require('tls')` 來訪問此模塊。 `tls` 模塊使用 OpenSSL 來提供傳輸層安全協議（Transport Layer Security）和/或安全套接層（Secure Socket Layer）：加密過的流通訊。 TLS/SSL 是一種公鑰/私鑰架構。每個客戶端和服務器都必有一個私鑰。一個私鑰使用類似的方式創建： ~~~ openssl genrsa -out ryans-key.pem 1024 ~~~ 所有服務器和某些客戶端需要具備證書。證書是證書辦法機構簽發或自簽發的公鑰。獲取證書的第一步是創建一個“證書簽發申請”（CSR）文件。使用這條命令完成： ~~~ openssl req -new -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 發送給一個數字證書認證機構請求簽名。 (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`: certificate - `inkey`: private key - `certfile`: all CA certs concatenated in one file like `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem` ### 客戶端初始化的對緩解攻擊的重新協商 TLS協議會令客戶端可以重新協商TLS會話的某些方面。但是，會話的重新協商是需要相應量的服務器端資源的，所以導致其變成一個阻斷服務攻擊（denial-of-service）的潛在媒介。為了減低這種情況的發生，重新協商被限制在每10分鐘三次。如果超過這個數目，那么在[tls.TLSSocket](#)實例上就會分發一個錯誤。這個限制是可設置的： - `tls.CLIENT_RENEG_LIMIT`: 重新協商的次數限制，默認為3。 - `tls.CLIENT_RENEG_WINDOW`: 重新協商窗口的秒數，默認為600（10分鐘）。除非你完全理解整個機制和清楚自己要干什么，否則不要改變這個默認值。要測試你的服務器的話，用命令 `openssl s_client -connect 地址:端口`連接上服務器，然后敲擊`R<CR>`（字母鍵`R`加回車鍵）幾次。 ### NPN 和 SNI NPN (Next Protocol Negotiation，下一個協議的協商)和SNI (Server Name Indication，服務器名稱指示)是TLS握手擴展，它們允許你： - NPN - 同一個TLS服務器使用多種協議 (HTTP, SPDY) - SNI - 同一個TLS服務器使用多個主機名，與其相應的SSL證書。 ### tls.getCiphers() 返回一個數組，其中包含了所支持的SSL加密器的名字。實例： ~~~ var ciphers = tls.getCiphers(); console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...] ~~~ ### tls.createServer(options, [secureConnectionListener]) 新建一個新的 [tls.Server](#). The `connectionListener` 參數會自動設置為 [secureConnection](#) 事件的監聽器. 這個 `options` 對象有這些可能性: - `pfx`: 一個String 或`Buffer`包含了私鑰, 證書和CA certs, 一般是 PFX 或者 PKCS12 格式. (Mutually exclusive with the `key`, `cert` and `ca` options.) - `key`: 一個字符串或 `Buffer`對象，其中包含了PEF格式的服務器的私鑰。 (必需) - `passphrase`: 私鑰或pfx密碼的字符串。 - `cert`: 字符串或者 `Buffer`，包含PEM格式的服務器證書密碼。（必選） - `ca`: An array of strings or `Buffer`s of trusted certificates. If this is omitted several well known "root" CAs will be used, like VeriSign. These are used to authorize connections. - `crl` : Either a string or list of strings of PEM encoded CRLs (Certificate Revocation List) - `ciphers`: 一個字符串，描述了使用或排除的cipher。 ~~~ **NOTE**: Previous revisions of this section suggested `AES256-SHA` as an acceptable cipher. Unfortunately, `AES256-SHA` is a CBC cipher and therefore susceptible to BEAST attacks. Do *not* use it. ~~~ - `handshakeTimeout`: Abort the connection if the SSL/TLS handshake does not finish in this many milliseconds. The default is 120 seconds. ~~~ `tls.Server`對象在握手超時時，總會觸發`'clientError'`事件。 ~~~ - `honorCipherOrder` : 當選擇cipher時，使用服務器設置，而不是客戶端設置。 ~~~ Although, this option is disabled by default, it is *recommended* that you use this option in conjunction with the `ciphers` option to mitigate BEAST attacks. ~~~ - `requestCert`: If `true` the server will request a certificate from clients that connect and attempt to verify that certificate. Default: `false`. - `rejectUnauthorized`: If `true` the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if `requestCert` is `true`. Default: `false`. - `NPNProtocols`: 一個數組或 `Buffer`，包含了可能的 NPN 協議。(協議應根據優先級排序） - `SNICallback(servername, cb)`: A function that will be called if client supports SNI TLS extension. Two argument will be passed to it: `servername`, and `cb`. `SNICallback` should invoke `cb(null, ctx)`, where `ctx` is a SecureContext instance. (You can use `crypto.createCredentials(...).context` to get proper SecureContext). If `SNICallback` wasn't provided - default callback with high-level API will be used (see below). - `sessionTimeout`: An integer specifying the seconds after which TLS session identifiers and TLS session tickets created by the server are timed out. See [SSL_CTX_set_timeout](http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html) for more details. - `sessionIdContext`: A string containing a opaque identifier for session resumption. If `requestCert` is `true`, the default is MD5 hash value generated from command-line. Otherwise, the default is not provided. - `secureProtocol`: The SSL method to use, e.g. `SSLv3_method` to force SSL version 3. The possible values depend on your installation of OpenSSL and are defined in the constant [SSL_METHODS](http://www.openssl.org/docs/ssl/ssl.html#DEALING_WITH_PROTOCOL_METHODS). 這是一個簡單的應答服務器例子： ~~~ var server = tls.createServer(options, function(socket) { console.log('服務器已連接', socket.authorized ? '已授權' : '未授權'); socket.write("歡迎！\n"); socket.setEncoding('utf8'); socket.pipe(socket); }); server.listen(8000, function() { console.log('server bound'); }); ~~~ 或者 ~~~ }; ~~~ ~~~ var server = tls.createServer(options, function(socket) { console.log('服務器已連接', socket.authorized ? '已授權' : '未授權'); socket.write("歡迎！\n"); socket.setEncoding('utf8'); socket.pipe(socket); }); server.listen(8000, function() { console.log('服務器已綁定'); }); ~~~ 您可以使用 `openssl s_client` 連接這個服務器來測試： ~~~ openssl s_client -connect 127.0.0.1:8000 ~~~ ### tls.connect(options, [callback]) ### tls.connect(port, [host], [options], [callback]) Creates a new client connection to the given `port` and `host` (old API) or `options.port` and `options.host`. (If `host` is omitted, it defaults to `localhost`.) `options` should be an object which specifies: - `host`: 客戶端應連接到的主機 - `port`: 客戶端應連接到的端口 - `socket`: Establish secure connection on a given socket rather than creating a new socket. If this option is specified, `host` and `port` are ignored. - `pfx`: 字符串或者 `Buffer`，包含 PFX 或 PKCS12 格式的服務器私鑰、證書和CA證書。 - `key`: 字符串或 `Buffer`，包含 PEM 格式的客戶端私鑰。 - `passphrase`: 私鑰或pfx密碼的字符串。 - `cert`: 字符串或 `Buffer`，包含PEM格式的客戶端證書密碼。 - `ca`: An array of strings or `Buffer`s of trusted certificates. If this is omitted several well known "root" CAs will be used, like VeriSign. These are used to authorize connections. - `rejectUnauthorized`: If `true`, the server certificate is verified against the list of supplied CAs. An `'error'` event is emitted if verification fails. Default: `true`. - `NPNProtocols`: An array of string or `Buffer` containing supported NPN protocols. `Buffer` should have following format: `0x05hello0x05world`, where first byte is next protocol name's length. (Passing array should usually be much simpler: `['hello', 'world']`.) - `servername`: SNI (Server Name Indication) TLS 擴展的服務器名。 - `secureProtocol`: The SSL method to use, e.g. `SSLv3_method` to force SSL version 3. The possible values depend on your installation of OpenSSL and are defined in the constant [SSL_METHODS](http://www.openssl.org/docs/ssl/ssl.html#DEALING_WITH_PROTOCOL_METHODS). `callback`參數會被作為監聽器添加到['secureConnect'](#)事件。 `tls.connect()`返回一個[tls.TLSSocket](#)對象。下面是一個上述應答服務器的客戶端的例子： ~~~ 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 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(); }); ~~~ ### Class: tls.TLSSocket Wrapper for instance of [net.Socket](#), replaces internal socket read/write routines to perform transparent encryption/decryption of incoming/outgoing data. ### new tls.TLSSocket(socket, options) Construct a new TLSSocket object from existing TCP socket. `socket`是一個[net.Socket](#)示例。 `options`是一個可能包含以下屬性的對象： - `credentials`: 可選的，通過`crypto.createCredentials( ... )`得到的資格對象。 - `isServer`: 如果為真——TLS套接字將在服務器模式下實例化。 - `server`: 一個可選的[net.Server](#)實例 - `requestCert`: 可選的，見[tls.createSecurePair](#) - `rejectUnauthorized`: 可選的，見[tls.createSecurePair](#) - `NPNProtocols`: 可選的，見[tls.createServer](#) - `SNICallback`: 可選的，見[tls.createServer](#) ### tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized]) ~~~ 穩定性: 0 - 已廢棄。使用 tls.TLSSocket 替代。 ~~~ Creates a new secure pair object with two streams, one of which reads/writes encrypted data, and one reads/writes cleartext data. Generally the encrypted one is piped to/from an incoming encrypted data stream, and the cleartext one is used as a replacement for the initial encrypted stream. - `credentials`: 通過`crypto.createCredentials( ... )`得到的資格對象 - `isServer`: A boolean indicating whether this tls connection should be opened as a server or a client. - `requestCert`: A boolean indicating whether a server should request a certificate from a connecting client. Only applies to server connections. - `rejectUnauthorized`: A boolean indicating whether a server should automatically reject clients with invalid certificates. Only applies to servers with `requestCert` enabled. `tls.createSecurePair()` returns a SecurePair object with `cleartext` and `encrypted` stream properties. NOTE: `cleartext` has the same APIs as [tls.TLSSocket](#) ### 類: SecurePair 由tls.createSecurePair返回。 ### 事件: 'secure' The event is emitted from the SecurePair once the pair has successfully established a secure connection. Similarly to the checking for the server 'secureConnection' event, pair.cleartext.authorized should be checked to confirm whether the certificate used properly authorized. ### 類: tls.Server This class is a subclass of `net.Server` and has the same methods on it. Instead of accepting just raw TCP connections, this accepts encrypted connections using TLS or SSL. ### 事件: 'secureConnection' `function (tlsSocket) {}` This event is emitted after a new connection has been successfully handshaked. The argument is a instance of [tls.TLSSocket](#). It has all the common stream methods and events. `socket.authorized` is a boolean value which indicates if the client has verified by one of the supplied certificate authorities for the server. If `socket.authorized` is false, then `socket.authorizationError` is set to describe how authorization failed. Implied but worth mentioning: depending on the settings of the TLS server, you unauthorized connections may be accepted. `socket.npnProtocol` is a string containing selected NPN protocol. `socket.servername` is a string containing servername requested with SNI. ### Event: 'clientError' `function (exception, tlsSocket) { }` When a client connection emits an 'error' event before secure connection is established - it will be forwarded here. `tlsSocket`就是`[tls.TLSSocket][]`，錯誤產生的地方。 ### 事件: 'newSession' `function (sessionId, sessionData) { }` Emitted on creation of TLS session. May be used to store sessions in external storage. NOTE: adding this event listener will have an effect only on connections established after addition of event listener. ### 事件: 'resumeSession' `function (sessionId, callback) { }` Emitted when client wants to resume previous TLS session. Event listener may perform lookup in external storage using given `sessionId`, and invoke `callback(null, sessionData)` once finished. If session can't be resumed (i.e. doesn't exist in storage) one may call `callback(null, null)`. Calling `callback(err)` will terminate incoming connection and destroy socket. NOTE: adding this event listener will have an effect only on connections established after addition of event listener. ### server.listen(port, [host], [callback]) Begin accepting connections on the specified `port` and `host`. If the `host` is omitted, the server will accept connections directed to any IPv4 address (`INADDR_ANY`). This function is asynchronous. The last parameter `callback` will be called when the server has been bound. 更多信息見`net.Server`。 ### server.close() Stops the server from accepting new connections. This function is asynchronous, the server is finally closed when the server emits a `'close'` event. ### server.address() Returns the bound address, the address family name and port of the server as reported by the operating system. See [net.Server.address()](#) for more information. ### server.addContext(hostname, credentials) Add secure context that will be used if client request's SNI hostname is matching passed `hostname` (wildcards can be used). `credentials` can contain `key`, `cert` and `ca`. ### server.maxConnections Set this property to reject connections when the server's connection count gets high. ### server.connections 服務器的并發連接數. ### 類: CryptoStream ~~~ 穩定性: 0 - 已廢棄。使用 tls.TLSSocket 替代。 ~~~ 這是一個被加密的流。 ### cryptoStream.bytesWritten A proxy to the underlying socket's bytesWritten accessor, this will return the total bytes written to the socket, *including the TLS overhead*. ### Class: tls.TLSSocket This is a wrapped version of [net.Socket](#) that does transparent encryption of written data and all required TLS negotiation. This instance implements a duplex [Stream](#) interfaces. It has all the common stream methods and events. ### 事件: 'secureConnect' This event is emitted after a new connection has been successfully handshaked. The listener will be called no matter if the server's certificate was authorized or not. It is up to the user to test `tlsSocket.authorized` to see if the server certificate was signed by one of the specified CAs. If `tlsSocket.authorized === false` then the error can be found in `tlsSocket.authorizationError`. Also if NPN was used - you can check `tlsSocket.npnProtocol` for negotiated protocol. ### tlsSocket.authorized A boolean that is `true` if the peer certificate was signed by one of the specified CAs, otherwise `false` ### tlsSocket.authorizationError The reason why the peer's certificate has not been verified. This property becomes available only when `tlsSocket.authorized === false`. ### tlsSocket.getPeerCertificate() Returns an object representing the peer's certificate. The returned object has some properties corresponding to the field of the certificate. 實例： ~~~ { subject: { C: 'UK', ST: 'Acknack Ltd', L: 'Rhys Jones', O: 'node.js', OU: 'Test TLS Certificate', CN: 'localhost' }, issuer: { C: 'UK', ST: 'Acknack Ltd', L: 'Rhys Jones', O: 'node.js', OU: 'Test TLS Certificate', CN: 'localhost' }, 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' } ~~~ 如果節點沒有提供證書, 它將返回 `null` 或者一個空對象. ### tlsSocket.getCipher() 返回一個對象，表示了當前連接的cipher名與SSL/TLS協議版本。 Example: { name: 'AES256-SHA', version: 'TLSv1/SSLv3' } See SSL_CIPHER_get_name() and SSL_CIPHER_get_version() in [http://www.openssl.org/docs/ssl/ssl.html#DEALING_WITH_CIPHERS](http://www.openssl.org/docs/ssl/ssl.html#DEALING_WITH_CIPHERS) for more information. ### tlsSocket.renegotiate(options, callback) Initiate TLS renegotiation process. The `options` may contain the following fields: `rejectUnauthorized`, `requestCert` (See [tls.createServer](#) for details). `callback(err)` will be executed with `null` as `err`, once the renegotiation is successfully completed. NOTE: Can be used to request peer's certificate after the secure connection has been established. ANOTHER NOTE: When running as the server, socket will be destroyed with an error after `handshakeTimeout` timeout. ### tlsSocket.address() Returns the bound address, the address family name and port of the underlying socket as reported by the operating system. Returns an object with three properties, e.g. `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` ### tlsSocket.remoteAddress 遠程IP地址的字符串表示。例如，`'74.125.127.100'`或 `'2001:4860:a005::68'`。 ### tlsSocket.remotePort 遠程端口的數值表示。例如， `443`。 ### tlsSocket.localAddress 本地IP地址的字符串表達。 ### tlsSocket.localPort 本地端口的數值表示。