Skip to content
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.

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

tls: inconsistency between doc and code for createSecureContext() options in TLSSocket constructor #10538

Closed
nbdd0121 opened this issue Dec 30, 2016 · 5 comments
Labels
tls Issues and PRs related to the tls subsystem.

Comments

@nbdd0121
Copy link

  • Version: 7.3
  • Platform: Any
  • Subsystem: Any

In current TLS doc, when documenting options argument of the constructor of TLSSocket, it says

...: Optional tls.createSecureContext() options can be provided, see the secureContext option for more information. Construct a new tls.TLSSocket object from an existing TCP socket.

However, in line 351 of _tls_wrap.js, tls.createSecureContext() is called without arguments at all. This inconsistency is introduced in caa7fa9. Either the doc or the code must be changed to match.

In my opinion I believe that what is described in the doc is sensible, but I believe that a community consensus must be reached to actually decide the correct behavior.

@mscdex mscdex added the tls Issues and PRs related to the tls subsystem. label Dec 30, 2016
sam-github added a commit to sam-github/node that referenced this issue Dec 30, 2016
Unlike all the other tls APIs, if any secure context configuration is
required, the caller is responsible for creating the context.

Corrects a doc regression introduced in caa7fa9.

Fix nodejs#10538
@sam-github
Copy link
Contributor

sam-github commented Jan 13, 2017

@jkryl and @nbdd0121 I started to change the code to accept all the options of tls.createSecureContext() and I'm running into some issues. Not in using the options to create the secure context, that is trivial, but testing it.

AFAICT, its impossible to actually use a tls.TLSSocket based on the documented properties and methods. I found this by looking at test-tls-socket-default-options.js, and realizing that it completely fails to authenticate the server's certificate (or run the tests its supposed to). Authentication is completely up to the creator of the tls.TLSSocket, and requires using various undocumented APIs, such as tlsSocket.ssl, tlsSocket.ssl.verifyError(), tls.checkServerIdentity(), because documented APIs such as the 'secureConnection' event, and .rejectUnauthorized only work when calling tls.connect(), not with directly constructed TLSSockets.

You two are clearly using this constructor, or you wouldn't have noticed the docs about the secureContext were wrong.

Am I off-base in thinking that it is necessary to use undocumented APIs when directly constructing a tls.TLSSocket? Do you have any links to code that does this, or is it all internal?

I'm about to go searching for npmjs.org code that uses this feature to figure out what the actual documented API surface should be, I think secure websockets might be one user, but any pointers are appreciated.

@jkryl
Copy link

jkryl commented Jan 16, 2017

hi @sam-github, I'm trying to use tls.TLSSocket in this pull request: nodeftpd/nodeftpd#123. It is about upgrading unencrypted socket to TLS socket upon "AUTH TLS" FTP command. Note that because of this bug I have to create the secure context explicitly and then pass it to the constructor. So that extra code should go away when this issue is fixed.

@sam-github
Copy link
Contributor

@jkryl Thanks for the reference, it confirms to me that there are undocumented APIs that are mandatory for use, and you even reference #10555, thank you.

I commented on your PR, hope its helpful.

@mk-pmb
Copy link

mk-pmb commented Jan 16, 2017

@jkryl, I'll have to deal with this soon, so I''d love if you (edit: or anyone. :-) ) could make a package that abstracts these API differences away and make it easy to write code in a manner that's future proof both in the sense of a centralized location for upcoming fixes, as well as not relying on people remembering unintuitive things.
The starttls package seems to solve some of this but the API calls in the example code for manual checking still look fragile to me.

@sam-github
Copy link
Contributor

@MylesBorins I marked #10846 for landing on v4 and v6, so that will be easy to write code that works on all LTS releases as well as current.

@mk-pmb starttls attempts to be compatible to node versions that are no longer supported. If you don't need that, keep an eye out here: we should be able to get this small API nicety back-ported to all the LTS releases (4.x and 6.x at the moment).

sam-github added a commit to sam-github/node that referenced this issue Feb 20, 2017
Add support to new tls.TLSSocket() to create a SecureContext object with
all its supported options, in the same way they are supported for all
the other APIs that need SecureContext objects.

Fix: nodejs#10538
PR-URL: nodejs#11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
sam-github added a commit to sam-github/node that referenced this issue Feb 20, 2017
Because of a poorly constructed test, only one of the two test vectors
ran.  The test also failed to cover the authentication error that occurs
when the server's certificate is not trusted.

Both issues are fixed.

Fix: nodejs#10538
PR-URL: nodejs#11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
sam-github added a commit to sam-github/node that referenced this issue Feb 20, 2017
Add support to new tls.TLSSocket() to create a SecureContext object with
all its supported options, in the same way they are supported for all
the other APIs that need SecureContext objects.

Fix: nodejs#10538
PR-URL: nodejs#11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
italoacasas pushed a commit to italoacasas/node that referenced this issue Feb 25, 2017
Because of a poorly constructed test, only one of the two test vectors
ran.  The test also failed to cover the authentication error that occurs
when the server's certificate is not trusted.

Both issues are fixed.

Fix: nodejs#10538
PR-URL: nodejs#11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
italoacasas pushed a commit to italoacasas/node that referenced this issue Feb 25, 2017
Add support to new tls.TLSSocket() to create a SecureContext object with
all its supported options, in the same way they are supported for all
the other APIs that need SecureContext objects.

Fix: nodejs#10538
PR-URL: nodejs#11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this issue May 16, 2017
Because of a poorly constructed test, only one of the two test vectors
ran.  The test also failed to cover the authentication error that occurs
when the server's certificate is not trusted.

Both issues are fixed.

Fix: #10538
PR-URL: #11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this issue May 16, 2017
Add support to new tls.TLSSocket() to create a SecureContext object with
all its supported options, in the same way they are supported for all
the other APIs that need SecureContext objects.

Fix: #10538
PR-URL: #11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this issue May 18, 2017
Because of a poorly constructed test, only one of the two test vectors
ran.  The test also failed to cover the authentication error that occurs
when the server's certificate is not trusted.

Both issues are fixed.

Fix: #10538
PR-URL: #11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this issue May 18, 2017
Add support to new tls.TLSSocket() to create a SecureContext object with
all its supported options, in the same way they are supported for all
the other APIs that need SecureContext objects.

Fix: #10538
PR-URL: #11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
andrew749 pushed a commit to michielbaird/node that referenced this issue Jul 19, 2017
Because of a poorly constructed test, only one of the two test vectors
ran.  The test also failed to cover the authentication error that occurs
when the server's certificate is not trusted.

Both issues are fixed.

Fix: nodejs/node#10538
PR-URL: nodejs/node#11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
andrew749 pushed a commit to michielbaird/node that referenced this issue Jul 19, 2017
Add support to new tls.TLSSocket() to create a SecureContext object with
all its supported options, in the same way they are supported for all
the other APIs that need SecureContext objects.

Fix: nodejs/node#10538
PR-URL: nodejs/node#11005
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
tls Issues and PRs related to the tls subsystem.
Projects
None yet
Development

No branches or pull requests

5 participants