Secure, modular server-side sessions.
This repo contains many packages that together implement traditional server-side sessions. Users who don't have a session yet are assigned a random 144-bit session ID that is the key on a storage backend. All session data is saved on a storage backend. Includes 110+ unit and property tests.
Backend (storage), in order to store the session data. Currently we support:
serversession-backend-acid-state(): Storage backend using
acid-state. This backend keeps sessions in memory but provides ACID guarantees using a transaction log. It can also be used without durability as a memory-only backend.
Frontend, bindings for your web framework of choice. Currently we support:
If your favorite storage backend or framework is not listed
above, please send us a pull request! The
package should work for any session that may be represented as a
mapping of keys to values.
- Using Yesod frontend + Persistent backend: GitHub link.
The session ID is generated via the
nonce package, which in
turn uses a CPRNG created from AES on CTR mode. The CPRNG is
reseed automatically from
/dev/urandom (or equivalent)
periodically. We use the base64url variant, thus providing 144
bits of entropy, which is more than enough to make guessing
session IDs impossible.
The session ID stays fixed most of the time. Anonymous users
receive session IDs unless their session remains empty (as an
optimization). The session ID can be invalidated in order to
session fixation attacks,
either automatically (see below) or manually (via
forceInvalidate). On a session fixation attack, the attacker
convinces the victim to use the same session ID as his and asks
the victim to log in. If the session is not invalidated upon
login, the attacker will now be in possession of a session ID
that is logged in as the victim. If the session is invalidated,
the victim receives a new session ID that the attacker doesn't
have any knowledge of.
We support both idle timeouts and absolute timeouts. Idle timeouts invalidate the session if a given amount of time has passed since the last request was made for a session. Absolute timeouts invalidate the session if a given amount of time has passed since the session was created, no matter the activity.
We have special support for authentication plugins that save information about the logged in user on a session variable:
The session key used by authentication plugin (e.g.,
yesod-auth) is recognized and saved separately on the database. This allows you to quickly identify all sessions of a given user. For example, you're able to implement a "log out everywhere" button.
Whenever the logged in user changes, the backend will also invalidate the current session ID and migrate the session data to a new ID. This prevents session fixation attacks while still allowing you to maintain session state accross login/logout boundaries.
Any authentication mechanism is supported as long as it uses a session variable.
We provide the following storage optimizations:
Empty sessions are not saved. This is done transparently: just insert a session variable and the session will materialize. Note that if your framework always creates a CSRF token (e.g., Snap), then this optimization will not apply you.
You can set the timeout resolution. Requests made within the timeout resolution that do not change any session variables will not update the session on the database. By default the timeout resolution is set to 10 minutes.
Session data types
serversession family is generalized with respect to the
session data type. We provide
Map Text ByteString, that is guaranteed to work with every backend
and frontend. However, you're able to create a custom data type
and use it as well, as long as you implement the typeclasses
needed by your backend and frontend.
The storage backends support basically anything they're able to
persistent backend accepts anything that can be
used as a
persistent field. The
acid-state backend accepts
anything that can be serialized via
backend accepts anything that can be stored as a Redis hash.
The frontends unfortunately are quite more limited. Yesod
insists that sessions be
Snap insists on
package allows any types of keys and values, but still expect a
map. Until the frameworks get generalized as well, it's a bit
difficult to take advantage of custom session data types.
These limitations may be addressed in the future. Right now, though, please bear in mind that:
There's no support for cleaning old sessions from the storage backends.
There's no way of setting timeouts and cookie persistence on a per-session basis, only on a global basis.
The Redis backend is not set to expire sessions yet.
persistentbackend does not automatically create an index for the auth ID. Thus, by default the
deleteAllSessionsOfAuthIdoperation will take linear time.
We stress test our backends to ensure they support almost every conceivable use case for sessions, but we only guarantee to support:
Every possible character and byte for keys and values, respectively.
At least one million keys per session.
Session values of at least 100 MiB.
Session keys of At least 1 MiB.
At least 200 independent sessions per user.
Yesod has always support client-side sessions via the
package: the session data is encrypted, signed, encoded and sent
to the client inside a cookie. When receiving a request, the
cookie is decoded, verified and decrypted. The server does not
have to maintain any state, so the client-side session backend is
as fast as the cryptographic primitives.
However, there are some disadvantages to client-side sessions:
Replay attacks. It's not possible to invalidate a session, for example. When logging out, a new cookie is sent with logged out session data. However, as the server doesn't maintain state about sessions, it will still accept the old, logged in cookie until it expires. One could set very small expiration times to mitigate this, but this would force users to relogin frequently. This server-side backend allows you to maintain long expiration times while still having secure logouts.
Cookie size. As the cookie contains the whole session data plus some overhead, care must be taken not to create too much session data. Yesod already saves the logged in user ID via
yesod-authand a XSRF token via
yesod-form. This server-side backend uses a cookie of fixed size (24 bytes).
No remote logout. In many instances it is desirable to invalidate sessions other than the current one. For example, the user may have changed their password, or the the site provides a button to cancel all logged in sessions besides the current one. This server-side backend allows you to invalidate sessions other than the current one via
Missing key rotation. Ideally,
clientsession's keys should be rotated periodically. In practice, support for key rotation has never been implemented on
clientsession. This server-side backend does not need to do key rotations, and the session ID CPRNG is automatically reseeded.
serversession package is
clientsession's rival, each has
their own advantages and disadvantages. However, both of them
can be used on different ecosystems and take security from the
Comparision to other packages
At the time of writing (2015-05-22), these are the session
packages that do not use either
Memorymodule, also supports
clientsessionmode): Server-side sessions. Works for
snap. Weak session ID generation. Vulnerable to session fixation attacks. Cannot invalidate other sessions.
salvia-sessions: Server-side sessions. Works only for
salvia. No built-in support for DB-backed sessions, only memory-backed ones. Weak session ID generation. Vulnerable to session fixation attacks. Cannot invalidate other sessions.
simple-session: Client-side sessions. Works for
simpleframework. No encryption. Authentication vulnerable to timing attacks.
scotty-session): Server-side sessions. Works for
Spock(code is not packaged separately). Only supports memory-backed sessions persisted on a file. Weak session ID generation. Vulnerable to session fixation attacks. Cannot invalidate other sessions.
wai-session: Server-side sessions. Works for
waiapplications. Weak session ID generation. Vulnerable to session fixation. Cannot invalidate other sessions. Out-of-the-box support for TokyoCabinet only.
yesod-session-redis: Server-side sessions. Works for Yesod and Redis. Weak session ID generation via
random. Vulnerable to session fixation. Cannot invalidate other sessions.
We apologize in advance if any information above is incorrect. Please contact us about any errors.
Assuming a version of
MAJOR.MINOR.PATCH, the following
conventions are used by the
serversession family of packages:
The PVP's versioning scheme is followed without changes. The important part is that either
MINORneeds to be increased whenever a breaking change is made, while only
PATCHneeds to be changed otherwise.
In addition to the PVP, we increment
MAJORonly when the
serversessioncore package makes a breaking change. This means that:
serversessioncore package always has
serversession-*packages have the same
serversession, while being free to have any
The scheme above is used to ensure consistent versioning of all packages even if they're not always released at the same time.