Portability | portable |
---|---|
Stability | Stable |
Maintainer | Michael Snoyman <michael@snoyman.com> |
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.
- data Key = Key {}
- data IV
- randomIV :: IO IV
- mkIV :: ByteString -> Maybe IV
- getKey :: FilePath -> IO Key
- defaultKeyFile :: FilePath
- getDefaultKey :: IO Key
- initKey :: ByteString -> Either String Key
- encrypt :: Key -> IV -> ByteString -> ByteString
- encryptIO :: Key -> ByteString -> IO ByteString
- decrypt :: Key -> ByteString -> Maybe ByteString
Automatic key generation
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
.
The initialization vector used by AES in CBC mode. Should be exactly 16 bytes long.
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.
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.
Simply calls getKey
defaultKeyFile
.
initKey :: ByteString -> Either String KeySource
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
:: Key | Key of the server. |
-> IV | New, random initialization vector (see |
-> 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 ByteStringSource
Same as encrypt
, however randomly generates the
initialization vector for you.
:: 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.