diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index f105614962e041..7f21276c5409e0 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,336 +139,211 @@ the character "E" appended to the traditional abbreviations): Ephemeral methods may have some performance drawbacks, because key generation is expensive. +## Class: CryptoStream -## tls.getCiphers() - -Returns an array with the names of the supported SSL ciphers. - -Example: - - var ciphers = tls.getCiphers(); - console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...] - - -## tls.createServer(options[, secureConnectionListener]) + Stability: 0 - Deprecated: Use [tls.TLSSocket][] instead. -Creates a new [tls.Server][]. The `connectionListener` argument is -automatically set as a listener for the [secureConnection][] event. The -`options` object has these possibilities: +This is an encrypted stream. - - `pfx`: A string or `Buffer` containing the private key, certificate and - CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with - the `key`, `cert` and `ca` options.) +### cryptoStream.bytesWritten - - `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) +A proxy to the underlying socket's bytesWritten accessor, this will return +the total bytes written to the socket, *including the TLS overhead*. - - `passphrase`: A string of passphrase for the private key or pfx. +## Class: SecurePair - - `cert`: A string or `Buffer` containing the certificate key of the server in - PEM format. (Could be an array of certs). (Required) +Returned by tls.createSecurePair. - - `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. +### Event: 'secure' - - `crl` : Either a string or list of strings of PEM encoded CRLs (Certificate - Revocation List) +The event is emitted from the SecurePair once the pair has successfully +established a secure connection. - - `ciphers`: A string describing the ciphers to use or exclude, separated by - `:`. The default cipher suite is: +Similarly to the checking for the server 'secureConnection' event, +pair.cleartext.authorized should be checked to confirm whether the certificate +used properly authorized. - ECDHE-RSA-AES128-GCM-SHA256: - ECDHE-ECDSA-AES128-GCM-SHA256: - ECDHE-RSA-AES256-GCM-SHA384: - ECDHE-ECDSA-AES256-GCM-SHA384: - DHE-RSA-AES128-GCM-SHA256: - ECDHE-RSA-AES128-SHA256: - DHE-RSA-AES128-SHA256: - ECDHE-RSA-AES256-SHA384: - DHE-RSA-AES256-SHA384: - ECDHE-RSA-AES256-SHA256: - DHE-RSA-AES256-SHA256: - HIGH: - !aNULL: - !eNULL: - !EXPORT: - !DES: - !RC4: - !MD5: - !PSK: - !SRP: - !CAMELLIA +## Class: tls.Server - The default cipher suite prefers GCM ciphers for [Chrome's 'modern - cryptography' setting] and also prefers ECDHE and DHE ciphers for Perfect - Forward secrecy, while offering *some* backward compatibiltity. +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. - 128 bit AES is preferred over 192 and 256 bit AES in light of [specific - attacks affecting larger AES key sizes]. +### Event: 'clientError' - Old clients that rely on insecure and deprecated RC4 or DES-based ciphers - (like Internet Explorer 6) aren't able to complete the handshake with the default - configuration. If you absolutely must support these clients, the - [TLS recommendations] may offer a compatible cipher suite. For more details - on the format, see the [OpenSSL cipher list format documentation]. +`function (exception, tlsSocket) { }` - - `ecdhCurve`: A string describing a named curve to use for ECDH key agreement - or false to disable ECDH. +When a client connection emits an 'error' event before secure connection is +established - it will be forwarded here. - Defaults to `prime256v1` (NIST P-256). Use [crypto.getCurves()][] to obtain - a list of available curve names. On recent releases, - `openssl ecparam -list_curves` will also display the name and description of - each available elliptic curve. +`tlsSocket` is the [tls.TLSSocket][] that the error originated from. - - `dhparam`: A string or `Buffer` containing Diffie Hellman parameters, - required for Perfect Forward Secrecy. Use `openssl dhparam` to create it. - Its key length should be greater than or equal to 1024 bits, otherwise - it throws an error. It is strongly recommended to use 2048 bits or - more for stronger security. If omitted or invalid, it is silently - discarded and DHE ciphers won't be available. +### Event: 'newSession' - - `handshakeTimeout`: Abort the connection if the SSL/TLS handshake does not - finish in this many milliseconds. The default is 120 seconds. +`function (sessionId, sessionData, callback) { }` - A `'clientError'` is emitted on the `tls.Server` object whenever a handshake - times out. +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. - - `honorCipherOrder` : When choosing a cipher, use the server's preferences - instead of the client preferences. Default: `true`. +NOTE: adding this event listener will have an effect only on connections +established after addition of event listener. - - `requestCert`: If `true` the server will request a certificate from - clients that connect and attempt to verify that certificate. Default: - `false`. +### Event: 'OCSPRequest' - - `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`. +`function (certificate, issuer, callback) { }` - - `NPNProtocols`: An array or `Buffer` of possible NPN protocols. (Protocols - should be ordered by their priority). +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. - - `ALPNProtocols`: An array or `Buffer` of possible ALPN - protocols. (Protocols should be ordered by their priority). When - the server receives both NPN and ALPN extensions from the client, - ALPN takes precedence over NPN and the server does not send an NPN - extension to the client. +Alternatively, `callback(null, null)` could be called, meaning that there is no +OCSP response. - - `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 `tls.createSecureContext(...)` to get proper - SecureContext). If `SNICallback` wasn't provided - default callback with - high-level API will be used (see below). +Calling `callback(err)` will result in a `socket.destroy(err)` call. - - `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] for more details. +Typical flow: - - `ticketKeys`: A 48-byte `Buffer` instance consisting of 16-byte prefix, - 16-byte hmac key, 16-byte AES key. You could use it to accept tls session - tickets on multiple instances of tls server. +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: Automatically shared between `cluster` module workers. +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.) - - `sessionIdContext`: A string containing an 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. +NOTE: adding this event listener will have an effect only on connections +established after addition of event listener. - - `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][]. +NOTE: you may want to use some npm module like [asn1.js] to parse the +certificates. -Here is a simple example echo server: +### Event: 'resumeSession' - var tls = require('tls'); - var fs = require('fs'); +`function (sessionId, callback) { }` - var options = { - key: fs.readFileSync('server-key.pem'), - cert: fs.readFileSync('server-cert.pem'), +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. - // This is necessary only if using the client certificate authentication. - requestCert: true, +NOTE: adding this event listener will have an effect only on connections +established after addition of event listener. - // This is necessary only if the client uses the self-signed certificate. - ca: [ fs.readFileSync('client-cert.pem') ] - }; +Here's an example for using TLS session resumption: - 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); + var tlsSessionStore = {}; + server.on('newSession', function(id, data, cb) { + tlsSessionStore[id.toString('hex')] = data; + cb(); }); - server.listen(8000, function() { - console.log('server bound'); + server.on('resumeSession', function(id, cb) { + cb(null, tlsSessionStore[id.toString('hex')] || null); }); -Or +### Event: 'secureConnection' - var tls = require('tls'); - var fs = require('fs'); +`function (tlsSocket) {}` - var options = { - pfx: fs.readFileSync('server.pfx'), +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. - // This is necessary only if using the client certificate authentication. - requestCert: true, +`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. - 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'); - }); -You can test this server by connecting to it with `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`: 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). +`socket.servername` is a string containing servername requested with +SNI. - - `passphrase`: A string of passphrase for the private key or pfx. +### server.addContext(hostname, context) - - `cert`: A string or `Buffer` containing the certificate key of the client in - PEM format. (Could be an array of certs). +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. - - `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. +### server.address() - - `ciphers`: A string describing the ciphers to use or exclude, separated by - `:`. Uses the same default cipher suite as `tls.createServer`. +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. - - `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`. +### server.close([callback]) - - `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']`.) +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. - - `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']`.) +### server.connections - - `servername`: Servername for SNI (Server Name Indication) TLS extension. +The number of concurrent connections on the server. - - `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. +### server.getTicketKeys() - - `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][]. +Returns `Buffer` instance holding the keys currently used for +encryption/decryption of the [TLS Session Tickets][] - - `session`: A `Buffer` instance, containing TLS session. +### server.listen(port[, hostname][, callback]) - - `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. +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. -The `callback` parameter will be added as a listener for the -['secureConnect'][] event. +This function is asynchronous. The last parameter `callback` will be called +when the server has been bound. -`tls.connect()` returns a [tls.TLSSocket][] object. +See `net.Server` for more information. -Here is an example of a client of echo server as described previously: +### server.setTicketKeys(keys) - var tls = require('tls'); - var fs = require('fs'); +Updates the keys for encryption/decryption of the [TLS Session Tickets][]. - var options = { - // These are necessary only if using the client certificate authentication - key: fs.readFileSync('client-key.pem'), - cert: fs.readFileSync('client-cert.pem'), +NOTE: the buffer should be 48 bytes long. See server `ticketKeys` option for +more information oh how it is going to be used. - // This is necessary only if the server uses the self-signed certificate - ca: [ fs.readFileSync('server-cert.pem') ] - }; +NOTE: the change is effective only for the future server connections. Existing +or currently pending server connections will use previous keys. - 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(); - }); +### server.maxConnections -Or +Set this property to reject connections when the server's connection count +gets high. - var tls = require('tls'); - var fs = require('fs'); - var options = { - pfx: fs.readFileSync('client.pfx') - }; +## Class: 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(); - }); +This is a wrapped version of [net.Socket][] that does transparent encryption +of written data and all required TLS negotiation. -## Class: tls.TLSSocket +This instance implements a duplex [Stream][] interfaces. It has all the +common stream methods and events. -Wrapper for instance of [net.Socket][], replaces internal socket read/write -routines to perform transparent encryption/decryption of incoming/outgoing data. +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]) +### new tls.TLSSocket(socket[, options]) Construct a new TLSSocket object from existing TCP socket. @@ -502,430 +375,544 @@ Construct a new TLSSocket object from existing TCP socket. be added to client hello, and `OCSPResponse` event will be emitted on socket before establishing secure communication +### Event: 'OCSPResponse' -## tls.createSecureContext(details) +`function (response) { }` -Creates a credentials object, with the optional details being a -dictionary with keys: +This event will be emitted if `requestOCSP` option was set. `response` is a +buffer object, containing server's OCSP response. -* `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. +Traditionally, the `response` is a signed object from the server's CA that +contains information about server's certificate revocation status. -If no 'ca' details are given, then Node.js will use the default -publicly trusted list of CAs as given in -. +### 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. -## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options]) +### tlsSocket.address() -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. +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' }` - - `credentials`: A secure context object from tls.createSecureContext( ... ) +### tlsSocket.authorized - - `isServer`: A boolean indicating whether this tls connection should be - opened as a server or a client. +A boolean that is `true` if the peer certificate was signed by one of the +specified CAs, otherwise `false` - - `requestCert`: A boolean indicating whether a server should request a - certificate from a connecting client. Only applies to server connections. +### tlsSocket.authorizationError - - `rejectUnauthorized`: A boolean indicating whether a server should - automatically reject clients with invalid certificates. Only applies to - servers with `requestCert` enabled. +The reason why the peer's certificate has not been verified. This property +becomes available only when `tlsSocket.authorized === false`. - - `options`: An object with common SSL options. See [tls.TLSSocket][]. +### tlsSocket.encrypted -`tls.createSecurePair()` returns a SecurePair object with `cleartext` and -`encrypted` stream properties. +Static boolean value, always `true`. May be used to distinguish TLS sockets +from regular ones. -NOTE: `cleartext` has the same APIs as [tls.TLSSocket][] +### tlsSocket.getCipher() +Returns an object representing the cipher name and the SSL/TLS +protocol version of the current connection. -## Class: SecurePair +Example: +{ name: 'AES256-SHA', version: 'TLSv1/SSLv3' } -Returned by tls.createSecurePair. +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. -### Event: 'secure' +### tlsSocket.getEphemeralKeyInfo() -The event is emitted from the SecurePair once the pair has successfully -established a secure connection. +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'. -Similarly to the checking for the server 'secureConnection' event, -pair.cleartext.authorized should be checked to confirm whether the certificate -used properly authorized. +Example: -## Class: tls.Server + { type: 'ECDH', name: 'prime256v1', size: 256 } -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. +### tlsSocket.getPeerCertificate([ detailed ]) -### Event: 'secureConnection' +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. -`function (tlsSocket) {}` +Example: -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. + { 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' } -`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. +If the peer does not provide a certificate, it returns `null` or an empty +object. -`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. +### 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. -### Event: 'clientError' +### tlsSocket.getTLSTicket() -`function (exception, tlsSocket) { }` +NOTE: Works only with client TLS sockets. Useful only for debugging, for +session reuse provide `session` option to `tls.connect`. -When a client connection emits an 'error' event before secure connection is -established - it will be forwarded here. +Return TLS session ticket or `undefined` if none was negotiated. -`tlsSocket` is the [tls.TLSSocket][] that the error originated from. +### tlsSocket.localAddress +The string representation of the local IP address. -### Event: 'newSession' +### tlsSocket.localPort -`function (sessionId, sessionData, callback) { }` +The numeric representation of the local port. -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. +### tlsSocket.remoteAddress -NOTE: adding this event listener will have an effect only on connections -established after addition of event listener. +The string representation of the remote IP address. For example, +`'74.125.127.100'` or `'2001:4860:a005::68'`. +### tlsSocket.remoteFamily -### Event: 'resumeSession' +The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. -`function (sessionId, callback) { }` +### tlsSocket.remotePort -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. +The numeric representation of the remote port. For example, `443`. -NOTE: adding this event listener will have an effect only on connections -established after addition of event listener. +### tlsSocket.renegotiate(options, callback) -Here's an example for using TLS session resumption: +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. - 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); - }); +NOTE: Can be used to request peer's certificate after the secure connection +has been established. -### Event: 'OCSPRequest' +ANOTHER NOTE: When running as the server, socket will be destroyed +with an error after `handshakeTimeout` timeout. -`function (certificate, issuer, callback) { }` +### tlsSocket.setMaxSendFragment(size) -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. +Set maximum TLS fragment size (default and maximum value is: `16384`, minimum +is: `512`). Returns `true` on success, `false` otherwise. -Alternatively, `callback(null, null)` could be called, meaning that there is no -OCSP response. +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. -Calling `callback(err)` will result in a `socket.destroy(err)` call. -Typical flow: +## tls.connect(options[, callback]) +## tls.connect(port[, host][, options][, callback]) -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. +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: -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.) + - `host`: Host the client should connect to -NOTE: adding this event listener will have an effect only on connections -established after addition of event listener. + - `port`: Port the client should connect to -NOTE: you may want to use some npm module like [asn1.js] to parse the -certificates. + - `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. -### server.listen(port[, hostname][, callback]) + - `pfx`: A string or `Buffer` containing the private key, certificate and + CA certs of the client in PFX or PKCS12 format. -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. + - `key`: A string or `Buffer` containing the private key of the client in + PEM format. (Could be an array of keys). -This function is asynchronous. The last parameter `callback` will be called -when the server has been bound. + - `passphrase`: A string of passphrase for the private key or pfx. -See `net.Server` for more information. + - `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. -### server.close([callback]) + - `ciphers`: A string describing the ciphers to use or exclude, separated by + `:`. Uses the same default cipher suite as `tls.createServer`. -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. + - `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`. -### server.address() + - `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']`.) -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. + - `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']`.) -### server.getTicketKeys() + - `servername`: Servername for SNI (Server Name Indication) TLS extension. -Returns `Buffer` instance holding the keys currently used for -encryption/decryption of the [TLS Session Tickets][] + - `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. -### server.setTicketKeys(keys) + - `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][]. -Updates the keys for encryption/decryption of the [TLS Session Tickets][]. + - `session`: A `Buffer` instance, containing TLS session. -NOTE: the buffer should be 48 bytes long. See server `ticketKeys` option for -more information oh how it is going to be used. + - `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. -NOTE: the change is effective only for the future server connections. Existing -or currently pending server connections will use previous keys. +The `callback` parameter will be added as a listener for the +['secureConnect'][] event. -### server.addContext(hostname, context) +`tls.connect()` returns a [tls.TLSSocket][] object. -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. +Here is an example of a client of echo server as described previously: -### server.maxConnections + var tls = require('tls'); + var fs = require('fs'); -Set this property to reject connections when the server's connection count -gets high. + var options = { + // These are necessary only if using the client certificate authentication + key: fs.readFileSync('client-key.pem'), + cert: fs.readFileSync('client-cert.pem'), -### server.connections + // This is necessary only if the server uses the self-signed certificate + ca: [ fs.readFileSync('server-cert.pem') ] + }; -The number of concurrent connections on the server. + 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 -## Class: CryptoStream + var tls = require('tls'); + var fs = require('fs'); - Stability: 0 - Deprecated: Use [tls.TLSSocket][] instead. + var options = { + pfx: fs.readFileSync('client.pfx') + }; -This is an encrypted stream. + 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(); + }); -### 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*. +## tls.createSecureContext(details) -## Class: tls.TLSSocket +Creates a credentials object, with the optional details being a +dictionary with keys: -This is a wrapped version of [net.Socket][] that does transparent encryption -of written data and all required TLS negotiation. +* `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. -This instance implements a duplex [Stream][] interfaces. It has all the -common stream methods and events. +If no 'ca' details are given, then Node.js will use the default +publicly trusted list of CAs as given in +. -Methods that return TLS connection meta data (e.g. -[getPeerCertificate](#tlssocketgetpeercertificate-detailed-)) -will only return data while the connection is open. +## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options]) -### Event: 'secureConnect' +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. -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. + - `credentials`: A secure context object from tls.createSecureContext( ... ) -### Event: 'OCSPResponse' + - `isServer`: A boolean indicating whether this tls connection should be + opened as a server or a client. -`function (response) { }` + - `requestCert`: A boolean indicating whether a server should request a + certificate from a connecting client. Only applies to server connections. -This event will be emitted if `requestOCSP` option was set. `response` is a -buffer object, containing server's OCSP response. + - `rejectUnauthorized`: A boolean indicating whether a server should + automatically reject clients with invalid certificates. Only applies to + servers with `requestCert` enabled. -Traditionally, the `response` is a signed object from the server's CA that -contains information about server's certificate revocation status. + - `options`: An object with common SSL options. See [tls.TLSSocket][]. -### tlsSocket.encrypted +`tls.createSecurePair()` returns a SecurePair object with `cleartext` and +`encrypted` stream properties. -Static boolean value, always `true`. May be used to distinguish TLS sockets -from regular ones. +NOTE: `cleartext` has the same APIs as [tls.TLSSocket][] -### tlsSocket.authorized +## tls.createServer(options[, secureConnectionListener]) -A boolean that is `true` if the peer certificate was signed by one of the -specified CAs, otherwise `false` +Creates a new [tls.Server][]. The `connectionListener` argument is +automatically set as a listener for the [secureConnection][] event. The +`options` object has these possibilities: -### tlsSocket.authorizationError + - `pfx`: A string or `Buffer` containing the private key, certificate and + CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with + the `key`, `cert` and `ca` options.) -The reason why the peer's certificate has not been verified. This property -becomes available only when `tlsSocket.authorized === false`. + - `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) -### tlsSocket.getPeerCertificate([ detailed ]) + - `passphrase`: A string of passphrase for the private key or pfx. -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. + - `cert`: A string or `Buffer` containing the certificate key of the server in + PEM format. (Could be an array of certs). (Required) -Example: + - `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. - { 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' } + - `crl` : Either a string or list of strings of PEM encoded CRLs (Certificate + Revocation List) -If the peer does not provide a certificate, it returns `null` or an empty -object. + - `ciphers`: A string describing the ciphers to use or exclude, separated by + `:`. The default cipher suite is: -### tlsSocket.getCipher() -Returns an object representing the cipher name and the SSL/TLS -protocol version of the current connection. + ECDHE-RSA-AES128-GCM-SHA256: + ECDHE-ECDSA-AES128-GCM-SHA256: + ECDHE-RSA-AES256-GCM-SHA384: + ECDHE-ECDSA-AES256-GCM-SHA384: + DHE-RSA-AES128-GCM-SHA256: + ECDHE-RSA-AES128-SHA256: + DHE-RSA-AES128-SHA256: + ECDHE-RSA-AES256-SHA384: + DHE-RSA-AES256-SHA384: + ECDHE-RSA-AES256-SHA256: + DHE-RSA-AES256-SHA256: + HIGH: + !aNULL: + !eNULL: + !EXPORT: + !DES: + !RC4: + !MD5: + !PSK: + !SRP: + !CAMELLIA -Example: -{ name: 'AES256-SHA', version: 'TLSv1/SSLv3' } + The default cipher suite prefers GCM ciphers for [Chrome's 'modern + cryptography' setting] and also prefers ECDHE and DHE ciphers for Perfect + Forward secrecy, while offering *some* backward compatibiltity. -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. + 128 bit AES is preferred over 192 and 256 bit AES in light of [specific + attacks affecting larger AES key sizes]. -### tlsSocket.getEphemeralKeyInfo() + Old clients that rely on insecure and deprecated RC4 or DES-based ciphers + (like Internet Explorer 6) aren't able to complete the handshake with the default + configuration. If you absolutely must support these clients, the + [TLS recommendations] may offer a compatible cipher suite. For more details + on the format, see the [OpenSSL cipher list format documentation]. -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'. + - `ecdhCurve`: A string describing a named curve to use for ECDH key agreement + or false to disable ECDH. -Example: + Defaults to `prime256v1` (NIST P-256). Use [crypto.getCurves()][] to obtain + a list of available curve names. On recent releases, + `openssl ecparam -list_curves` will also display the name and description of + each available elliptic curve. - { type: 'ECDH', name: 'prime256v1', size: 256 } + - `dhparam`: A string or `Buffer` containing Diffie Hellman parameters, + required for Perfect Forward Secrecy. Use `openssl dhparam` to create it. + Its key length should be greater than or equal to 1024 bits, otherwise + it throws an error. It is strongly recommended to use 2048 bits or + more for stronger security. If omitted or invalid, it is silently + discarded and DHE ciphers won't be available. -### tlsSocket.renegotiate(options, callback) + - `handshakeTimeout`: Abort the connection if the SSL/TLS handshake does not + finish in this many milliseconds. The default is 120 seconds. -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. + A `'clientError'` is emitted on the `tls.Server` object whenever a handshake + times out. -NOTE: Can be used to request peer's certificate after the secure connection -has been established. + - `honorCipherOrder` : When choosing a cipher, use the server's preferences + instead of the client preferences. Default: `true`. -ANOTHER NOTE: When running as the server, socket will be destroyed -with an error after `handshakeTimeout` timeout. + - `requestCert`: If `true` the server will request a certificate from + clients that connect and attempt to verify that certificate. Default: + `false`. -### tlsSocket.setMaxSendFragment(size) + - `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`. -Set maximum TLS fragment size (default and maximum value is: `16384`, minimum -is: `512`). Returns `true` on success, `false` otherwise. + - `NPNProtocols`: An array or `Buffer` of possible NPN protocols. (Protocols + should be ordered by their priority). -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. + - `ALPNProtocols`: An array or `Buffer` of possible ALPN + protocols. (Protocols should be ordered by their priority). When + the server receives both NPN and ALPN extensions from the client, + ALPN takes precedence over NPN and the server does not send an NPN + extension to the client. -### tlsSocket.getSession() + - `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 `tls.createSecureContext(...)` to get proper + SecureContext). If `SNICallback` wasn't provided - default callback with + high-level API will be used (see below). -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. + - `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] for more details. -### tlsSocket.getTLSTicket() + - `ticketKeys`: A 48-byte `Buffer` instance consisting of 16-byte prefix, + 16-byte hmac key, 16-byte AES key. You could use it to accept tls session + tickets on multiple instances of tls server. -NOTE: Works only with client TLS sockets. Useful only for debugging, for -session reuse provide `session` option to `tls.connect`. + NOTE: Automatically shared between `cluster` module workers. -Return TLS session ticket or `undefined` if none was negotiated. + - `sessionIdContext`: A string containing an 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. -### tlsSocket.address() + - `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][]. -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' }` +Here is a simple example echo server: -### tlsSocket.remoteAddress + var tls = require('tls'); + var fs = require('fs'); -The string representation of the remote IP address. For example, -`'74.125.127.100'` or `'2001:4860:a005::68'`. + var options = { + key: fs.readFileSync('server-key.pem'), + cert: fs.readFileSync('server-cert.pem'), -### tlsSocket.remoteFamily + // This is necessary only if using the client certificate authentication. + requestCert: true, -The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. + // This is necessary only if the client uses the self-signed certificate. + ca: [ fs.readFileSync('client-cert.pem') ] + }; -### tlsSocket.remotePort + 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'); + }); -The numeric representation of the remote port. For example, `443`. +Or -### tlsSocket.localAddress + var tls = require('tls'); + var fs = require('fs'); -The string representation of the local IP address. + var options = { + pfx: fs.readFileSync('server.pfx'), -### tlsSocket.localPort + // 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'); + }); +You can test this server by connecting to it with `openssl s_client`: + + + openssl s_client -connect 127.0.0.1:8000 + +## tls.getCiphers() + +Returns an array with the names of the supported SSL ciphers. + +Example: + + var ciphers = tls.getCiphers(); + console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...] -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