tls: introduce client 'session' event

OpenSSL has supported async notification of sessions and tickets since
1.1.0 using SSL_CTX_sess_set_new_cb(), for all versions of TLS. Using
the async API is optional for TLS1.2 and below, but for TLS1.3 it will
be mandatory. Future-proof applications should start to use async
notification immediately. In the future, for TLS1.3, applications that
don't use the async API will silently, but gracefully, fail to resume
sessions and instead do a full handshake.

See: https://wiki.openssl.org/index.php/TLS1.3#Sessions

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

1 files changed, 46 insertions, 3 deletions

diff --git a/doc/api/tls.md b/doc/api/tls.md
index ccd1b7ad74..7add7d5fef 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -152,9 +152,9 @@ will create a new session. See [RFC 2246][] for more information, page 23 and
 Resumption using session identifiers is supported by most web browsers when
 making HTTPS requests.
 
-For Node.js, clients must call [`tls.TLSSocket.getSession()`][] after the
-[`'secureConnect'`][] event to get the session data, and provide the data to the
-`session` option of [`tls.connect()`][] to reuse the session. Servers must
+For Node.js, clients wait for the [`'session'`][] event to get the session data,
+and provide the data to the `session` option of a subsequent [`tls.connect()`][]
+to reuse the session. Servers must
 implement handlers for the [`'newSession'`][] and [`'resumeSession'`][] events
 to save and restore the session data using the session ID as the lookup key to
 reuse sessions. To reuse sessions across load balancers or cluster workers,
@@ -614,6 +614,45 @@ determine if the server certificate was signed by one of the specified CAs. If
 `tlsSocket.alpnProtocol` property can be checked to determine the negotiated
 protocol.
 
+### Event: 'session'
+<!-- YAML
+added: REPLACEME
+-->
+
+* `session` {Buffer}
+
+The `'session'` event is emitted on a client `tls.TLSSocket` when a new session
+or TLS ticket is available. This may or may not be before the handshake is
+complete, depending on the TLS protocol version that was negotiated. The event
+is not emitted on the server, or if a new session was not created, for example,
+when the connection was resumed. For some TLS protocol versions the event may be
+emitted multiple times, in which case all the sessions can be used for
+resumption.
+
+On the client, the `session` can be provided to the `session` option of
+[`tls.connect()`][] to resume the connection.
+
+See [Session Resumption][] for more information.
+
+Note: For TLS1.2 and below, [`tls.TLSSocket.getSession()`][] can be called once
+the handshake is complete.  For TLS1.3, only ticket based resumption is allowed
+by the protocol, multiple tickets are sent, and the tickets aren't sent until
+later, after the handshake completes, so it is necessary to wait for the
+`'session'` event to get a resumable session.  Future-proof applications are
+recommended to use the `'session'` event instead of `getSession()` to ensure
+they will work for all TLS protocol versions.  Applications that only expect to
+get or use 1 session should listen for this event only once:
+
+```js
+tlsSocket.once('session', (session) => {
+  // The session can be used immediately or later.
+  tls.connect({
+    session: session,
+    // Other connect options...
+  });
+});
+```
+
 ### tlsSocket.address()
 <!-- YAML
 added: v0.11.4
@@ -880,6 +919,9 @@ for debugging.
 
 See [Session Resumption][] for more information.
 
+Note: `getSession()` works only for TLS1.2 and below. Future-proof applications
+should use the [`'session'`][] event.
+
 ### tlsSocket.getTLSTicket()
 <!-- YAML
 added: v0.11.4
@@ -1540,6 +1582,7 @@ where `secureSocket` has the same API as `pair.cleartext`.
 [`'resumeSession'`]: #tls_event_resumesession
 [`'secureConnect'`]: #tls_event_secureconnect
 [`'secureConnection'`]: #tls_event_secureconnection
+[`'session'`]: #tls_event_session
 [`--tls-cipher-list`]: cli.html#cli_tls_cipher_list_list
 [`NODE_OPTIONS`]: cli.html#cli_node_options_options
 [`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves