1# Using TLS Session resumption 2 3Lws supports clientside session caching and session resumption on both mbedtls 4and openssl-type tls library backends, to accellerate connection re- 5establishment. 6 7## Background 8 9TLS specifies logical "sessions" that get "established" on both sides when the 10tls tunnel is negotiated... these are the object that gets validated by the 11certificate PKI. They each have a server-unique "Session ID" of up to 32 bytes 12each. 13 14Normally the default is that there is a new session negotiated per connection, 15so multiple connections to the same endpoint each negotiate fresh sessions from 16scratch. 17 18However tls servers typically maintain a cache of recent sessions, and where 19both the server and client still have a copy of a previously-negotiated session 20around, support the client explicitly requesting additional connections binding 21to the old session by asking for it by its Session ID at negotiation time. 22 23### Re-use of validated sessions 24 25The advantage is that the timeconsuming key exchange part of the negotiation can 26be skipped, and a connection-specific AES key agreed at both sides just by 27hashing on the secret held in the session object at each side. This allows new 28tunnels to be established much faster after the first, while the session from 29the first is still valid and available at both sides. 30 31Both the server and client may apply their own lifetime restriction to their 32copy of the session, the first side to expire it will cause a new session to be 33forced at the next reuse attempt. Lifetimes above 24h are not recommended by 34RFC5246. 35 36### Multiple concurrent use of validated sessions 37 38In addition, the session's scope is any connection to the server that knows the 39original session ID, because individual new AES keys are hashed from the session 40secret, multiple connections to the same endpoint can take advantage of a single 41valid session object. 42 43### Difference from Session Tickets 44 45TLS also supports sessions as bearer tokens, but these are generally considered 46as degrading security. Lws doesn't support Session Tickets, just reuse by 47Session IDs. 48 49## Support in lws 50 51Server-side TLS generally has session caching enabled by default. For client 52side, lws now enables `LWS_WITH_TLS_SESSIONS` at cmake by default, which adds 53a configurable tls session cache that is automatically kept updated with a 54MRU-sorted list of established sessions. 55 56It's also possible to serialize sessions and save and load them, but this has to 57be treated with caution. 58 59Filling, expiring and consulting the session cache for client connections is 60performed automatically. 61 62### tls library differences 63 64Mbedtls supports clientside session caching in lws, but it does not have a 65session message arrival callback to synchronize updating the client session 66cache like openssl does. 67 68Separately, the session cb in boringssl is reportedly nonfunctional at the 69moment. 70 71To solve both cases, lws will schedule a check for the session at +500ms after 72the tls negotiation completed, and for the case the connection doesn't last 73500ms or the server is slow issuing the message, also attempt to update the 74cache at the time the tls connection object is closing. 75 76### Session namespacing in lws 77 78Internally sessions are referred to by a vhostname.hostname.port tuple. 79 80### Configuring the clientside cache 81 82Session caches in lws exist in and are bound to the vhost. Different vhosts may 83provide different authentication (eg, client certs) to the same endpoint that 84another connection should not be able to take advantage of. 85 86The max size of this cache can be set at `.tls_session_cache_max` in the vhost 87creation info struct, if left at 0 then a default of 10 is applied. 88 89The Time-To-Live policy for sessions at the client can be set in seconds at 90`.tls_session_timeout`, by default whatever the tls library thinks it should be, 91perhaps 300s. 92 93You can disable session caching for a particular vhost by adding the vhost 94option flag `LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE` to `.options` at 95vhost creation time. 96 97### Session saving and loading 98 99Trying to make sessions really persistent is supported but requires extra 100caution. RFC5246 says 101 102 Applications that may be run in relatively insecure environments should not 103 write session IDs to stable storage. 104 105The issue is that while in process memory the session object is relatively 106secure compared to sensitive secrets and tls library data already in process 107memory. 108 109But when serialized to, eg, some external, unencrypted medium, the accessibility 110of what is basically a secret able to decrypt tls connections can become a 111security hazard. It's left to the user to take any necessary steps to secure 112sessions stored that way. 113 114For openssl, Public APIs are provided in `libwebsockets/lws-tls-sessions.h` to 115serialize any session in the cache associated with a vhost/host/port tuple, and 116to preload any available session into a vhost session cache by describing the 117endpoint hostname and port. 118 119The session saving and loading apis aren't supported for mbedtls yet. 120