From f8390fdd7528e4c1863ee1e40eda8f9b1dbd23e6 Mon Sep 17 00:00:00 2001 From: Tristian Flanagan Date: Thu, 5 Nov 2015 15:04:26 -0500 Subject: [PATCH] doc: sort tls alphabetically Reorders, with no contextual changes, the tls documentation alphabetically. PR-URL: https://github.com/nodejs/node/pull/3662 Reviewed-By: Evan Lucas Reviewed-By: James M Snell Reviewed-By: Jeremiah Senkpiel --- doc/api/tls.markdown | 1187 +++++++++++++++++++++--------------------- 1 file changed, 587 insertions(+), 600 deletions(-) diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index f105614962..7f21276c54 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -40,6 +40,17 @@ To create .pfx or .p12, do this: - `certfile`: all CA certs concatenated in one file like `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem` +## ALPN, NPN and SNI + + + +ALPN (Application-Layer Protocol Negotiation Extension), NPN (Next +Protocol Negotiation) and SNI (Server Name Indication) are TLS +handshake extensions allowing you: + + * ALPN/NPN - to use one TLS server for multiple protocols (HTTP, SPDY, HTTP/2) + * SNI - to use one TLS server for multiple hostnames with different SSL + certificates. ## Client-initiated renegotiation attack mitigation @@ -65,19 +76,6 @@ To test your server, connect to it with `openssl s_client -connect address:port` and tap `R` (that's the letter `R` followed by a carriage return) a few times. - -## ALPN, NPN and SNI - - - -ALPN (Application-Layer Protocol Negotiation Extension), NPN (Next -Protocol Negotiation) and SNI (Server Name Indication) are TLS -handshake extensions allowing you: - - * ALPN/NPN - to use one TLS server for multiple protocols (HTTP, SPDY, HTTP/2) - * SNI - to use one TLS server for multiple hostnames with different SSL - certificates. - ## Modifying the Default TLS Cipher suite Node.js is built with a default suite of enabled and disabled TLS ciphers. @@ -141,16 +139,583 @@ the character "E" appended to the traditional abbreviations): Ephemeral methods may have some performance drawbacks, because key generation is expensive. +## Class: CryptoStream -## tls.getCiphers() + Stability: 0 - Deprecated: Use [tls.TLSSocket][] instead. -Returns an array with the names of the supported SSL ciphers. +This is an encrypted stream. + +### 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: SecurePair + +Returned by tls.createSecurePair. + +### Event: '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. + +## Class: 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. + +### Event: 'clientError' + +`function (exception, tlsSocket) { }` + +When a client connection emits an 'error' event before secure connection is +established - it will be forwarded here. + +`tlsSocket` is the [tls.TLSSocket][] that the error originated from. + +### Event: 'newSession' + +`function (sessionId, sessionData, callback) { }` + +Emitted on creation of TLS session. May be used to store sessions in external +storage. `callback` must be invoked eventually, otherwise no data will be +sent or received from secure connection. + +NOTE: adding this event listener will have an effect only on connections +established after addition of event listener. + +### Event: 'OCSPRequest' + +`function (certificate, issuer, callback) { }` + +Emitted when the client sends a certificate status request. You could parse +server's current certificate to obtain OCSP url and certificate id, and after +obtaining OCSP response invoke `callback(null, resp)`, where `resp` is a +`Buffer` instance. Both `certificate` and `issuer` are a `Buffer` +DER-representations of the primary and issuer's certificates. They could be used +to obtain OCSP certificate id and OCSP endpoint url. + +Alternatively, `callback(null, null)` could be called, meaning that there is no +OCSP response. + +Calling `callback(err)` will result in a `socket.destroy(err)` call. + +Typical flow: + +1. Client connects to server and sends `OCSPRequest` to it (via status info + extension in ClientHello.) +2. Server receives request and invokes `OCSPRequest` event listener if present +3. Server grabs OCSP url from either `certificate` or `issuer` and performs an + [OCSP request] to the CA +4. Server receives `OCSPResponse` from CA and sends it back to client via + `callback` argument +5. Client validates the response and either destroys socket or performs a + handshake. + +NOTE: `issuer` could be null, if the certificate is self-signed or if the issuer +is not in the root certificates list. (You could provide an issuer via `ca` +option.) + +NOTE: adding this event listener will have an effect only on connections +established after addition of event listener. + +NOTE: you may want to use some npm module like [asn1.js] to parse the +certificates. + +### Event: '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. + +Here's an example for using TLS session resumption: + + var tlsSessionStore = {}; + server.on('newSession', function(id, data, cb) { + tlsSessionStore[id.toString('hex')] = data; + cb(); + }); + server.on('resumeSession', function(id, cb) { + cb(null, tlsSessionStore[id.toString('hex')] || null); + }); + +### Event: 'secureConnection' + +`function (tlsSocket) {}` + +This event is emitted after a new connection has been successfully +handshaked. The argument is an 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 the selected NPN protocol +and `socket.alpnProtocol` is a string containing the selected ALPN +protocol, When both NPN and ALPN extensions are received, ALPN takes +precedence over NPN and the next protocol is selected by ALPN. When +ALPN has no selected protocol, this returns false. + +`socket.servername` is a string containing servername requested with +SNI. + +### server.addContext(hostname, context) + +Add secure context that will be used if client request's SNI hostname is +matching passed `hostname` (wildcards can be used). `context` can contain +`key`, `cert`, `ca` and/or any other properties from `tls.createSecureContext` +`options` argument. + +### 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.close([callback]) + +Stops the server from accepting new connections. This function is +asynchronous, the server is finally closed when the server emits a `'close'` +event. Optionally, you can pass a callback to listen for the `'close'` event. + +### server.connections + +The number of concurrent connections on the server. + +### server.getTicketKeys() + +Returns `Buffer` instance holding the keys currently used for +encryption/decryption of the [TLS Session Tickets][] + +### server.listen(port[, hostname][, callback]) + +Begin accepting connections on the specified `port` and `hostname`. If the +`hostname` is omitted, the server will accept connections on any IPv6 address +(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. A +port value of zero will assign a random port. + +This function is asynchronous. The last parameter `callback` will be called +when the server has been bound. + +See `net.Server` for more information. + +### server.setTicketKeys(keys) + +Updates the keys for encryption/decryption of the [TLS Session Tickets][]. + +NOTE: the buffer should be 48 bytes long. See server `ticketKeys` option for +more information oh how it is going to be used. + +NOTE: the change is effective only for the future server connections. Existing +or currently pending server connections will use previous keys. + +### server.maxConnections + +Set this property to reject connections when the server's connection count +gets high. + + +## 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. + +Methods that return TLS connection meta data (e.g. +[getPeerCertificate](#tlssocketgetpeercertificate-detailed-)) +will only return data while the connection is open. + +### new tls.TLSSocket(socket[, options]) + +Construct a new TLSSocket object from existing TCP socket. + +`socket` is an instance of [net.Socket][] + +`options` is an optional object that might contain following properties: + + - `secureContext`: An optional TLS context object from + `tls.createSecureContext( ... )` + + - `isServer`: If `true` - TLS socket will be instantiated in server-mode. + Default: `false` + + - `server`: An optional [net.Server][] instance + + - `requestCert`: Optional, see [tls.createSecurePair][] + + - `rejectUnauthorized`: Optional, see [tls.createSecurePair][] + + - `NPNProtocols`: Optional, see [tls.createServer][] + + - `ALPNProtocols`: Optional, see [tls.createServer][] + + - `SNICallback`: Optional, see [tls.createServer][] + + - `session`: Optional, a `Buffer` instance, containing TLS session + + - `requestOCSP`: Optional, if `true` - OCSP status request extension would + be added to client hello, and `OCSPResponse` event will be emitted on socket + before establishing secure communication + +### Event: 'OCSPResponse' + +`function (response) { }` + +This event will be emitted if `requestOCSP` option was set. `response` is a +buffer object, containing server's OCSP response. + +Traditionally, the `response` is a signed object from the server's CA that +contains information about server's certificate revocation status. + +### Event: '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 ALPN or NPN was used - you can +check `tlsSocket.alpnProtocol` or `tlsSocket.npnProtocol` for the +negotiated protocol. + +### 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.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.encrypted + +Static boolean value, always `true`. May be used to distinguish TLS sockets +from regular ones. + +### tlsSocket.getCipher() +Returns an object representing the cipher name and the SSL/TLS +protocol version of the current connection. + +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 for more +information. + +### tlsSocket.getEphemeralKeyInfo() + +Returns an object representing a type, name and size of parameter of +an ephemeral key exchange in [Perfect forward Secrecy][] on a client +connection. It returns an empty object when the key exchange is not +ephemeral. As it is only supported on a client socket, it returns null +if this is called on a server socket. The supported types are 'DH' and +'ECDH'. The `name` property is only available in 'ECDH'. Example: - var ciphers = tls.getCiphers(); - console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...] + { type: 'ECDH', name: 'prime256v1', size: 256 } +### tlsSocket.getPeerCertificate([ detailed ]) + +Returns an object representing the peer's certificate. The returned object has +some properties corresponding to the field of the certificate. If `detailed` +argument is `true` - the full chain with `issuer` property will be returned, +if `false` - only the top certificate without `issuer` property. + +Example: + + { 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' } + +If the peer does not provide a certificate, it returns `null` or an empty +object. + + +### tlsSocket.getSession() + +Return ASN.1 encoded TLS session or `undefined` if none was negotiated. Could +be used to speed up handshake establishment when reconnecting to the server. + +### tlsSocket.getTLSTicket() + +NOTE: Works only with client TLS sockets. Useful only for debugging, for +session reuse provide `session` option to `tls.connect`. + +Return TLS session ticket or `undefined` if none was negotiated. + +### tlsSocket.localAddress + +The string representation of the local IP address. + +### tlsSocket.localPort + +The numeric representation of the local port. + +### tlsSocket.remoteAddress + +The string representation of the remote IP address. For example, +`'74.125.127.100'` or `'2001:4860:a005::68'`. + +### tlsSocket.remoteFamily + +The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. + +### tlsSocket.remotePort + +The numeric representation of the remote port. For example, `443`. + +### 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.setMaxSendFragment(size) + +Set maximum TLS fragment size (default and maximum value is: `16384`, minimum +is: `512`). Returns `true` on success, `false` otherwise. + +Smaller fragment size decreases buffering latency on the client: large +fragments are buffered by the TLS layer until the entire fragment is received +and its integrity is verified; large fragments can span multiple roundtrips, +and their processing can be delayed due to packet loss or reordering. However, +smaller fragments add extra TLS framing bytes and CPU overhead, which may +decrease overall server throughput. + + +## 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`: Host the client should connect to + + - `port`: Port the client should connect to + + - `socket`: Establish secure connection on a given socket rather than + creating a new socket. If this option is specified, `host` and `port` + are ignored. + + - `path`: Creates unix socket connection to path. If this option is + specified, `host` and `port` are ignored. + + - `pfx`: A string or `Buffer` containing the private key, certificate and + CA certs of the client in PFX or PKCS12 format. + + - `key`: A string or `Buffer` containing the private key of the client in + PEM format. (Could be an array of keys). + + - `passphrase`: A string of passphrase for the private key or pfx. + + - `cert`: A string or `Buffer` containing the certificate key of the client in + PEM format. (Could be an array of certs). + + - `ca`: An array of strings or `Buffer`s of trusted certificates in PEM + format. If this is omitted several well known "root" CAs will be used, + like VeriSign. These are used to authorize connections. + + - `ciphers`: A string describing the ciphers to use or exclude, separated by + `:`. Uses the same default cipher suite as `tls.createServer`. + + - `rejectUnauthorized`: If `true`, the server certificate is verified against + the list of supplied CAs. An `'error'` event is emitted if verification + fails; `err.code` contains the OpenSSL error code. Default: `true`. + + - `NPNProtocols`: An array of strings or `Buffer`s containing supported NPN + protocols. `Buffer`s should have the following format: + `0x05hello0x05world`, where first byte is next protocol name's + length. (Passing array should usually be much simpler: + `['hello', 'world']`.) + + - `ALPNProtocols`: An array of strings or `Buffer`s containing + supported ALPN protocols. `Buffer`s should have following format: + `0x05hello0x05world`, where the first byte is the next protocol + name's length. (Passing array should usually be much simpler: + `['hello', 'world']`.) + + - `servername`: Servername for SNI (Server Name Indication) TLS extension. + + - `checkServerIdentity(servername, cert)`: Provide an override for checking + server's hostname against the certificate. Should return an error if verification + fails. Return `undefined` if passing. + + - `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][]. + + - `session`: A `Buffer` instance, containing TLS session. + + - `minDHSize`: Minimum size of DH parameter in bits to accept a TLS + connection. When a server offers DH parameter with a size less + than this, the TLS connection is destroyed and throws an + error. Default: 1024. + +The `callback` parameter will be added as a listener for the +['secureConnect'][] event. + +`tls.connect()` returns a [tls.TLSSocket][] object. + +Here is an example of a client of echo server as described previously: + + 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(); + }); + +Or + + 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.createSecureContext(details) + +Creates a credentials object, with the optional details being a +dictionary with keys: + +* `pfx` : A string or buffer holding the PFX or PKCS12 encoded private + key, certificate and CA certificates +* `key`: A string or `Buffer` containing the private key of the server in + PEM format. To support multiple keys using different algorithms, an array + can be provided. It can either be a plain array of keys, or an array of + objects in the format `{pem: key, passphrase: passphrase}`. (Required) +* `passphrase` : A string of passphrase for the private key or pfx +* `cert` : A string holding the PEM encoded certificate +* `ca` : Either a string or list of strings of PEM encoded CA + certificates to trust. +* `crl` : Either a string or list of strings of PEM encoded CRLs + (Certificate Revocation List) +* `ciphers`: A string describing the ciphers to use or exclude. + Consult + + for details on the format. +* `honorCipherOrder` : When choosing a cipher, use the server's preferences + instead of the client preferences. For further details see `tls` module + documentation. + +If no 'ca' details are given, then Node.js will use the default +publicly trusted list of CAs as given in +. + +## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options]) + +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`: A secure context object from tls.createSecureContext( ... ) + + - `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. + + - `options`: An object with common SSL options. See [tls.TLSSocket][]. + +`tls.createSecurePair()` returns a SecurePair object with `cleartext` and +`encrypted` stream properties. + +NOTE: `cleartext` has the same APIs as [tls.TLSSocket][] ## tls.createServer(options[, secureConnectionListener]) @@ -338,594 +903,16 @@ You can test this server by connecting to it with `openssl s_client`: openssl s_client -connect 127.0.0.1:8000 + +## tls.getCiphers() - -## 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`: Host the client should connect to - - - `port`: Port the client should connect to - - - `socket`: Establish secure connection on a given socket rather than - creating a new socket. If this option is specified, `host` and `port` - are ignored. - - - `path`: Creates unix socket connection to path. If this option is - specified, `host` and `port` are ignored. - - - `pfx`: A string or `Buffer` containing the private key, certificate and - CA certs of the client in PFX or PKCS12 format. - - - `key`: A string or `Buffer` containing the private key of the client in - PEM format. (Could be an array of keys). - - - `passphrase`: A string of passphrase for the private key or pfx. - - - `cert`: A string or `Buffer` containing the certificate key of the client in - PEM format. (Could be an array of certs). - - - `ca`: An array of strings or `Buffer`s of trusted certificates in PEM - format. If this is omitted several well known "root" CAs will be used, - like VeriSign. These are used to authorize connections. - - - `ciphers`: A string describing the ciphers to use or exclude, separated by - `:`. Uses the same default cipher suite as `tls.createServer`. - - - `rejectUnauthorized`: If `true`, the server certificate is verified against - the list of supplied CAs. An `'error'` event is emitted if verification - fails; `err.code` contains the OpenSSL error code. Default: `true`. - - - `NPNProtocols`: An array of strings or `Buffer`s containing supported NPN - protocols. `Buffer`s should have the following format: - `0x05hello0x05world`, where first byte is next protocol name's - length. (Passing array should usually be much simpler: - `['hello', 'world']`.) - - - `ALPNProtocols`: An array of strings or `Buffer`s containing - supported ALPN protocols. `Buffer`s should have following format: - `0x05hello0x05world`, where the first byte is the next protocol - name's length. (Passing array should usually be much simpler: - `['hello', 'world']`.) - - - `servername`: Servername for SNI (Server Name Indication) TLS extension. - - - `checkServerIdentity(servername, cert)`: Provide an override for checking - server's hostname against the certificate. Should return an error if verification - fails. Return `undefined` if passing. - - - `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][]. - - - `session`: A `Buffer` instance, containing TLS session. - - - `minDHSize`: Minimum size of DH parameter in bits to accept a TLS - connection. When a server offers DH parameter with a size less - than this, the TLS connection is destroyed and throws an - error. Default: 1024. - -The `callback` parameter will be added as a listener for the -['secureConnect'][] event. - -`tls.connect()` returns a [tls.TLSSocket][] object. - -Here is an example of a client of echo server as described previously: - - 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(); - }); - -Or - - 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(); - }); - -## 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` is an instance of [net.Socket][] - -`options` is an optional object that might contain following properties: - - - `secureContext`: An optional TLS context object from - `tls.createSecureContext( ... )` - - - `isServer`: If `true` - TLS socket will be instantiated in server-mode. - Default: `false` - - - `server`: An optional [net.Server][] instance - - - `requestCert`: Optional, see [tls.createSecurePair][] - - - `rejectUnauthorized`: Optional, see [tls.createSecurePair][] - - - `NPNProtocols`: Optional, see [tls.createServer][] - - - `ALPNProtocols`: Optional, see [tls.createServer][] - - - `SNICallback`: Optional, see [tls.createServer][] - - - `session`: Optional, a `Buffer` instance, containing TLS session - - - `requestOCSP`: Optional, if `true` - OCSP status request extension would - be added to client hello, and `OCSPResponse` event will be emitted on socket - before establishing secure communication - - -## tls.createSecureContext(details) - -Creates a credentials object, with the optional details being a -dictionary with keys: - -* `pfx` : A string or buffer holding the PFX or PKCS12 encoded private - key, certificate and CA certificates -* `key`: A string or `Buffer` containing the private key of the server in - PEM format. To support multiple keys using different algorithms, an array - can be provided. It can either be a plain array of keys, or an array of - objects in the format `{pem: key, passphrase: passphrase}`. (Required) -* `passphrase` : A string of passphrase for the private key or pfx -* `cert` : A string holding the PEM encoded certificate -* `ca` : Either a string or list of strings of PEM encoded CA - certificates to trust. -* `crl` : Either a string or list of strings of PEM encoded CRLs - (Certificate Revocation List) -* `ciphers`: A string describing the ciphers to use or exclude. - Consult - - for details on the format. -* `honorCipherOrder` : When choosing a cipher, use the server's preferences - instead of the client preferences. For further details see `tls` module - documentation. - -If no 'ca' details are given, then Node.js will use the default -publicly trusted list of CAs as given in -. - - -## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options]) - -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`: A secure context object from tls.createSecureContext( ... ) - - - `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. - - - `options`: An object with common SSL options. See [tls.TLSSocket][]. - -`tls.createSecurePair()` returns a SecurePair object with `cleartext` and -`encrypted` stream properties. - -NOTE: `cleartext` has the same APIs as [tls.TLSSocket][] - -## Class: SecurePair - -Returned by tls.createSecurePair. - -### Event: '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. - -## Class: 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. - -### Event: 'secureConnection' - -`function (tlsSocket) {}` - -This event is emitted after a new connection has been successfully -handshaked. The argument is an 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 the selected NPN protocol -and `socket.alpnProtocol` is a string containing the selected ALPN -protocol, When both NPN and ALPN extensions are received, ALPN takes -precedence over NPN and the next protocol is selected by ALPN. When -ALPN has no selected protocol, this returns false. - -`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` is the [tls.TLSSocket][] that the error originated from. - - -### Event: 'newSession' - -`function (sessionId, sessionData, callback) { }` - -Emitted on creation of TLS session. May be used to store sessions in external -storage. `callback` must be invoked eventually, otherwise no data will be -sent or received from secure connection. - -NOTE: adding this event listener will have an effect only on connections -established after addition of event listener. - - -### Event: '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. - -Here's an example for using TLS session resumption: - - var tlsSessionStore = {}; - server.on('newSession', function(id, data, cb) { - tlsSessionStore[id.toString('hex')] = data; - cb(); - }); - server.on('resumeSession', function(id, cb) { - cb(null, tlsSessionStore[id.toString('hex')] || null); - }); - -### Event: 'OCSPRequest' - -`function (certificate, issuer, callback) { }` - -Emitted when the client sends a certificate status request. You could parse -server's current certificate to obtain OCSP url and certificate id, and after -obtaining OCSP response invoke `callback(null, resp)`, where `resp` is a -`Buffer` instance. Both `certificate` and `issuer` are a `Buffer` -DER-representations of the primary and issuer's certificates. They could be used -to obtain OCSP certificate id and OCSP endpoint url. - -Alternatively, `callback(null, null)` could be called, meaning that there is no -OCSP response. - -Calling `callback(err)` will result in a `socket.destroy(err)` call. - -Typical flow: - -1. Client connects to server and sends `OCSPRequest` to it (via status info - extension in ClientHello.) -2. Server receives request and invokes `OCSPRequest` event listener if present -3. Server grabs OCSP url from either `certificate` or `issuer` and performs an - [OCSP request] to the CA -4. Server receives `OCSPResponse` from CA and sends it back to client via - `callback` argument -5. Client validates the response and either destroys socket or performs a - handshake. - -NOTE: `issuer` could be null, if the certificate is self-signed or if the issuer -is not in the root certificates list. (You could provide an issuer via `ca` -option.) - -NOTE: adding this event listener will have an effect only on connections -established after addition of event listener. - -NOTE: you may want to use some npm module like [asn1.js] to parse the -certificates. - - -### server.listen(port[, hostname][, callback]) - -Begin accepting connections on the specified `port` and `hostname`. If the -`hostname` is omitted, the server will accept connections on any IPv6 address -(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. A -port value of zero will assign a random port. - -This function is asynchronous. The last parameter `callback` will be called -when the server has been bound. - -See `net.Server` for more information. - - -### server.close([callback]) - -Stops the server from accepting new connections. This function is -asynchronous, the server is finally closed when the server emits a `'close'` -event. Optionally, you can pass a callback to listen for the `'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.getTicketKeys() - -Returns `Buffer` instance holding the keys currently used for -encryption/decryption of the [TLS Session Tickets][] - -### server.setTicketKeys(keys) - -Updates the keys for encryption/decryption of the [TLS Session Tickets][]. - -NOTE: the buffer should be 48 bytes long. See server `ticketKeys` option for -more information oh how it is going to be used. - -NOTE: the change is effective only for the future server connections. Existing -or currently pending server connections will use previous keys. - -### server.addContext(hostname, context) - -Add secure context that will be used if client request's SNI hostname is -matching passed `hostname` (wildcards can be used). `context` can contain -`key`, `cert`, `ca` and/or any other properties from `tls.createSecureContext` -`options` argument. - -### server.maxConnections - -Set this property to reject connections when the server's connection count -gets high. - -### server.connections - -The number of concurrent connections on the server. - - -## Class: CryptoStream - - Stability: 0 - Deprecated: Use [tls.TLSSocket][] instead. - -This is an encrypted stream. - -### 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. - -Methods that return TLS connection meta data (e.g. -[getPeerCertificate](#tlssocketgetpeercertificate-detailed-)) -will only return data while the connection is open. - -### Event: '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 ALPN or NPN was used - you can -check `tlsSocket.alpnProtocol` or `tlsSocket.npnProtocol` for the -negotiated protocol. - -### Event: 'OCSPResponse' - -`function (response) { }` - -This event will be emitted if `requestOCSP` option was set. `response` is a -buffer object, containing server's OCSP response. - -Traditionally, the `response` is a signed object from the server's CA that -contains information about server's certificate revocation status. - -### tlsSocket.encrypted - -Static boolean value, always `true`. May be used to distinguish TLS sockets -from regular ones. - -### 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([ detailed ]) - -Returns an object representing the peer's certificate. The returned object has -some properties corresponding to the field of the certificate. If `detailed` -argument is `true` - the full chain with `issuer` property will be returned, -if `false` - only the top certificate without `issuer` property. +Returns an array with the names of the supported SSL ciphers. Example: - { 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' } + var ciphers = tls.getCiphers(); + console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...] -If the peer does not provide a certificate, it returns `null` or an empty -object. - -### tlsSocket.getCipher() -Returns an object representing the cipher name and the SSL/TLS -protocol version of the current connection. - -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 for more -information. - -### tlsSocket.getEphemeralKeyInfo() - -Returns an object representing a type, name and size of parameter of -an ephemeral key exchange in [Perfect forward Secrecy][] on a client -connection. It returns an empty object when the key exchange is not -ephemeral. As it is only supported on a client socket, it returns null -if this is called on a server socket. The supported types are 'DH' and -'ECDH'. The `name` property is only available in 'ECDH'. - -Example: - - { type: 'ECDH', name: 'prime256v1', size: 256 } - -### 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.setMaxSendFragment(size) - -Set maximum TLS fragment size (default and maximum value is: `16384`, minimum -is: `512`). Returns `true` on success, `false` otherwise. - -Smaller fragment size decreases buffering latency on the client: large -fragments are buffered by the TLS layer until the entire fragment is received -and its integrity is verified; large fragments can span multiple roundtrips, -and their processing can be delayed due to packet loss or reordering. However, -smaller fragments add extra TLS framing bytes and CPU overhead, which may -decrease overall server throughput. - -### tlsSocket.getSession() - -Return ASN.1 encoded TLS session or `undefined` if none was negotiated. Could -be used to speed up handshake establishment when reconnecting to the server. - -### tlsSocket.getTLSTicket() - -NOTE: Works only with client TLS sockets. Useful only for debugging, for -session reuse provide `session` option to `tls.connect`. - -Return TLS session ticket or `undefined` if none was negotiated. - -### 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 - -The string representation of the remote IP address. For example, -`'74.125.127.100'` or `'2001:4860:a005::68'`. - -### tlsSocket.remoteFamily - -The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. - -### tlsSocket.remotePort - -The numeric representation of the remote port. For example, `443`. - -### tlsSocket.localAddress - -The string representation of the local IP address. - -### tlsSocket.localPort - -The numeric representation of the local port. [OpenSSL cipher list format documentation]: http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT [Chrome's 'modern cryptography' setting]: http://www.chromium.org/Home/chromium-security/education/tls#TOC-Deprecation-of-TLS-Features-Algorithms-in-Chrome