doc: general improvements to tls.md copy #6933

jasnell · 2016-05-23T19:47:40Z

Checklist

documentation is changed or added
the commit message follows commit guidelines

Affected core subsystem(s)

doc (tls)

Description of change

General improvements to tls.md copy

@nodejs/documentation @nodejs/crypto

indutny · 2016-05-23T19:53:14Z

doc/api/tls.md

@@ -2,90 +2,138 @@

    Stability: 2 - Stable

-Use `require('tls')` to access this module.
+The `tls` module provides an implementation of the Transport Layer Security
+(TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL.


I think we do not support either of SSL2 or SSL3 by default anymore. Is it worth mentioning here?

Yeah, I made a note of that for myself when I was going through this. There are a couple of outdated bits in this that should be updated.

Should we at least add deprecated to SSL?

Perhaps... let's do this separately. There are a couple places where the SSL stuff in this doc needs to be updated.

eljefedelrodeodeljefe · 2016-05-23T19:56:14Z

nit: we are very, very inconsistent about it, but I would prefer the "Note"-section preceded with an underscore and only ended with an underscore after/with the relevant section.

addaleax · 2016-05-23T20:02:02Z

doc/api/tls.md

+
+The `tlsSocket.renegotiate()` method initiate TLS renegotiation process. 
+Upon completion, the `callback` function will be passed a single argument 
+that is either an `Error` (if the request failed) or `null.


Unmatched backtick

thefourtheye · 2016-05-23T20:08:12Z

@eljefedelrodeodeljefe I totally agree. We should perhaps document the conventions followed in docs, somewhere.

indutny · 2016-05-23T20:08:24Z

doc/api/tls.md


-## ALPN, NPN and SNI
+### ALPN, NPN and SNI

 <!-- type=misc -->

 ALPN (Application-Layer Protocol Negotiation Extension), NPN (Next
 Protocol Negotiation) and, SNI (Server Name Indication) are TLS


Let's add a note about deprecation of NPN. It was never documented officially, and now is slowly going away.

Deprecation just in Node.js or deprecation in general use?

In general https://groups.google.com/a/chromium.org/forum/#!topic/security-dev/eJVxCZ92vvg

jasnell · 2016-05-23T20:20:47Z

@thefourtheye @eljefedelrodeodeljefe ... regarding the Note sections, I have something different in mind when I'm done going through each of these documents... I'd like to explore making them true aside callout in the rendered html, pulled out of the regular text flow using <aside>. But first I need to get all of our instances normalized.

jasnell · 2016-05-23T20:22:04Z

@addaleax @indutny @thefourtheye ... nits addressed

eljefedelrodeodeljefe · 2016-05-23T20:23:33Z

@jasnell SGTM

indutny · 2016-05-23T20:28:24Z

doc/api/tls.md

+The term "[Forward Secrecy]" or "Perfect Forward Secrecy" describes a feature of
+key-agreement (i.e., key-exchange) methods. That is, the server and client keys
+are used to negotiate new keys that are used specifically and only for the
+current communication session. Practically, this means that even if a private


Nit, but server's private key?

What about this?

indutny · 2016-05-23T20:38:51Z

Few more nits, otherwise LGTM. This is looking really great, thank you!

jasnell · 2016-05-23T20:39:52Z

Nits updated!

indutny · 2016-05-23T20:42:38Z

doc/api/tls.md

+key-agreement (i.e., key-exchange) methods. That is, the server and client keys
+are used to negotiate new temporary keys that are used specifically and only for
+the current communication session. Practically, this means that even if the
+server's private key is compromised, communication can only be decrypted by


I see it now, nvm.

indutny · 2016-05-23T20:43:20Z

LGTM, good job on this @jasnell

bnoordhuis · 2016-05-24T12:56:12Z

doc/api/tls.md

-TLS/SSL is a public/private key infrastructure. Each client and each
-server must have a private key. A private key is created like this:
+The TLS/SSL is a public/private key infrastructure (PKI). Each client and
+server must have a *private key*.


If I were a pedant, I'd point out that null ciphers (i.e., no-auth and no-encrypt ciphers) that don't require a key do exist.

Fortunately, I'm not a pedant!

jasnell · 2016-05-24T17:54:37Z

@shigeki @bnoordhuis ... nits addressed! commits squashed and message updated.

bnoordhuis · 2016-05-24T20:28:53Z

I couldn't spot whether you changed the description for the checkServerIdentity callback. Maybe it's because it's documented in several places.

shigeki · 2016-05-25T06:05:18Z

doc/api/tls.md

 ```

+where `secure_socket` has the same API as `pair.cleartext`.

 [OpenSSL cipher list format documentation]: https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT
 [Chrome's 'modern cryptography' setting]: https://www.chromium.org/Home/chromium-security/education/tls#TOC-Deprecation-of-TLS-Features-Algorithms-in-Chrome


This link was already outdated. https://www.chromium.org/Home/chromium-security/education/tls#TOC-Cipher-Suites seems to be a new one.

shigeki · 2016-05-25T06:08:15Z

@jasnell Just one minor nits, otherwise LGTM. Good work, thanks.

jasnell · 2016-05-25T15:50:31Z

@bnoordhuis ... made the change here => https://github.com/nodejs/node/pull/6933/files#diff-f6e3a86962eaf0897ab59e88b418e64fR724

@shigeki ... updated!

jasnell · 2016-05-25T15:52:20Z

@bnoordhuis ... updated both instances of the checkServerIdentity text to the updated language.

bnoordhuis · 2016-05-25T19:50:37Z

I only see one change in commit 49e287f. Did I overlook something?

jasnell · 2016-05-25T21:20:10Z

@bnoordhuis ... the other one was here -> 129be4b#diff-f6e3a86962eaf0897ab59e88b418e64fR724

It was squashed in with the other changes...

bnoordhuis · 2016-05-25T21:36:37Z

Ah, alright. LGTM then.

Restructuring and clarifications to the tls.md copy to improve readability and flow.

Restructuring and clarifications to the tls.md copy to improve readability and flow. PR-URL: #6933 Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Shigeki Ohtsu <ohtsu@iij.ad.jp>

jasnell · 2016-05-26T15:13:58Z

Landed in 1b6a468. Thanks all.
For the next round of edits I will work on pulling out the SSL references that are no longer relevant.

Restructuring and clarifications to the tls.md copy to improve readability and flow. PR-URL: nodejs#6933 Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Shigeki Ohtsu <ohtsu@iij.ad.jp>

Restructuring and clarifications to the tls.md copy to improve readability and flow. PR-URL: #6933 Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Shigeki Ohtsu <ohtsu@iij.ad.jp>

MylesBorins · 2016-07-11T21:44:07Z

added don't land label please feel free to backport

zbinlin · 2016-12-16T11:37:48Z

doc/api/tls.md

-  - `certfile`: all CA certs concatenated in one file like
-    `cat ca1-cert.pem ca2-cert.pem > ca-cert.pem`
+If using Perfect Foward Secrecy using `ECDHE`, Diffie-Hellman parameters are
+not required and a default ECDHE curve will be used. The `ecdheCurve` property


ecdheCurve or ecdhCurve?

Addresses comment after PR nodejs#6933 merged. nodejs#6933 (review) PR-URL: nodejs#10345 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Italo A. Casas <me@italoacasas.com>

Addresses comment after PR #6933 merged. #6933 (review) PR-URL: #10345 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Italo A. Casas <me@italoacasas.com>

jasnell added tls Issues and PRs related to the tls subsystem. crypto Issues and PRs related to the crypto subsystem. doc Issues and PRs related to the documentations. labels May 23, 2016

indutny reviewed May 23, 2016
View reviewed changes

addaleax reviewed May 23, 2016
View reviewed changes

indutny reviewed May 23, 2016
View reviewed changes

mscdex removed the crypto Issues and PRs related to the crypto subsystem. label May 24, 2016

bnoordhuis reviewed May 24, 2016
View reviewed changes

shigeki reviewed May 25, 2016
View reviewed changes

doc: general improvements to tls.md copy

8ad0809

Restructuring and clarifications to the tls.md copy to improve readability and flow.

jasnell force-pushed the doc-tls-copy branch from 49e287f to 8ad0809 Compare May 26, 2016 15:08

jasnell closed this May 26, 2016

MylesBorins mentioned this pull request Jul 11, 2016

Audit commits not found on v4.x-staging #7661

Closed

MylesBorins added the dont-land-on-v4.x label Jul 11, 2016

zbinlin reviewed Dec 16, 2016

View reviewed changes

sam-github mentioned this pull request Dec 19, 2016

doc: fix typo in ecdhCurve, a tls property name #10345

Merged

2 tasks

cjihrig pushed a commit that referenced this pull request Dec 20, 2016

doc: fix typo in ecdhCurve, a tls property name

5654c83

Addresses comment after PR #6933 merged. #6933 (review) PR-URL: #10345 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Italo A. Casas <me@italoacasas.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: general improvements to tls.md copy #6933

doc: general improvements to tls.md copy #6933

jasnell commented May 23, 2016

indutny May 23, 2016

jasnell May 23, 2016

indutny May 23, 2016

jasnell May 23, 2016

eljefedelrodeodeljefe commented May 23, 2016

addaleax May 23, 2016

thefourtheye commented May 23, 2016

indutny May 23, 2016

jasnell May 23, 2016

indutny May 23, 2016

jasnell May 23, 2016

jasnell May 23, 2016

jasnell commented May 23, 2016 •

edited

Loading

jasnell commented May 23, 2016

eljefedelrodeodeljefe commented May 23, 2016

indutny May 23, 2016

indutny May 23, 2016

indutny commented May 23, 2016

jasnell commented May 23, 2016

indutny May 23, 2016

indutny commented May 23, 2016

bnoordhuis May 24, 2016

jasnell commented May 24, 2016

bnoordhuis commented May 24, 2016

shigeki May 25, 2016

shigeki commented May 25, 2016

jasnell commented May 25, 2016

jasnell commented May 25, 2016

bnoordhuis commented May 25, 2016

jasnell commented May 25, 2016

bnoordhuis commented May 25, 2016

jasnell commented May 26, 2016

MylesBorins commented Jul 11, 2016

zbinlin Dec 16, 2016

doc: general improvements to tls.md copy #6933

doc: general improvements to tls.md copy #6933

Conversation

jasnell commented May 23, 2016

Checklist

Affected core subsystem(s)

Description of change

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eljefedelrodeodeljefe commented May 23, 2016

Choose a reason for hiding this comment

thefourtheye commented May 23, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented May 23, 2016 • edited Loading

jasnell commented May 23, 2016

eljefedelrodeodeljefe commented May 23, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

indutny commented May 23, 2016

jasnell commented May 23, 2016

Choose a reason for hiding this comment

indutny commented May 23, 2016

Choose a reason for hiding this comment

jasnell commented May 24, 2016

bnoordhuis commented May 24, 2016

Choose a reason for hiding this comment

shigeki commented May 25, 2016

jasnell commented May 25, 2016

jasnell commented May 25, 2016

bnoordhuis commented May 25, 2016

jasnell commented May 25, 2016

bnoordhuis commented May 25, 2016

jasnell commented May 26, 2016

MylesBorins commented Jul 11, 2016

Choose a reason for hiding this comment

jasnell commented May 23, 2016 •

edited

Loading