Portability	portable
Stability	Stable
Maintainer	Michael Snoyman <michael@snoyman.com>

Web.ClientSession

Contents

Automatic key generation
Actual encryption/decryption

Description

Stores session data in a client cookie. In order to do so, we:

Encrypt the cookie data using AES in CBC mode. This allows you to store sensitive information on the client side without worrying about eavesdropping.
Sign the encrypted cookie data using HMAC-SHA256. Besides detecting potential errors in storage or transmission of the cookies (integrity), the HMAC-SHA256 code also avoids malicious modifications of the cookie data by assuring you that the cookie data really was generated by this server (authentication).
Encode everything using Base64. Thus we avoid problems with non-printable characters by giving the browser a simple string.

Simple usage of the library involves just calling getDefaultKey on the startup of your server, encryptIO when serializing cookies and decrypt when parsing then back.

Synopsis

Automatic key generation

data Key Source

The keys used to store the cookies. We have an AES key used to encrypt the cookie and a HMAC-SHA256 key used verify the authencity and integrity of the cookie. The AES key needs to have exactly 32 bytes (256 bits). The HMAC-SHA256 should have 64 bytes (512 bits), which is the block size of SHA256, but any size may be used.

See also getDefaultKey and initKey.

Constructors

Key
Fields aesKey :: Key hmacKey :: MacKey

Instances

Eq Key
Show Key

data IV Source

The initialization vector used by AES in CBC mode. Should be exactly 16 bytes long.

Instances

Show IV

randomIV :: IO IV Source

Randomly construct a fresh initialization vector. You should not reuse initialization vectors.

mkIV :: ByteString -> Maybe IV Source

Construct an initialization vector from a ByteString. Fails if there isn't exactly 16 bytes.

getKey Source

Arguments

:: FilePath	File name where key is stored.
-> IO Key	The actual key.

Get a key from the given text file.

If the file does not exist or is corrupted a random key will be generated and stored in that file.

defaultKeyFile :: FilePath Source

The default key file.

getDefaultKey :: IO Key Source

Simply calls getKey defaultKeyFile.

initKey :: ByteString -> Either String Key Source

Initializes a Key from a random ByteString. It's better to give a ByteString with exactly 64 bytes, but anything with at least 32 bytes will work.

Actual encryption/decryption

encrypt Source

Arguments

:: Key	Key of the server.
-> IV	New, random initialization vector (see `randomIV`).
-> ByteString	Serialized cookie data.
-> ByteString	Encoded cookie data to be given to the client browser.

Encrypt (AES-CBC), sign (HMAC-SHA256) and encode (Base64) the given cookie data. The returned byte string is ready to be used in a response header.

encryptIO :: Key -> ByteString -> IO ByteString Source

Same as encrypt, however randomly generates the initialization vector for you.

decrypt Source

Arguments

:: Key	Key of the server.
-> ByteString	Encoded cookie data given by the browser.
-> Maybe ByteString	Serialized cookie data.

Decode (Base64), verify the integrity and authenticity (HMAC-SHA256) and decrypt (AES-CBC) the given encoded cookie data. Returns the original serialized cookie data. Fails if the data is corrupted.