clientsession-0.7.3.2: Securely store session data in a client-side cookie.

Portabilityportable
StabilityStable
MaintainerMichael Snoyman <michael@snoyman.com>

Web.ClientSession

Contents

Description

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

  • Encrypt the cookie data using AES in CTR mode. This allows you to store sensitive information on the client side without worrying about eavesdropping.
  • Authenticate the encrypted cookie data using Skein-MAC-512-256. Besides detecting potential errors in storage or transmission of the cookies (integrity), the MAC also avoids malicious modifications of the cookie data by assuring you that the cookie data really was generated by this server (authenticity).
  • 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 Skein-MAC-512-256 key used verify the authencity and integrity of the cookie. The AES key needs to have exactly 32 bytes (256 bits) while Skein-MAC-512-256 should have 64 bytes (512 bits).

See also getDefaultKey and initKey.

Constructors

Key 

Fields

aesKey :: AES256

AES key with 32 bytes.

macKey :: ByteString -> Skein_512_256

Skein-MAC key. Instead of storing the key data, we store a partially applied function for calculating the MAC (see skeinMAC').

Instances

Show Key

Dummy Show instance.

type IV = IV AES256Source

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

randomIV :: IO IVSource

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

mkIV :: ByteString -> Maybe IVSource

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

getKeySource

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 :: FilePathSource

The default key file.

initKey :: ByteString -> Either String KeySource

Initializes a Key from a random ByteString. Fails if there isn't exactly 96 bytes (256 bits for AES and 512 bits for Skein-MAC-512-512).

Actual encryption/decryption

encryptSource

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-CTR), authenticate (Skein-MAC-512-256) and encode (Base64) the given cookie data. The returned byte string is ready to be used in a response header.

encryptIO :: Key -> ByteString -> IO ByteStringSource

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

decryptSource

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 (Skein-MAC-512-256) and decrypt (AES-CTR) the given encoded cookie data. Returns the original serialized cookie data. Fails if the data is corrupted.