-- 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:
--   
--   <ul>
--   <li>Encrypt the cookie data using AES in CTR mode. This allows you to
--   store sensitive information on the client side without worrying about
--   eavesdropping.</li>
--   <li>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).</li>
--   <li>Encode everything using Base64. Thus we avoid problems with
--   non-printable characters by giving the browser a simple string.</li>
--   </ul>
--   
--   Simple usage of the library involves just calling <a>getDefaultKey</a>
--   on the startup of your server, <a>encryptIO</a> when serializing
--   cookies and <a>decrypt</a> 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 <a>getDefaultKey</a> and <a>initKey</a>.
data Key

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

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

-- | Construct an initialization vector from a <a>ByteString</a>. 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 <tt><i>dev</i>stdout</tt>.
getKeyEnv :: String -> IO Key

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

-- | Simply calls <a>getKey</a> <a>defaultKeyFile</a>.
getDefaultKey :: IO Key

-- | Initializes a <a>Key</a> from a random <a>ByteString</a>. 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 <i>highly</i> recommended to feed <tt>initKey</tt> only with
--   values generated by <a>randomKey</a>, unless you really know what
--   you're doing.
initKey :: ByteString -> Either String Key

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

-- | Generate a random <a>Key</a>, set a Base64-encoded version of it in
--   the given environment variable, then return it. Also prints the
--   generated string to <tt><i>dev</i>stdout</tt>.
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 <a>encrypt</a>, 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
