From 9b8565c42a8a06822f425f67fa014b041c58d1a0 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 10:33:17 -0400 Subject: [PATCH] doc: add `added:` information for tls Ref: https://github.com/nodejs/node/issues/6578 PR-URL: https://github.com/nodejs/node/pull/7018 Reviewed-By: Anna Henningsen --- doc/api/tls.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index dbc87ccce66067..271b69d5562aab 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -184,12 +184,18 @@ 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) { }` @@ -199,6 +205,9 @@ established it will be forwarded here. `tlsSocket` is the [`tls.TLSSocket`][] that the error originated from. ### Event: 'newSession' + `function (sessionId, sessionData, callback) { }` @@ -210,6 +219,9 @@ NOTE: adding this event listener will have an effect only on connections established after addition of event listener. ### Event: 'OCSPRequest' + `function (certificate, issuer, callback) { }` @@ -248,6 +260,9 @@ NOTE: you may want to use some npm module like [asn1.js] to parse the certificates. ### Event: 'resumeSession' + `function (sessionId, callback) { }` @@ -274,6 +289,9 @@ server.on('resumeSession', (id, cb) => { ``` ### Event: 'secureConnection' + `function (tlsSocket) {}` @@ -292,6 +310,9 @@ server, you unauthorized connections may be accepted. 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 @@ -299,27 +320,42 @@ matching passed `hostname` (wildcards can be used). `context` can contain [`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 @@ -332,11 +368,17 @@ when the server has been bound. See `net.Server` for more information. ### server.maxConnections + Set this property to reject connections when the server's connection count gets high. ### server.setTicketKeys(keys) + Updates the keys for encryption/decryption of the [TLS Session Tickets][]. @@ -348,6 +390,9 @@ or currently pending server connections will use previous keys. ## Class: tls.TLSSocket + This is a wrapped version of [`net.Socket`][] that does transparent encryption of written data and all required TLS negotiation. @@ -360,6 +405,9 @@ Methods that return TLS connection meta data (e.g. connection is open. ## new tls.TLSSocket(socket[, options]) + Construct a new TLSSocket object from existing TCP socket. @@ -390,6 +438,9 @@ Construct a new TLSSocket object from existing TCP socket. on the socket before establishing a secure communication ### Event: 'OCSPResponse' + `function (response) { }` @@ -400,6 +451,9 @@ 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 @@ -410,6 +464,9 @@ If `tlsSocket.authorized === false` then the error can be found in `tlsSocket.npnProtocol` for 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 @@ -417,21 +474,34 @@ 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. @@ -443,6 +513,9 @@ https://www.openssl.org/docs/ssl/ssl.html#DEALING-WITH-CIPHERS for more information. ### 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` @@ -479,11 +552,17 @@ 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()`][]. @@ -491,27 +570,45 @@ session reuse provide `session` option to [`tls.connect()`][]. Return TLS session ticket or `undefined` if none was negotiated. ### tlsSocket.localPort + The numeric representation of the local port. ### tlsSocket.localAddress + The string representation of the local IP address. ### 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 @@ -525,6 +622,9 @@ 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. @@ -538,6 +638,9 @@ 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 @@ -654,6 +757,9 @@ socket.on('end', () => { ``` ## tls.createSecureContext(details) + Creates a credentials object, with the optional details being a dictionary with keys: @@ -711,6 +817,9 @@ and the cleartext one is used as a replacement for the initial encrypted stream. NOTE: `cleartext` has the same APIs as [`tls.TLSSocket`][] ## tls.createServer(options[, secureConnectionListener]) + Creates a new [tls.Server][]. The `connectionListener` argument is automatically set as a listener for the [`'secureConnection'`][] event. The @@ -901,6 +1010,9 @@ openssl s_client -connect 127.0.0.1:8000 ``` ## tls.getCiphers() + Returns an array with the names of the supported SSL ciphers.