Copyright	(c) 2016 Al Zohali
License	BSD3
Maintainer	Al Zohali <zohl@fmap.me>
Stability	experimental
Safe Haskell	None
Language	Haskell2010

Servant.Server.Experimental.Auth.Cookie

Description

Authentication via encrypted client-side cookies, inspired by client-session library by Michael Snoyman and based on ideas of the paper "A Secure Cookie Protocol" by Alex Liu et al.

Synopsis

Documentation

type CipherAlgorithm c = c -> IV c -> ByteString -> ByteString #

A type for encryption and decryption functions operating on ByteStrings.

type family AuthCookieData #

A type family that maps user-defined data to AuthServerData.

data Cookie #

Cookie representation.

Constructors

Cookie
Fields cookieIV :: ByteString The initialization vector cookieExpirationTime :: UTCTime The cookie's expiration time cookiePayload :: ByteString The payload

data AuthCookieException #

The exception is thrown when something goes wrong with this package.

Constructors

CannotMakeIV ByteString	Could not make `IV` for block cipher.
BadProperKey CryptoError	Could not initialize a cipher context.
TooShortProperKey Int Int	The key is too short for current cipher algorithm. Arguments of this constructor: minimal key length, actual key length.
IncorrectMAC ByteString	Thrown when Message Authentication Code (MAC) is not correct.
CannotParseExpirationTime ByteString	Thrown when expiration time cannot be parsed.
CookieExpired UTCTime UTCTime	Thrown when `Cookie` has expired. Arguments of the constructor: expiration time, actual time.
SessionDeserializationFailed String	This is thrown when `runGet` or `decode` blows up.

Instances

Eq AuthCookieException #
Methods (==) :: AuthCookieException -> AuthCookieException -> Bool # (/=) :: AuthCookieException -> AuthCookieException -> Bool #
Show AuthCookieException #
Methods showsPrec :: Int -> AuthCookieException -> ShowS # show :: AuthCookieException -> String # showList :: [AuthCookieException] -> ShowS #
Exception AuthCookieException #
Methods toException :: AuthCookieException -> SomeException # fromException :: SomeException -> Maybe AuthCookieException # displayException :: AuthCookieException -> String #

data WithMetadata a #

Wrapper for cookies and sessions to keep some related metadata.

Constructors

WithMetadata
Fields wmData :: a Value itself wmRenew :: Bool Whether we should renew cookies/session

type Cookied a = Headers '[Header "Set-Cookie" EncryptedSession] a #

Helper type to wrap endpoints.

cookied #

Arguments

