mirror of
https://libwebsockets.org/repo/libwebsockets
synced 2024-12-11 16:27:36 +00:00
122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
# 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 do anything special for Session Tickets, but
|
|
it's possible your TLS library will support them by default, as is reportedly the
|
|
case with mbedtls 2.28.1. Either way, it's expected Session IDs should work with
|
|
lws if enabled and your tls library supports them.
|
|
|
|
## 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.
|