From 5af646cec5610aa04e58fb0306e562fa04e6792a Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 10:33:17 -0400 Subject: [PATCH 01/25] adding added to Class CruptoStream --- doc/api/tls.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index caec8a7b123c57..11664e54eb675d 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1031,7 +1031,9 @@ console.log(tls.getCiphers()); // ['AES128-SHA', 'AES256-SHA', ...] ## Deprecated APIs ### Class: CryptoStream - + Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. The `tls.CryptoStream` class represents a stream of encrypted data. This class From 40d345a638d246bc242972e1a50ab9d02c7bec07 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 11:13:14 -0400 Subject: [PATCH 02/25] adding added to a few methods --- doc/api/tls.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 11664e54eb675d..114a1704a8922d 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -132,9 +132,14 @@ threshold is exceeded. The limits are configurable: * `tls.CLIENT_RENEG_LIMIT` {number} Specifies the number of renegotiation requests. Defaults to `3`. + * `tls.CLIENT_RENEG_WINDOW` {number} Specifies the time renegotiation window in seconds. Defaults to `600` (10 minutes). - + *Note*: The default renegotiation limits should not be modified without a full understanding of the implications and risks. @@ -1019,6 +1024,9 @@ openssl s_client -connect 127.0.0.1:8000 ``` ## tls.getCiphers() + Returns an array with the names of the supported SSL ciphers. From 28217fc8c27cb378199e7400994015db56fc2344 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 11:22:36 -0400 Subject: [PATCH 03/25] adding added to Class tls.TLSSocket --- doc/api/tls.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 114a1704a8922d..557b900b3d8cd3 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -132,14 +132,8 @@ threshold is exceeded. The limits are configurable: * `tls.CLIENT_RENEG_LIMIT` {number} Specifies the number of renegotiation requests. Defaults to `3`. - * `tls.CLIENT_RENEG_WINDOW` {number} Specifies the time renegotiation window in seconds. Defaults to `600` (10 minutes). - *Note*: The default renegotiation limits should not be modified without a full understanding of the implications and risks. @@ -390,7 +384,9 @@ previous keys. ## Class: tls.TLSSocket - + The `tls.TLSSocket` is a subclass of [`net.Socket`][] that performs transparent encryption of written data and all required TLS negotiation. From e993b2e26f4c2c4705fa04f9e2d5a33282dcb991 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 11:27:28 -0400 Subject: [PATCH 04/25] adding YAML and added for OCSResponse event --- doc/api/tls.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 557b900b3d8cd3..2636793fbe9d4b 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -384,7 +384,7 @@ previous keys. ## Class: tls.TLSSocket - The `tls.TLSSocket` is a subclass of [`net.Socket`][] that performs transparent @@ -397,7 +397,9 @@ Instances of `tls.TLSSocket` implement the duplex [Stream][] interface. connection is open. ### new tls.TLSSocket(socket[, options]) - + * `socket` {net.Socket} An instance of [`net.Socket`][] * `options` {Object} * `secureContext`: An optional TLS context object from @@ -418,7 +420,9 @@ connection is open. Construct a new `tls.TLSSocket` object from an existing TCP socket. ### Event: 'OCSPResponse' - + The `'OCSPResponse'` event is emitted if the `requestOCSP` option was set when the `tls.TLSSocket` was created and an OCSP response has been received. The listener callback is passed a single argument when called: From 8d8aaca53842dad8288260a88819c91dc93b3c11 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 13:23:14 -0400 Subject: [PATCH 05/25] adding added before version --- doc/api/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 2636793fbe9d4b..f163ef1bd62253 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1025,7 +1025,7 @@ openssl s_client -connect 127.0.0.1:8000 ## tls.getCiphers() Returns an array with the names of the supported SSL ciphers. From b0c3498f565d40a81a04d2e8b9fbfbd1dbd5da79 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 14:42:55 -0400 Subject: [PATCH 06/25] adding add to a few evetns --- doc/api/tls.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index f163ef1bd62253..64dccb05dddc81 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -190,6 +190,9 @@ The `tls.Server` class is a subclass of `net.Server` that accepts encrypted connections using TLS or SSL. ### Event: 'tlsClientError' + The `'tlsClientError'` event is emitted when an error occurs before a secure connection is established. The listener callback is passed two arguments when @@ -200,7 +203,9 @@ called: error originated. ### Event: 'newSession' - + The `'newSession'` event is emitted upon creation of a new TLS session. This may be used to store sessions in external storage. The listener callback is passed three arguments when called: @@ -214,7 +219,9 @@ three arguments when called: established after the addition of the event listener. ### Event: 'OCSPRequest' - + The `'OCSPRequest'` event is emitted when the client sends a certificate status request. The listener callback is passed three arguments when called: From 8eefd49d455bfba63c1e5ddd16c148f8c0c46bb7 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 14:43:59 -0400 Subject: [PATCH 07/25] adding added for the resumeSession event --- doc/api/tls.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 64dccb05dddc81..115a2b9c6794e4 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -265,7 +265,9 @@ established after the addition of the event listener. *Note*: An npm module like [asn1.js] may be used to parse the certificates. ### Event: 'resumeSession' - + The `'resumeSession'` event is emitted when the client requests to resume a previous TLS session. The listener callback is passed two arguments when called: From f12bed4ef936ad667945b109e46af55dc654459f Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 14:45:11 -0400 Subject: [PATCH 08/25] adding added for secureConnection event --- doc/api/tls.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 115a2b9c6794e4..0a7d6a281fba86 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -299,7 +299,9 @@ server.on('resumeSession', (id, cb) => { ``` ### Event: 'secureConnection' - + The `'secureConnection'` event is emitted after the handshaking process for a new connection has successfully completed. The listener callback is passed a single argument when called: From aba37d5f0f46678fba4e89f040734dfab419449a Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 14:46:57 -0400 Subject: [PATCH 09/25] adding added for the addContext method --- doc/api/tls.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 0a7d6a281fba86..d9744453b2fc2b 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -325,7 +325,9 @@ The `tlsSocket.servername` property is a string containing the server name requested via SNI. ### server.addContext(hostname, context) - + * `hostname` {string} A SNI hostname or wildcard (e.g. `'*'`) * `context` {Object} An object containing any of the possible properties from the [`tls.createSecureContext()`][] `options` arguments (e.g. `key`, From 9f4fb600527dc8d4406634450630b55032a4489c Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 15:00:04 -0400 Subject: [PATCH 10/25] adding added to the secureConnect event --- doc/api/tls.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index d9744453b2fc2b..3b79c848e4c567 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -343,7 +343,7 @@ server as reported by the operating system. See [`net.Server.address()`][] for more information. ### server.close([callback]) - +w * `callback` {Function} An optional listener callback that will be registered to listen for the server instance's `'close'` event. @@ -446,7 +446,9 @@ Typically, the `response` is a digitally signed object from the server's CA that contains information about server's certificate revocation status. ### Event: 'secureConnect' - + The `'secureConnect'` event is emitted after the handshaking process for a new connection has successfully completed. The listener callback will be called regardless of whether or not the server's certificate has been authorized. It From 7460fff02c1f36a3a6d083fd243311ba8b643ead Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 15:01:35 -0400 Subject: [PATCH 11/25] adding added to server.close event --- doc/api/tls.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 3b79c848e4c567..3a2ba54b05b856 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -343,7 +343,9 @@ server as reported by the operating system. See [`net.Server.address()`][] for more information. ### server.close([callback]) -w + * `callback` {Function} An optional listener callback that will be registered to listen for the server instance's `'close'` event. From 2e167f4a814ae55559e51070ef0aab154fb66e8d Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 15:38:20 -0400 Subject: [PATCH 12/25] adding added to the connections method --- doc/api/tls.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index 3a2ba54b05b856..662874098aa277 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -355,6 +355,9 @@ This function operates asynchronously. The `'close'` event will be emitted when the the server is finally closed. ### server.connections + Returns the current number of concurrent connections on the server. From e8bfe2ce1669985f7c52d727a463437dc0491179 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 15:39:02 -0400 Subject: [PATCH 13/25] adding added to the class and the address method --- doc/api/tls.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index 662874098aa277..34cce4c1ece10e 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -185,6 +185,9 @@ of an application. The `--tls-cipher-list` switch should by used only if absolutely necessary. ## Class: tls.Server + The `tls.Server` class is a subclass of `net.Server` that accepts encrypted connections using TLS or SSL. @@ -337,6 +340,9 @@ The `server.addContext()` method adds a secure context that will be used if the client request's SNS hostname matches the supplied `hostname` (or wildcard). ### 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 From 7235213b0cdab2e1d19f8ef3cf76082f3fd86ff2 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 15:41:20 -0400 Subject: [PATCH 14/25] adding added to the getTicketKeys --- doc/api/tls.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 34cce4c1ece10e..fb3643069ad578 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -361,14 +361,16 @@ This function operates asynchronously. The `'close'` event will be emitted when the the server is finally closed. ### server.connections - Returns the current number of concurrent connections on the server. ### server.getTicketKeys() - + Returns a `Buffer` instance holding the keys currently used for encryption/decryption of the [TLS Session Tickets][] From a2fff2303a892ae84bd9282f7d07a2b559f78fb5 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 15:43:52 -0400 Subject: [PATCH 15/25] adding added to the setTicketKeys method --- doc/api/tls.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index fb3643069ad578..75fe91562367e8 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -375,6 +375,9 @@ Returns a `Buffer` instance holding the keys currently used for encryption/decryption of the [TLS Session Tickets][] ### server.listen(port[, hostname][, callback]) + * `port` {number} The TCP/IP port on which to begin listening for connections. A value of `0` (zero) will assign a random port. @@ -394,6 +397,9 @@ called when the server has started listening. See `net.Server` for more information. ### server.setTicketKeys(keys) + * `keys` {Buffer} The keys used for encryption/decryption of the [TLS Session Tickets][]. From 5550764bad23db62d8df0351fe91505aba31163b Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 19:58:56 -0400 Subject: [PATCH 16/25] Adding added to the address and authorized methods for tlsSocket --- doc/api/tls.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index 75fe91562367e8..61e784bba487ce 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -479,6 +479,9 @@ the `tlsSocket.alpnProtocol` or `tlsSocket.npnProtocol` properties can be checked to determine 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 @@ -486,6 +489,9 @@ object with three properties, e.g., `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` ### tlsSocket.authorized + Returns `true` if the peer certificate was signed by one of the CAs specified when creating the `tls.TLSSocket` instance, otherwise `false`. From e20d2b250415e193abe6adcae0f59b83e1f69c42 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 20:22:50 -0400 Subject: [PATCH 17/25] adding added to all tls methods --- doc/api/tls.md | 77 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 57 insertions(+), 20 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 61e784bba487ce..936512b5291165 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -492,22 +492,27 @@ object with three properties, e.g., - Returns `true` if the peer certificate was signed by one of the CAs specified when creating the `tls.TLSSocket` instance, otherwise `false`. ### tlsSocket.authorizationError - + Returns the reason why the peer's certificate was not been verified. This property is set only when `tlsSocket.authorized === false`. ### tlsSocket.encrypted - + Always returns `true`. This may be used to distinguish TLS sockets from regular `net.Socket` instances. ### tlsSocket.getCipher() - + Returns an object representing the cipher name and the SSL/TLS protocol version that first defined the cipher. @@ -518,7 +523,9 @@ https://www.openssl.org/docs/manmaster/ssl/SSL_CIPHER_get_name.html for more information. ### tlsSocket.getEphemeralKeyInfo() - + Returns an object representing the 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 @@ -529,7 +536,9 @@ if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The For Example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }` ### tlsSocket.getPeerCertificate([ detailed ]) - + * `detailed` {boolean} Specify `true` to request that the full certificate chain with the `issuer` property be returned; `false` to return only the top certificate without the `issuer` property. @@ -567,7 +576,9 @@ If the peer does not provide a certificate, `null` or an empty object will be returned. ### tlsSocket.getProtocol() - + Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value `'unknown'` will be returned for connected sockets that have not completed the handshaking process. The value `null` will @@ -585,41 +596,57 @@ See https://www.openssl.org/docs/manmaster/ssl/SSL_get_version.html for more information. ### tlsSocket.getSession() - + Returns the ASN.1 encoded TLS session or `undefined` if no session was negotiated. Can be used to speed up handshake establishment when reconnecting to the server. ### tlsSocket.getTLSTicket() - + Returns the TLS session ticket or `undefined` if no session was negotiated. *Note*: This only works with client TLS sockets. Useful only for debugging, for session reuse provide `session` option to [`tls.connect()`][]. ### tlsSocket.localAddress - + Returns the string representation of the local IP address. ### tlsSocket.localPort - + Returns the numeric representation of the local port. ### tlsSocket.remoteAddress - + Returns the string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. ### tlsSocket.remoteFamily - + Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`. ### tlsSocket.remotePort - + Returns the numeric representation of the remote port. For example, `443`. ### tlsSocket.renegotiate(options, callback) - + * `options` {Object} * `rejectUnauthorized` {boolean} * `requestCert` @@ -637,7 +664,9 @@ secure connection has been established. after `handshakeTimeout` timeout. ### tlsSocket.setMaxSendFragment(size) - + * `size` {number} The maximum TLS fragment size. Defaults to `16384`. The maximum value is `16384`. @@ -653,7 +682,9 @@ decrease overall server throughput. ## tls.connect(options[, callback]) - + * `options` {Object} * `host` {string} Host the client should connect to. * `port` {number} Port the client should connect to. @@ -722,7 +753,9 @@ The `callback` function, if specified, will be added as a listener for the `tls.connect()` returns a [`tls.TLSSocket`][] object. ## tls.connect(port[, host][, options][, callback]) - + * `port` {number} * `host` {string} * `options` {Object} @@ -850,7 +883,9 @@ socket.on('end', () => { ## tls.createSecureContext(options) - + * `options` {Object} * `pfx` {string|Buffer} A string or `Buffer` holding the PFX or PKCS12 encoded private key, certificate, and CA certificates. @@ -883,7 +918,9 @@ publicly trusted list of CAs as given in ## tls.createServer(options[, secureConnectionListener]) - + * `options` {Object} * `pfx` {string|Buffer} A string or `Buffer` containing the private key, certificate and CA certs of the server in PFX or PKCS12 format. (Mutually From 69a7e5c692b11d44a19cf21ffc2b56997bb710de Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 20:50:26 -0400 Subject: [PATCH 18/25] finish adding added and deprecated --- doc/api/tls.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 936512b5291165..4232dfd96cefc7 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1117,7 +1117,8 @@ console.log(tls.getCiphers()); // ['AES128-SHA', 'AES256-SHA', ...] ### Class: CryptoStream Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. @@ -1125,19 +1126,27 @@ The `tls.CryptoStream` class represents a stream of encrypted data. This class has been deprecated and should no longer be used. #### cryptoStream.bytesWritten - + The `cryptoStream.bytesWritten` property returns the total number of bytes written to the underlying socket *including* the bytes required for the implementation of the TLS protocol. ### Class: SecurePair - + Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. Returned by `tls.createSecurePair()`. #### Event: 'secure' - + The `'secure'` event is emitted by the `SecurePair` object once a secure connection has been established. @@ -1146,7 +1155,10 @@ event, `pair.cleartext.authorized` should be inspected to confirm whether the certificate used is properly authorized. ## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options]) - + Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. * `context` {Object} A secure context object as returned by From a093711c7184d173aee0b57499f995d370674e64 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 20:59:57 -0400 Subject: [PATCH 19/25] removing release candidate version --- doc/api/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 4232dfd96cefc7..2167472d6977c7 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -524,7 +524,7 @@ information. ### tlsSocket.getEphemeralKeyInfo() Returns an object representing the type, name, and size of parameter of an ephemeral key exchange in [Perfect Forward Secrecy][] on a client From e8a9bfa7e307721c4ab3f7273809c592d4919672 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 21:09:32 -0400 Subject: [PATCH 20/25] adding added to SecurePair class --- doc/api/tls.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index 2167472d6977c7..25304a61075f7c 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1136,6 +1136,7 @@ implementation of the TLS protocol. ### Class: SecurePair Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. From 456a59f7ff3c348634fee913f02dbafbf4cea7da Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Fri, 27 May 2016 21:12:04 -0400 Subject: [PATCH 21/25] fixing missing YAML's and adding space --- doc/api/tls.md | 78 +++++++++++++++++++++++++------------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 25304a61075f7c..5e61ed4080ea6c 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -185,7 +185,7 @@ of an application. The `--tls-cipher-list` switch should by used only if absolutely necessary. ## Class: tls.Server - @@ -193,7 +193,7 @@ The `tls.Server` class is a subclass of `net.Server` that accepts encrypted connections using TLS or SSL. ### Event: 'tlsClientError' - @@ -206,7 +206,7 @@ called: error originated. ### Event: 'newSession' - The `'newSession'` event is emitted upon creation of a new TLS session. This may @@ -222,7 +222,7 @@ three arguments when called: established after the addition of the event listener. ### Event: 'OCSPRequest' - The `'OCSPRequest'` event is emitted when the client sends a certificate status @@ -268,7 +268,7 @@ established after the addition of the event listener. *Note*: An npm module like [asn1.js] may be used to parse the certificates. ### Event: 'resumeSession' - The `'resumeSession'` event is emitted when the client requests to resume a @@ -302,7 +302,7 @@ server.on('resumeSession', (id, cb) => { ``` ### Event: 'secureConnection' - The `'secureConnection'` event is emitted after the handshaking process for a @@ -328,7 +328,7 @@ The `tlsSocket.servername` property is a string containing the server name requested via SNI. ### server.addContext(hostname, context) - * `hostname` {string} A SNI hostname or wildcard (e.g. `'*'`) @@ -340,7 +340,7 @@ The `server.addContext()` method adds a secure context that will be used if the client request's SNS hostname matches the supplied `hostname` (or wildcard). ### server.address() - @@ -349,7 +349,7 @@ server as reported by the operating system. See [`net.Server.address()`][] for more information. ### server.close([callback]) - * `callback` {Function} An optional listener callback that will be registered to @@ -361,21 +361,21 @@ This function operates asynchronously. The `'close'` event will be emitted when the the server is finally closed. ### server.connections - Returns the current number of concurrent connections on the server. ### server.getTicketKeys() - Returns a `Buffer` instance holding the keys currently used for encryption/decryption of the [TLS Session Tickets][] ### server.listen(port[, hostname][, callback]) - @@ -397,7 +397,7 @@ called when the server has started listening. See `net.Server` for more information. ### server.setTicketKeys(keys) - @@ -416,7 +416,7 @@ previous keys. ## Class: tls.TLSSocket - The `tls.TLSSocket` is a subclass of [`net.Socket`][] that performs transparent @@ -429,7 +429,7 @@ Instances of `tls.TLSSocket` implement the duplex [Stream][] interface. connection is open. ### new tls.TLSSocket(socket[, options]) - * `socket` {net.Socket} An instance of [`net.Socket`][] @@ -452,7 +452,7 @@ added: v0.11.4 Construct a new `tls.TLSSocket` object from an existing TCP socket. ### Event: 'OCSPResponse' - The `'OCSPResponse'` event is emitted if the `requestOCSP` option was set @@ -465,7 +465,7 @@ Typically, the `response` is a digitally signed object from the server's CA that contains information about server's certificate revocation status. ### Event: 'secureConnect' - The `'secureConnect'` event is emitted after the handshaking process for a new @@ -479,7 +479,7 @@ the `tlsSocket.alpnProtocol` or `tlsSocket.npnProtocol` properties can be checked to determine the negotiated protocol. ### tlsSocket.address() - @@ -489,28 +489,28 @@ object with three properties, e.g., `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` ### tlsSocket.authorized - Returns `true` if the peer certificate was signed by one of the CAs specified when creating the `tls.TLSSocket` instance, otherwise `false`. ### tlsSocket.authorizationError - Returns the reason why the peer's certificate was not been verified. This property is set only when `tlsSocket.authorized === false`. ### tlsSocket.encrypted - Always returns `true`. This may be used to distinguish TLS sockets from regular `net.Socket` instances. ### tlsSocket.getCipher() - Returns an object representing the cipher name and the SSL/TLS protocol version @@ -523,7 +523,7 @@ https://www.openssl.org/docs/manmaster/ssl/SSL_CIPHER_get_name.html for more information. ### tlsSocket.getEphemeralKeyInfo() - Returns an object representing the type, name, and size of parameter of @@ -536,7 +536,7 @@ if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The For Example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }` ### tlsSocket.getPeerCertificate([ detailed ]) - * `detailed` {boolean} Specify `true` to request that the full certificate @@ -576,7 +576,7 @@ If the peer does not provide a certificate, `null` or an empty object will be returned. ### tlsSocket.getProtocol() - Returns a string containing the negotiated SSL/TLS protocol version of the @@ -596,7 +596,7 @@ See https://www.openssl.org/docs/manmaster/ssl/SSL_get_version.html for more information. ### tlsSocket.getSession() - Returns the ASN.1 encoded TLS session or `undefined` if no session was @@ -604,7 +604,7 @@ negotiated. Can be used to speed up handshake establishment when reconnecting to the server. ### tlsSocket.getTLSTicket() - Returns the TLS session ticket or `undefined` if no session was negotiated. @@ -613,38 +613,38 @@ Returns the TLS session ticket or `undefined` if no session was negotiated. session reuse provide `session` option to [`tls.connect()`][]. ### tlsSocket.localAddress - Returns the string representation of the local IP address. ### tlsSocket.localPort - Returns the numeric representation of the local port. ### tlsSocket.remoteAddress - Returns the string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. ### tlsSocket.remoteFamily - Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`. ### tlsSocket.remotePort - Returns the numeric representation of the remote port. For example, `443`. ### tlsSocket.renegotiate(options, callback) - * `options` {Object} @@ -664,7 +664,7 @@ secure connection has been established. after `handshakeTimeout` timeout. ### tlsSocket.setMaxSendFragment(size) - * `size` {number} The maximum TLS fragment size. Defaults to `16384`. The @@ -682,7 +682,7 @@ decrease overall server throughput. ## tls.connect(options[, callback]) - * `options` {Object} @@ -753,7 +753,7 @@ The `callback` function, if specified, will be added as a listener for the `tls.connect()` returns a [`tls.TLSSocket`][] object. ## tls.connect(port[, host][, options][, callback]) - * `port` {number} @@ -883,7 +883,7 @@ socket.on('end', () => { ## tls.createSecureContext(options) - * `options` {Object} @@ -918,7 +918,7 @@ publicly trusted list of CAs as given in ## tls.createServer(options[, secureConnectionListener]) - * `options` {Object} @@ -1101,7 +1101,7 @@ openssl s_client -connect 127.0.0.1:8000 ``` ## tls.getCiphers() - From 2b73b0cbf597bc65703fd9ddb8eb7273ef182b16 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Sat, 28 May 2016 10:35:57 -0400 Subject: [PATCH 22/25] adding space between added comment and text --- doc/api/tls.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index 5e61ed4080ea6c..64327b8eb96ba6 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -209,6 +209,7 @@ called: + The `'newSession'` event is emitted upon creation of a new TLS session. This may be used to store sessions in external storage. The listener callback is passed three arguments when called: @@ -225,6 +226,7 @@ established after the addition of the event listener. + The `'OCSPRequest'` event is emitted when the client sends a certificate status request. The listener callback is passed three arguments when called: @@ -271,6 +273,7 @@ established after the addition of the event listener. + The `'resumeSession'` event is emitted when the client requests to resume a previous TLS session. The listener callback is passed two arguments when called: @@ -305,6 +308,7 @@ server.on('resumeSession', (id, cb) => { + The `'secureConnection'` event is emitted after the handshaking process for a new connection has successfully completed. The listener callback is passed a single argument when called: @@ -331,6 +335,7 @@ requested via SNI. + * `hostname` {string} A SNI hostname or wildcard (e.g. `'*'`) * `context` {Object} An object containing any of the possible properties from the [`tls.createSecureContext()`][] `options` arguments (e.g. `key`, @@ -352,6 +357,7 @@ more information. + * `callback` {Function} An optional listener callback that will be registered to listen for the server instance's `'close'` event. @@ -371,6 +377,7 @@ Returns the current number of concurrent connections on the server. + Returns a `Buffer` instance holding the keys currently used for encryption/decryption of the [TLS Session Tickets][] @@ -419,6 +426,7 @@ previous keys. + The `tls.TLSSocket` is a subclass of [`net.Socket`][] that performs transparent encryption of written data and all required TLS negotiation. @@ -432,6 +440,7 @@ connection is open. + * `socket` {net.Socket} An instance of [`net.Socket`][] * `options` {Object} * `secureContext`: An optional TLS context object from @@ -455,6 +464,7 @@ Construct a new `tls.TLSSocket` object from an existing TCP socket. + The `'OCSPResponse'` event is emitted if the `requestOCSP` option was set when the `tls.TLSSocket` was created and an OCSP response has been received. The listener callback is passed a single argument when called: @@ -468,6 +478,7 @@ contains information about server's certificate revocation status. + The `'secureConnect'` event is emitted after the handshaking process for a new connection has successfully completed. The listener callback will be called regardless of whether or not the server's certificate has been authorized. It @@ -492,6 +503,7 @@ object with three properties, e.g., + Returns `true` if the peer certificate was signed by one of the CAs specified when creating the `tls.TLSSocket` instance, otherwise `false`. @@ -499,6 +511,7 @@ when creating the `tls.TLSSocket` instance, otherwise `false`. + Returns the reason why the peer's certificate was not been verified. This property is set only when `tlsSocket.authorized === false`. @@ -506,6 +519,7 @@ property is set only when `tlsSocket.authorized === false`. + Always returns `true`. This may be used to distinguish TLS sockets from regular `net.Socket` instances. @@ -513,6 +527,7 @@ Always returns `true`. This may be used to distinguish TLS sockets from regular + Returns an object representing the cipher name and the SSL/TLS protocol version that first defined the cipher. @@ -526,6 +541,7 @@ information. + Returns an object representing the 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 @@ -539,6 +555,7 @@ For Example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }` + * `detailed` {boolean} Specify `true` to request that the full certificate chain with the `issuer` property be returned; `false` to return only the top certificate without the `issuer` property. @@ -579,6 +596,7 @@ returned. + Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value `'unknown'` will be returned for connected sockets that have not completed the handshaking process. The value `null` will @@ -599,6 +617,7 @@ information. + Returns the ASN.1 encoded TLS session or `undefined` if no session was negotiated. Can be used to speed up handshake establishment when reconnecting to the server. @@ -607,6 +626,7 @@ to the server. + Returns the TLS session ticket or `undefined` if no session was negotiated. *Note*: This only works with client TLS sockets. Useful only for debugging, for @@ -616,12 +636,14 @@ session reuse provide `session` option to [`tls.connect()`][]. + Returns the string representation of the local IP address. ### tlsSocket.localPort + Returns the numeric representation of the local port. ### tlsSocket.remoteAddress @@ -635,18 +657,21 @@ Returns the string representation of the remote IP address. For example, + Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`. ### tlsSocket.remotePort + Returns the numeric representation of the remote port. For example, `443`. ### tlsSocket.renegotiate(options, callback) + * `options` {Object} * `rejectUnauthorized` {boolean} * `requestCert` @@ -667,6 +692,7 @@ after `handshakeTimeout` timeout. + * `size` {number} The maximum TLS fragment size. Defaults to `16384`. The maximum value is `16384`. @@ -685,6 +711,7 @@ decrease overall server throughput. + * `options` {Object} * `host` {string} Host the client should connect to. * `port` {number} Port the client should connect to. @@ -756,6 +783,7 @@ The `callback` function, if specified, will be added as a listener for the + * `port` {number} * `host` {string} * `options` {Object} @@ -886,6 +914,7 @@ socket.on('end', () => { + * `options` {Object} * `pfx` {string|Buffer} A string or `Buffer` holding the PFX or PKCS12 encoded private key, certificate, and CA certificates. @@ -921,6 +950,7 @@ publicly trusted list of CAs as given in + * `options` {Object} * `pfx` {string|Buffer} A string or `Buffer` containing the private key, certificate and CA certs of the server in PFX or PKCS12 format. (Mutually @@ -1120,6 +1150,7 @@ console.log(tls.getCiphers()); // ['AES128-SHA', 'AES256-SHA', ...] added: v0.3.4 deprecated: v0.11.3 --> + Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. The `tls.CryptoStream` class represents a stream of encrypted data. This class @@ -1139,6 +1170,7 @@ implementation of the TLS protocol. added: v0.3.2 deprecated: v0.11.3 --> + Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. Returned by `tls.createSecurePair()`. @@ -1160,6 +1192,7 @@ certificate used is properly authorized. added: v0.3.2 deprecated: v0.11.3 --> + Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. * `context` {Object} A secure context object as returned by From 926997759425677388e49468b323a94c65826794 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Wed, 8 Jun 2016 21:37:58 -0400 Subject: [PATCH 23/25] fixing tls.Server added date --- doc/api/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 64327b8eb96ba6..c5f0cf9f384e38 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -186,7 +186,7 @@ absolutely necessary. ## Class: tls.Server The `tls.Server` class is a subclass of `net.Server` that accepts encrypted From 6c48020f267e89786ddbd56b3cdf3f07b7ffaea0 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Sun, 12 Jun 2016 14:15:29 -0400 Subject: [PATCH 24/25] fixing some errors --- doc/api/tls.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index c5f0cf9f384e38..ea674591769a57 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -207,7 +207,7 @@ called: ### Event: 'newSession' The `'newSession'` event is emitted upon creation of a new TLS session. This may @@ -271,7 +271,7 @@ established after the addition of the event listener. ### Event: 'resumeSession' The `'resumeSession'` event is emitted when the client requests to resume a @@ -306,7 +306,7 @@ server.on('resumeSession', (id, cb) => { ### Event: 'secureConnection' The `'secureConnection'` event is emitted after the handshaking process for a @@ -333,7 +333,7 @@ requested via SNI. ### server.addContext(hostname, context) * `hostname` {string} A SNI hostname or wildcard (e.g. `'*'`) @@ -346,7 +346,7 @@ the client request's SNS hostname matches the supplied `hostname` (or wildcard). ### server.address() Returns the bound address, the address family name, and port of the @@ -355,7 +355,7 @@ more information. ### server.close([callback]) * `callback` {Function} An optional listener callback that will be registered to @@ -368,14 +368,14 @@ when the the server is finally closed. ### server.connections Returns the current number of concurrent connections on the server. ### server.getTicketKeys() Returns a `Buffer` instance holding the keys currently used for @@ -383,7 +383,7 @@ encryption/decryption of the [TLS Session Tickets][] ### server.listen(port[, hostname][, callback]) * `port` {number} The TCP/IP port on which to begin listening for connections. @@ -405,7 +405,7 @@ See `net.Server` for more information. ### server.setTicketKeys(keys) * `keys` {Buffer} The keys used for encryption/decryption of the @@ -476,7 +476,7 @@ contains information about server's certificate revocation status. ### Event: 'secureConnect' The `'secureConnect'` event is emitted after the handshaking process for a new @@ -594,7 +594,7 @@ returned. ### tlsSocket.getProtocol() Returns a string containing the negotiated SSL/TLS protocol version of the @@ -650,6 +650,7 @@ Returns the numeric representation of the local port. + Returns the string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. @@ -948,7 +949,7 @@ publicly trusted list of CAs as given in ## tls.createServer(options[, secureConnectionListener]) * `options` {Object} From 092e015ad275b88e71be9f1273453d5a369e2da5 Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Sun, 12 Jun 2016 15:30:42 -0400 Subject: [PATCH 25/25] fixing whitespace change --- doc/api/tls.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index ea674591769a57..6a5cdda7e4208a 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -134,6 +134,7 @@ threshold is exceeded. The limits are configurable: requests. Defaults to `3`. * `tls.CLIENT_RENEG_WINDOW` {number} Specifies the time renegotiation window in seconds. Defaults to `600` (10 minutes). + *Note*: The default renegotiation limits should not be modified without a full understanding of the implications and risks.