src: in-source comments and minor TLS cleanups

Renamed some internal C++ methods and properties for consistency, and
commented SSL I/O.

- Rename waiting_new_session_ after is_waiting_new_session(), instead of
  using reverse naming (new_session_wait_), and change "waiting" to
  "awaiting".
- Make TLSWrap::ClearIn() return void, the value is never used.
- Fix a getTicketKeys() cut-n-paste error. Since it doesn't use the
  arguments, remove them from the js wrapper.
- Remove call of setTicketKeys(getTicketKeys()), its a no-op.

PR-URL: https://github.com/nodejs/node/pull/25713
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>

1 files changed, 23 insertions, 7 deletions

diff --git a/src/tls_wrap.h b/src/tls_wrap.h
index 13f2bc1c71..cd2701cd6d 100644
--- a/src/tls_wrap.h
+++ b/src/tls_wrap.h
@@ -72,7 +72,9 @@ class TLSWrap : public AsyncWrap,
               uv_buf_t* bufs,
               size_t count,
               uv_stream_t* send_handle) override;
+  // Return error_ string or nullptr if it's empty.
   const char* Error() const override;
+  // Reset error_ string to empty. Not related to "clear text".
   void ClearError() override;
 
   void NewSessionDoneCb();
@@ -105,11 +107,22 @@ class TLSWrap : public AsyncWrap,
 
   static void SSLInfoCallback(const SSL* ssl_, int where, int ret);
   void InitSSL();
-  void EncOut();
-  bool ClearIn();
-  void ClearOut();
+  // SSL has a "clear" text (unencrypted) side (to/from the node API) and
+  // encrypted ("enc") text side (to/from the underlying socket/stream).
+  // On each side data flows "in" or "out" of SSL context.
+  //
+  // EncIn() doesn't exist. Encrypted data is pushed from underlying stream into
+  // enc_in_ via the stream listener's OnStreamAlloc()/OnStreamRead() interface.
+  void EncOut();  // Write encrypted data from enc_out_ to underlying stream.
+  void ClearIn();  // SSL_write() clear data "in" to SSL.
+  void ClearOut();  // SSL_read() clear text "out" from SSL.
+
+  // Call Done() on outstanding WriteWrap request.
   bool InvokeQueued(int status, const char* error_str = nullptr);
 
+  // Drive the SSL state machine by attempting to SSL_read() and SSL_write() to
+  // it. Transparent handshakes mean SSL_read() might trigger I/O on the
+  // underlying stream even if there is no clear text to read or write.
   inline void Cycle() {
     // Prevent recursion
     if (++cycle_depth_ > 1)
@@ -118,6 +131,7 @@ class TLSWrap : public AsyncWrap,
     for (; cycle_depth_ > 0; cycle_depth_--) {
       ClearIn();
       ClearOut();
+      // EncIn() doesn't exist, it happens via stream listener callbacks.
       EncOut();
     }
   }
@@ -139,16 +153,18 @@ class TLSWrap : public AsyncWrap,
   static void SetVerifyMode(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void EnableSessionCallbacks(
       const v8::FunctionCallbackInfo<v8::Value>& args);
-  static void EnableCertCb(
-      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void EnableTrace(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void EnableCertCb(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void DestroySSL(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetServername(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetServername(const v8::FunctionCallbackInfo<v8::Value>& args);
   static int SelectSNIContextCallback(SSL* s, int* ad, void* arg);
 
   crypto::SecureContext* sc_;
-  BIO* enc_in_ = nullptr;
-  BIO* enc_out_ = nullptr;
+  // BIO buffers hold encrypted data.
+  BIO* enc_in_ = nullptr;   // StreamListener fills this for SSL_read().
+  BIO* enc_out_ = nullptr;  // SSL_write()/handshake fills this for EncOut().
+  // Waiting for ClearIn() to pass to SSL_write().
   std::vector<uv_buf_t> pending_cleartext_input_;
   size_t write_size_ = 0;
   WriteWrap* current_write_ = nullptr;