tls: in-line comments and other cleanups

PR-URL: https://github.com/nodejs/node/pull/25861
Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

1 files changed, 24 insertions, 7 deletions

diff --git a/lib/_tls_wrap.js b/lib/_tls_wrap.js
index 39a1cfad8a..365dbb9491 100644
--- a/lib/_tls_wrap.js
+++ b/lib/_tls_wrap.js
@@ -62,6 +62,8 @@ const noop = () => {};
 
 let ipServernameWarned = false;
 
+// Server side times how long a handshake is taking to protect against slow
+// handshakes being used for DoS.
 function onhandshakestart(now) {
   debug('onhandshakestart');
 
@@ -121,6 +123,7 @@ function loadSession(hello) {
       return owner.destroy(new ERR_SOCKET_CLOSED());
 
     owner._handle.loadSession(session);
+    // Session is loaded. End the parser to allow handshaking to continue.
     owner._handle.endParser();
   }
 
@@ -128,6 +131,11 @@ function loadSession(hello) {
       hello.tlsTicket ||
       owner.server &&
       !owner.server.emit('resumeSession', hello.sessionId, onSession)) {
+    // Sessions without identifiers can't be resumed.
+    // Sessions with tickets can be resumed directly from the ticket, no server
+    // session storage is necessary.
+    // Without a call to a resumeSession listener, a session will never be
+    // loaded, so end the parser to allow handshaking to continue.
     owner._handle.endParser();
   }
 }
@@ -222,13 +230,17 @@ function onnewsessionclient(sessionId, session) {
 }
 
 function onnewsession(sessionId, session) {
+  debug('onnewsession');
   const owner = this[owner_symbol];
 
+  // XXX(sam) no server to emit the event on, but handshake won't continue
+  // unless newSessionDone() is called, should it be?
   if (!owner.server)
     return;
 
   var once = false;
   const done = () => {
+    debug('onnewsession done');
     if (once)
       return;
     once = true;
@@ -319,8 +331,12 @@ function TLSSocket(socket, opts) {
 
   var wrap;
   if ((socket instanceof net.Socket && socket._handle) || !socket) {
+    // 1. connected socket
+    // 2. no socket, one will be created with net.Socket().connect
     wrap = socket;
   } else {
+    // 3. socket has no handle so it is js not c++
+    // 4. unconnected sockets are wrapped
     // TLS expects to interact from C++ with a net.Socket that has a C++ stream
     // handle, but a JS stream doesn't have one. Wrap it up to make it look like
     // a socket.
@@ -340,7 +356,7 @@ function TLSSocket(socket, opts) {
   });
 
   // Proxy for API compatibility
-  this.ssl = this._handle;
+  this.ssl = this._handle;  // C++ TLSWrap object
 
   this.on('error', this._tlsError);
 
@@ -436,8 +452,8 @@ TLSSocket.prototype._wrapHandle = function(wrap) {
   const res = tls_wrap.wrap(externalStream,
                             context.context,
                             !!options.isServer);
-  res._parent = handle;
-  res._parentWrap = wrap;
+  res._parent = handle;  // C++ "wrap" object: TCPWrap, JSStream, ...
+  res._parentWrap = wrap;  // JS object: net.Socket, JSStreamSocket, ...
   res._secureContext = context;
   res.reading = handle.reading;
   this[kRes] = res;
@@ -487,8 +503,8 @@ TLSSocket.prototype._init = function(socket, wrap) {
 
   this.server = options.server;
 
-  // For clients, we will always have either a given ca list or be using
-  // default one
+  // Clients (!isServer) always request a cert, servers request a client cert
+  // only on explicit configuration.
   const requestCert = !!options.requestCert || !options.isServer;
   const rejectUnauthorized = !!options.rejectUnauthorized;
 
@@ -509,6 +525,7 @@ TLSSocket.prototype._init = function(socket, wrap) {
     if (this.server) {
       if (this.server.listenerCount('resumeSession') > 0 ||
           this.server.listenerCount('newSession') > 0) {
+        // Also starts the client hello parser as a side effect.
         ssl.enableSessionCallbacks();
       }
       if (this.server.listenerCount('OCSPRequest') > 0)
@@ -736,7 +753,7 @@ TLSSocket.prototype.getCipher = function(err) {
 // TODO: support anonymous (nocert) and PSK
 
 
-function onSocketSecure() {
+function onServerSocketSecure() {
   if (this._requestCert) {
     const verifyError = this._handle.verifyError();
     if (verifyError) {
@@ -787,7 +804,7 @@ function tlsConnectionListener(rawSocket) {
     SNICallback: this[kSNICallback] || SNICallback
   });
 
-  socket.on('secure', onSocketSecure);
+  socket.on('secure', onServerSocketSecure);
 
   socket[kErrorEmitted] = false;
   socket.on('close', onSocketClose);