:: (Serialize a, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> RandomSource	Random source to use
-> k	Instance of `ServerKeySet` to use
-> (a -> r)	Implementation of an endpoint
-> WithMetadata a -> Handler (Cookied r)	Cookied endpoint

Wrapper for an implementation of an endpoint to make it automatically renew the cookies.

data RandomSource #

A wrapper of self-resetting DRG suitable for concurrent usage.

mkRandomSource #

Arguments

:: (MonadIO m, DRG d)
=> IO d	How to get deterministic random generator
-> Int	Threshold (number of bytes to be generated before resetting)
-> m RandomSource	New `RandomSource` value

Constructor for RandomSource value.

getRandomBytes #

Arguments

:: MonadIO m
=> RandomSource	The source of random numbers
-> Int	How many random bytes to generate
-> m ByteString	The generated bytes in form of a `ByteString`

Extract pseudo-random bytes from RandomSource.

generateRandomBytes :: Int -> IO ByteString #

Generates random sequence of bytes from new DRG

type ServerKey = ByteString #

Internal representation of a server key.

class ServerKeySet k where #

Interface for a set of server keys.

Minimal complete definition

getKeys, removeKey

Methods

getKeys :: (MonadThrow m, MonadIO m) => k -> m (ServerKey, [ServerKey]) #

Retrieve current and rotated keys respectively.

removeKey :: (MonadThrow m, MonadIO m) => k -> ServerKey -> m () #

Non-graciously remove the key from a keyset.

Instances

ServerKeySet PersistentServerKey #
Methods getKeys :: (MonadThrow m, MonadIO m) => PersistentServerKey -> m (ServerKey, [ServerKey]) # removeKey :: (MonadThrow m, MonadIO m) => PersistentServerKey -> ServerKey -> m () #
Eq s => ServerKeySet (RenewableKeySet s p) #
Methods getKeys :: (MonadThrow m, MonadIO m) => RenewableKeySet s p -> m (ServerKey, [ServerKey]) # removeKey :: (MonadThrow m, MonadIO m) => RenewableKeySet s p -> ServerKey -> m () #

data PersistentServerKey #

A keyset containing only one key, that doesn't change.

Instances

ServerKeySet PersistentServerKey #
Methods getKeys :: (MonadThrow m, MonadIO m) => PersistentServerKey -> m (ServerKey, [ServerKey]) # removeKey :: (MonadThrow m, MonadIO m) => PersistentServerKey -> ServerKey -> m () #

mkPersistentServerKey :: ByteString -> PersistentServerKey #

Create instance of PersistentServerKey.

data RenewableKeySet s p #

Customizable key set, that provides partial implementation of ServerKeySet.

Instances

Eq s => ServerKeySet (RenewableKeySet s p) #
Methods getKeys :: (MonadThrow m, MonadIO m) => RenewableKeySet s p -> m (ServerKey, [ServerKey]) # removeKey :: (MonadThrow m, MonadIO m) => RenewableKeySet s p -> ServerKey -> m () #

data RenewableKeySetHooks s p #

Customizable actions for RenewableKeySet.

Constructors

RenewableKeySetHooks

Fields

rkshNewState :: forall m. (MonadIO m, MonadThrow m) => p -> ([ServerKey], s) -> m ([ServerKey], s)
Called when a keyset needs to refresh it's state. It's result might be discarded occasionally in favour of result yielded in another thread.
rkshNeedUpdate :: forall m. (MonadIO m, MonadThrow m) => p -> ([ServerKey], s) -> m Bool
Called before retrieving the keys and refreshing the state.
rkshRemoveKey :: forall m. (MonadIO m, MonadThrow m) => p -> ServerKey -> m ()
Called after removing the key. This hook is called only if the key belongs to a keyset and called once per key. The only purpose of it is to clear the garbage after removing the key. The state might differs after removing the key and before calling the hook, therefore the hook doesn't rely on the state.

mkRenewableKeySet #

Arguments

:: MonadIO m
=> RenewableKeySetHooks s p	Hooks
-> p	Parameters
-> s	Initial state
-> m (RenewableKeySet s p)

Create instance of RenewableKeySet.

data AuthCookieSettings where #

Options that determine authentication mechanisms. Use def to get default value of this type.

Constructors

AuthCookieSettings :: (HashAlgorithm h, BlockCipher c) => {..} -> AuthCookieSettings

Fields

acsSessionField :: ByteString
Name of a cookie which stores session object
acsCookieFlags :: [ByteString]
Session cookie's flags
acsMaxAge :: NominalDiffTime
For how long the cookie will be valid (corresponds to “Max-Age” attribute).
acsExpirationFormat :: String
Expiration format as in formatTime.
acsPath :: ByteString
Scope of the cookie (corresponds to “Path” attribute).
acsHashAlgorithm :: Proxy h
Hash algorithm that will be used in hmac.
acsCipher :: Proxy c
Symmetric cipher that will be used in encryption.
acsEncryptAlgorithm :: CipherAlgorithm c
Algorithm to encrypt cookies.
acsDecryptAlgorithm :: CipherAlgorithm c
Algorithm to decrypt cookies.

Instances

Default AuthCookieSettings #
Methods def :: AuthCookieSettings #

newtype EncryptedSession #

A newtype wrapper over ByteString

Constructors

EncryptedSession ByteString

Instances

Eq EncryptedSession #
Methods (==) :: EncryptedSession -> EncryptedSession -> Bool # (/=) :: EncryptedSession -> EncryptedSession -> Bool #
Show EncryptedSession #
Methods showsPrec :: Int -> EncryptedSession -> ShowS # show :: EncryptedSession -> String # showList :: [EncryptedSession] -> ShowS #
ToHttpApiData EncryptedSession #
Methods toUrlPiece :: EncryptedSession -> Text # toEncodedUrlPiece :: EncryptedSession -> Builder # toHeader :: EncryptedSession -> ByteString # toQueryParam :: EncryptedSession -> Text #

emptyEncryptedSession :: EncryptedSession #

An empty EncryptedSession

encryptCookie #

Arguments

:: (MonadIO m, MonadThrow m, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> k	Instance of `ServerKeySet` to use
-> Cookie	The `Cookie` to encrypt
-> m (Tagged EncryptedCookie ByteString)	Encrypted `Cookie` is form of `ByteString`

Encrypt given Cookie with server key.

The function can throw the following exceptions (of type AuthCookieException):

decryptCookie #

Arguments

:: (MonadIO m, MonadThrow m, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> k	Instance of `ServerKeySet` to use
-> Tagged EncryptedCookie ByteString	The `ByteString` to decrypt
-> m (WithMetadata Cookie)	The decrypted `Cookie`

Decrypt a Cookie from ByteString.

The function can throw the following exceptions (of type AuthCookieException):

encryptSession #

Arguments

:: (MonadIO m, MonadThrow m, Serialize a, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> RandomSource	Random source to use
-> k	Instance of `ServerKeySet` to use
-> a	Session value
-> m (Tagged SerializedEncryptedCookie ByteString)	Serialized and encrypted session

Pack session object into a cookie. The function can throw the same exceptions as encryptCookie.

decryptSession #

Arguments

:: (MonadIO m, MonadThrow m, Serialize a, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> k	Instance of `ServerKeySet` to use
-> Tagged SerializedEncryptedCookie ByteString	Cookie in binary form
-> m (WithMetadata a)	Unpacked session value

Unpack session value from a cookie. The function can throw the same exceptions as decryptCookie.

addSession #

Arguments

:: (MonadIO m, MonadThrow m, Serialize a, AddHeader (e :: Symbol) EncryptedSession s r, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> RandomSource	Random source to use
-> k	Instance of `ServerKeySet` to use
-> a	The session value
-> s	Response to add session to
-> m r	Response with the session added

Add cookie header to response. The function can throw the same exceptions as encryptSession.

removeSession #

Arguments

:: (Monad m, AddHeader (e :: Symbol) EncryptedSession s r)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> s	Response to return with session removed
-> m r	Response with the session "removed"

Remove a session by invalidating the cookie.

addSessionToErr #

Arguments

:: (MonadIO m, MonadThrow m, Serialize a, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> RandomSource	Random source to use
-> k	Instance of `ServerKeySet` to use
-> a	The session value
-> ServantErr	Servant error to add the cookie to
-> m ServantErr

Add cookie session to error allowing to set cookie even if response is not 200.

removeSessionFromErr #

Arguments

:: Monad m
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> ServantErr	Servant error to add the cookie to
-> m ServantErr

Remove a session by invalidating the cookie. Cookie expiry date is set at 0 and content is wiped

getSession #

Arguments

:: (MonadIO m, MonadThrow m, Serialize a, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> k	`ServerKeySet` to use
-> Request	The request
-> m (Maybe (WithMetadata a))	The result

Request handler that checks cookies. If Cookie is just missing, you get Nothing, but if something is wrong with its format, getSession can throw the same exceptions as decryptSession.

defaultAuthHandler #

Arguments

:: (Serialize a, ServerKeySet k)
=> AuthCookieSettings	Options, see `AuthCookieSettings`
-> k	Instance of `ServerKeySet` to use
-> AuthHandler Request (WithMetadata a)	The result

Cookie authentication handler.

renderSession :: (MonadIO m, MonadThrow m, Serialize a, ServerKeySet k) => AuthCookieSettings -> RandomSource -> k -> a -> m ByteString #

Render session cookie to ByteString.

parseSessionRequest :: AuthCookieSettings -> RequestHeaders -> Maybe (Tagged SerializedEncryptedCookie ByteString) #

Parse session cookie from RequestHeaders.

parseSessionResponse :: AuthCookieSettings -> ResponseHeaders -> Maybe (Tagged SerializedEncryptedCookie ByteString) #

Parse session cookie from ResponseHeaders.

Eq Cookie #
Methods (==) :: Cookie -> Cookie -> Bool # (/=) :: Cookie -> Cookie -> Bool #
Show Cookie #
Methods showsPrec :: Int -> Cookie -> ShowS # show :: Cookie -> String # showList :: [Cookie] -> ShowS #