Skip to content

Improvements to tls API documentation, batch 1 #9800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
sam-github wants to merge 19 commits into from
Closed

Improvements to tls API documentation, batch 1 #9800

Changes from 1 commit
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
8ea758c
tls: fix/annotate connect arg comments
sam-github Nov 18, 2016
516a9d9
tls: document and test option-less createServer
sam-github Nov 21, 2016
cd1fdfb
test: tls key/cert ordering not necessary
sam-github Nov 22, 2016
28a3045
tls: do not refer to secureOptions as flags
sam-github Nov 22, 2016
53cfdb0
doc: document all TLSSocket options
sam-github Nov 23, 2016
43b8c9e
doc: describe all tls.connect() variants
sam-github Nov 23, 2016
c94b954
doc: socket passed to tls.connect is user managed
sam-github Nov 24, 2016
b9a6642
doc: describe tls passphrase use with pfx and key
sam-github Nov 24, 2016
8c25224
doc: describe tls cert and ca options
sam-github Nov 24, 2016
90e01ff
doc: describe buffer forms of tls crl option
sam-github Nov 24, 2016
706efcd
doc: describe tls cipher option and defaults
sam-github Nov 24, 2016
be11388
doc: fix link to Crypto Constants
sam-github Nov 25, 2016
17405b6
doc: honorCipherOrder sets CIPHER_SERVER_PREFERENCE
sam-github Nov 25, 2016
5c078e5
doc: describe tls ecdhCurve/dhparam options
sam-github Nov 25, 2016
e8e59e4
doc: describe tls secureProtocol option
sam-github Nov 25, 2016
797b334
doc: describe tls secureOptions
sam-github Nov 25, 2016
5a85e08
doc: describe tls sessionIdContext
sam-github Nov 25, 2016
bb89227
doc: de-deduplicate secure context docs
sam-github Nov 25, 2016
a52555e
test: var to const in tls-no-cert-required
sam-github Dec 9, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
doc: describe tls cert and ca options
  • Loading branch information
@sam-github
sam-github committed Dec 9, 2016
commit 8c25224639960f863aba291651e95714877f9623
18 changes: 13 additions & 5 deletions doc/api/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -896,11 +896,19 @@ added: v0.11.13
not encrypted.
* `passphrase` {string} Optional shared passphrase used for a single private
key and/or a PFX.
* `cert` {string} A string containing the PEM encoded certificate
* `ca`{string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of strings,
or array of `Buffer`s of trusted certificates in PEM format. If omitted,
several well known "root" CAs (like VeriSign) will be used. These are used
to authorize connections.
* `cert` {string|string[]|Buffer|Buffer[]} Optional cert chains in PEM format.
One cert chain should be provided per private key. Each cert chain should
consist of the PEM formatted certificate for a provided private `key`,
followed by the PEM formatted intermediate certificates (if any), in order,
and not including the root CA (the root CA must be pre-known to the peer,
see `ca`). When providing multiple cert chains, they do not have to be in
the same order as their private keys in `key`. If the intermediate
certificates are not provided, the peer will not be able to validate the
certificate, and the handshake will fail.
* `ca`{string|string[]|Buffer|Buffer[]} Optional CA certificates to trust.
Default is the well-known CAs from Mozilla. When connecting to peers that
use certificates issued privately, or self-signed, the private root CA or
self-signed certificate must be provided to verify the peer.
Copy link
Copy Markdown
Contributor

@silverwind silverwind Nov 25, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add a word that it will replace default CAs?

Copy link
Copy Markdown
Contributor Author

@sam-github sam-github Nov 25, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't that how all default values work? The default is used when you don't specify the option. If you specify the option, the default isn't used.

I can spell it out if necessary, but the other Optional x. Default is y.
I think the old text used to be confusing, which is why some people thought it could possibly be additive.

Copy link
Copy Markdown
Contributor Author

@sam-github sam-github Nov 25, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, meant to write: but the other Optional x. Default is y. don't spell out that x replaces y if you specify it.

Copy link
Copy Markdown
Contributor

@silverwind silverwind Nov 25, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, you have a point. It's probably okay your way.

Copy link
Copy Markdown
Contributor Author

@sam-github sam-github Nov 25, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do feel there is a missing section describing the basic authentication model of TLS, which will make all the buttons and dials more clear. Also, the examples are terrible, but I ran out of time. Maybe on the plane next week I'll rewrite them.

* `crl` {string|string[]} Either a string or array of strings of PEM encoded
CRLs (Certificate Revocation List).
* `ciphers` {string} A string describing the ciphers to use or exclude.
Expand Down