-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Securely store session data in a client-side cookie.
--   
--   Achieves security through AES-CTR encryption and Skein-MAC-512-256
--   authentication. Uses Base64 encoding to avoid any issues with
--   characters.
@package clientsession
@version 0.9.1.1

-- | 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.
module Web.ClientSession

-- | 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 must have exactly 32 bytes (256
--   bits) while Skein-MAC-512-256 must have 64 bytes (512 bits).
--   
--   See also getDefaultKey and initKey.
data Key

-- | The initialization vector used by AES. Must be exactly 16 bytes long.
data IV

-- | Randomly construct a fresh initialization vector. You MUST NOT
--   reuse initialization vectors.
randomIV :: IO IV

-- | Construct an initialization vector from a ByteString. Fails if
--   there isn't exactly 16 bytes.
mkIV :: ByteString -> Maybe IV

-- | 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.
getKey :: FilePath -> IO Key

-- | Get the key from the named environment variable
--   
--   Assumes the value is a Base64-encoded string. If the variable is not
--   set, a random key will be generated, set in the environment, and the
--   Base64-encoded version printed on devstdout.
getKeyEnv :: String -> IO Key

-- | The default key file.
defaultKeyFile :: FilePath

-- | Simply calls getKey defaultKeyFile.
getDefaultKey :: IO Key

-- | 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).
--   
--   Note that the input string is assumed to be uniformly chosen from the
--   set of all 96-byte strings. In other words, each byte should be chosen
--   from the set of all byte values (0-255) with the same probability.
--   
--   In particular, this function does not do any kind of key stretching.
--   You should never feed it a password, for example.
--   
--   It's highly recommended to feed initKey only with
--   values generated by randomKey, unless you really know what
--   you're doing.
initKey :: ByteString -> Either String Key

-- | Generate a random Key. Besides the Key, the
--   ByteString passed to initKey is returned so that it
--   can be saved for later use.
randomKey :: IO (ByteString, Key)

-- | Generate a random Key, set a Base64-encoded version of it in
--   the given environment variable, then return it. Also prints the
--   generated string to devstdout.
randomKeyEnv :: String -> IO Key

-- | 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.
encrypt :: Key -> IV -> ByteString -> ByteString

-- | Same as encrypt, however randomly generates the initialization
--   vector for you.
encryptIO :: Key -> ByteString -> IO ByteString

-- | 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.
decrypt :: Key -> ByteString -> Maybe ByteString
instance GHC.Classes.Eq Web.ClientSession.Key
instance Data.Serialize.Serialize Web.ClientSession.Key
instance GHC.Show.Show Web.ClientSession.Key
instance GHC.Classes.Eq Web.ClientSession.IV
instance GHC.Classes.Ord Web.ClientSession.IV
instance GHC.Show.Show Web.ClientSession.IV
instance Data.Serialize.Serialize Web.ClientSession.IV
