| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Web.Spock.Session.Cookie
Description
Encrypted, authenticated sessions stored entirely in a browser cookie. Uses Crypton's XChaCha20-Poly1305 with fresh 192-bit OS-random nonces. Keys are supplied by the application; this library never writes them to disk.
Use cookieSessionCodec with defaultClientSessionCfg and ClientSessions
from Web.Spock.Config.
Spock checks the authenticated expiry using the server clock. Use HTTPS,
Secure/HttpOnly cookies and CSRF protection, for example defaultBrowserSpockCfg.
Stateless cookies cannot revoke individual sessions or merge simultaneous requests. Logout expires this browser's cookie; copies remain replayable until expiry or key removal. Use a server backend when immediate revocation or concurrent counters are required. Keep payloads small; Spock limits the entire Set-Cookie value to 4096 bytes and rejects oversized changes before saving them.
Synopsis
- data CookieKey
- data CookieKeyRing
- data CookieKeyError
- cookieKey :: Text -> ByteString -> Either CookieKeyError CookieKey
- cookieKeyRing :: Text -> CookieKey -> [CookieKey] -> Either CookieKeyError CookieKeyRing
- cookieSessionCodec :: (ToJSON sess, FromJSON sess) => CookieKeyRing -> ClientSessionCodec sess
Documentation
Validated 256-bit key and public wire identifier. No Show instance; identifiers are visible in the cookie, but key material must come from a secret manager.
data CookieKeyRing Source #
Application namespace, primary encryption key, and accepted older keys. Deploy a new primary with the old key still accepted, then remove the old key after its last possible session expiry. All workers must share the key ring.
data CookieKeyError Source #
Configuration errors never include key material or cookie contents.
Constructors
| InvalidKeyId | |
| InvalidKeyLength | |
| InvalidNamespace | |
| DuplicateKeyId | |
| TooManyKeys | |
| CookieEncryptionFailure |
Instances
| Eq CookieKeyError Source # | |
Defined in Web.Spock.Session.Cookie Methods (==) :: CookieKeyError -> CookieKeyError -> Bool (/=) :: CookieKeyError -> CookieKeyError -> Bool | |
| Exception CookieKeyError Source # | |
Defined in Web.Spock.Session.Cookie Methods toException :: CookieKeyError -> SomeException fromException :: SomeException -> Maybe CookieKeyError displayException :: CookieKeyError -> String backtraceDesired :: CookieKeyError -> Bool | |
| Show CookieKeyError Source # | |
Defined in Web.Spock.Session.Cookie Methods showsPrec :: Int -> CookieKeyError -> ShowS show :: CookieKeyError -> String showList :: [CookieKeyError] -> ShowS | |
cookieKey :: Text -> ByteString -> Either CookieKeyError CookieKey Source #
A 32-byte key and a 1–32 character identifier using ASCII letters, digits, underscore or hyphen. Generate keys with a cryptographic OS random source.
cookieKeyRing :: Text -> CookieKey -> [CookieKey] -> Either CookieKeyError CookieKeyRing Source #
Bind cookies to an application namespace (1–128 UTF-8 bytes). Accept at most seven old keys, with unique identifiers across the entire ring.
cookieSessionCodec :: (ToJSON sess, FromJSON sess) => CookieKeyRing -> ClientSessionCodec sess Source #
A versioned JSON codec. All session fields are encrypted and authenticated; the namespace, cookie name, wire version and key identifier are authenticated as associated data. Decoding never releases unauthenticated JSON. An accepted old key triggers reissue with the primary key, including with fixed expiry.
Changing the namespace or removing a key invalidates affected cookies. The decoder also bounds input size before attempting cryptography. It returns Nothing for malformed, tampered or unknown-key input; the manager creates a new empty session only if the request uses one.