xref: /aosp_15_r20/external/libwebsockets/READMEs/README.tls-sessions.md (revision 1c60b9aca93fdbc9b5f19b2d2194c91294b22281)

# Using TLS Session resumption

Lws supports clientside session caching and session resumption on both mbedtls
and openssl-type tls library backends, to accellerate connection re-
establishment.

## Background

TLS specifies logical "sessions" that get "established" on both sides when the
tls tunnel is negotiated... these are the object that gets validated by the
certificate PKI.  They each have a server-unique "Session ID" of up to 32 bytes
each.

Normally the default is that there is a new session negotiated per connection,
so multiple connections to the same endpoint each negotiate fresh sessions from
scratch.

However tls servers typically maintain a cache of recent sessions, and where
both the server and client still have a copy of a previously-negotiated session
around, support the client explicitly requesting additional connections binding
to the old session by asking for it by its Session ID at negotiation time.

### Re-use of validated sessions

The advantage is that the timeconsuming key exchange part of the negotiation can
be skipped, and a connection-specific AES key agreed at both sides just by
hashing on the secret held in the session object at each side.  This allows new
tunnels to be established much faster after the first, while the session from
the first is still valid and available at both sides.

Both the server and client may apply their own lifetime restriction to their
copy of the session, the first side to expire it will cause a new session to be
forced at the next reuse attempt.  Lifetimes above 24h are not recommended by
RFC5246.

### Multiple concurrent use of validated sessions

In addition, the session's scope is any connection to the server that knows the
original session ID, because individual new AES keys are hashed from the session
secret, multiple connections to the same endpoint can take advantage of a single
valid session object.

### Difference from Session Tickets

TLS also supports sessions as bearer tokens, but these are generally considered
as degrading security.  Lws doesn't support Session Tickets, just reuse by
Session IDs.

## Support in lws

Server-side TLS generally has session caching enabled by default.  For client
side, lws now enables `LWS_WITH_TLS_SESSIONS` at cmake by default, which adds
a configurable tls session cache that is automatically kept updated with a
MRU-sorted list of established sessions.

It's also possible to serialize sessions and save and load them, but this has to
be treated with caution.

Filling, expiring and consulting the session cache for client connections is
performed automatically.

### tls library differences

Mbedtls supports clientside session caching in lws, but it does not have a
session message arrival callback to synchronize updating the client session
cache like openssl does.

Separately, the session cb in boringssl is reportedly nonfunctional at the
moment.

To solve both cases, lws will schedule a check for the session at +500ms after
the tls negotiation completed, and for the case the connection doesn't last
500ms or the server is slow issuing the message, also attempt to update the
cache at the time the tls connection object is closing.

### Session namespacing in lws

Internally sessions are referred to by a vhostname.hostname.port tuple.

### Configuring the clientside cache

Session caches in lws exist in and are bound to the vhost.  Different vhosts may
provide different authentication (eg, client certs) to the same endpoint that
another connection should not be able to take advantage of.

The max size of this cache can be set at `.tls_session_cache_max` in the vhost
creation info struct, if left at 0 then a default of 10 is applied.

The Time-To-Live policy for sessions at the client can be set in seconds at
`.tls_session_timeout`, by default whatever the tls library thinks it should be,
perhaps 300s.

You can disable session caching for a particular vhost by adding the vhost
option flag `LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE` to `.options` at
vhost creation time.

### Session saving and loading

Trying to make sessions really persistent is supported but requires extra
caution.  RFC5246 says

   Applications that may be run in relatively insecure environments should not
   write session IDs to stable storage.

The issue is that while in process memory the session object is relatively
secure compared to sensitive secrets and tls library data already in process
memory.

But when serialized to, eg, some external, unencrypted medium, the accessibility
of what is basically a secret able to decrypt tls connections can become a
security hazard.  It's left to the user to take any necessary steps to secure
sessions stored that way.

For openssl, Public APIs are provided in `libwebsockets/lws-tls-sessions.h` to
serialize any session in the cache associated with a vhost/host/port tuple, and
to preload any available session into a vhost session cache by describing the
endpoint hostname and port.

The session saving and loading apis aren't supported for mbedtls yet.