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.

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 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.

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

type AuthCookieExceptionHandler = forall a. AuthCookieException -> Handler (Maybe (ExtendedPayloadWrapper a))

Type for exception handler.

type AuthCookieHandler a

Arguments

 = ServerKeySet k

=> AuthCookieSettings

Options, see AuthCookieSettings

-> k

Instance of ServerKeySet to use

-> AuthHandler Request (ExtendedPayloadWrapper a)

The result

Type for cookied handler.

data PayloadWrapper a

Wrapper for session value that goes into cookies' payload.

Constructors

PayloadWrapper

Fields

• pwSession :: a
• pwSettings :: SessionSettings
• pwExpiration :: UTCTime

Instances

Generic (PayloadWrapper a)

Associated Types

type Rep (PayloadWrapper a) :: * -> *

Methods

from :: PayloadWrapper a -> Rep (PayloadWrapper a) x

to :: Rep (PayloadWrapper a) x -> PayloadWrapper a

Serialize a => Serialize (PayloadWrapper a)

Methods

put :: Putter (PayloadWrapper a)

get :: Get (PayloadWrapper a)

type Rep (PayloadWrapper a)

type Rep (PayloadWrapper a) = D1 (MetaData "PayloadWrapper" "Servant.Server.Experimental.Auth.Cookie" "servant-auth-cookie-0.6.0-1Iu8dtw7QNMD6YVqtc0Cd9" False) (C1 (MetaCons "PayloadWrapper" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "pwSession") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a)) ((:*:) (S1 (MetaSel (Just Symbol "pwSettings") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 SessionSettings)) (S1 (MetaSel (Just Symbol "pwExpiration") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 UTCTime)))))

data ExtendedPayloadWrapper a

Wrapper for session value with metadata that doesn't go into payload.

Constructors

ExtendedPayloadWrapper

Fields

• epwSession :: a
• epwSettings :: SessionSettings
• epwExpiration :: UTCTime
• epwRenew :: Bool

Instances

(Serialize c, CookiedWrapperClass b b' c) => CookiedWrapperClass (c -> b) (ExtendedPayloadWrapper c -> b') c

Methods

wrapCookied :: ServerKeySet k => (AuthCookieSettings, RandomSource, k, Proxy * c) -> Maybe (PayloadWrapper c) -> (c -> b) -> ExtendedPayloadWrapper c -> b'

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

Helper type to wrap endpoints.

type CookiedWrapper c = forall f r. CookiedWrapperClass f r c => f -> r

Type for curried cookied function (with fixed settings, random source, keyset and session type).

class CookiedWrapperClass f r c where

Class of functions that can be wrapped with cookied.

Minimal complete definition

wrapCookied

Methods

wrapCookied :: ServerKeySet k => (AuthCookieSettings, RandomSource, k, Proxy c) -> Maybe (PayloadWrapper c) -> f -> r

Instances

Serialize c => CookiedWrapperClass (Handler b) (Handler (Cookied b)) c

Methods

wrapCookied :: ServerKeySet k => (AuthCookieSettings, RandomSource, k, Proxy * c) -> Maybe (PayloadWrapper c) -> Handler b -> Handler (Cookied b)

(Serialize c, CookiedWrapperClass b b' c) => CookiedWrapperClass (a -> b) (a -> b') c

Methods

wrapCookied :: ServerKeySet k => (AuthCookieSettings, RandomSource, k, Proxy * c) -> Maybe (PayloadWrapper c) -> (a -> b) -> a -> b'

(Serialize c, CookiedWrapperClass b b' c) => CookiedWrapperClass (c -> b) (ExtendedPayloadWrapper c -> b') c

Methods

wrapCookied :: ServerKeySet k => (AuthCookieSettings, RandomSource, k, Proxy * c) -> Maybe (PayloadWrapper c) -> (c -> b) -> ExtendedPayloadWrapper c -> b'

cookied

Arguments

:: (ServerKeySet k, Serialize c)

=> AuthCookieSettings

Options, see AuthCookieSettings

-> RandomSource

Random source to use

-> k

Instance of ServerKeySet to use

-> Proxy c

Type of session

-> CookiedWrapper c

Wrapper that transforms given functions.

Wrapper for endpoints that use cookies. It transforms function of type: >>> q1 -> q2 -> ... -> Session -> ... -> qN -> Handler r into >>> q1 -> q2 -> ... -> ExtendedPayloadWrapper Session -> ... qN -> Handler (Cookied r)

Non-session variables number can be arbitrary. It supposed to be used in tandem with Cookied type.

Using this wrapper requires FlexibleContexts extention to be turned on. In case of curring cookied function, it's highly recommended to provide signature for this (see CookiedWrapper).

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” or Expires attribute).

• 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

data SessionSettings

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

Constructors

SessionSettings

Fields

• ssExpirationType :: ExpirationType

  How to represent expiration to the client's browser.

• ssAutoRenew :: Bool

  Whether to renew cookies automatically.

Instances

Eq SessionSettings

Methods

(==) :: SessionSettings -> SessionSettings -> Bool

(/=) :: SessionSettings -> SessionSettings -> Bool

Show SessionSettings

Methods

showsPrec :: Int -> SessionSettings -> ShowS

show :: SessionSettings -> String

showList :: [SessionSettings] -> ShowS

Generic SessionSettings

Associated Types

type Rep SessionSettings :: * -> *

Methods

from :: SessionSettings -> Rep SessionSettings x

to :: Rep SessionSettings x -> SessionSettings

Serialize SessionSettings

Methods

put :: Putter SessionSettings

get :: Get SessionSettings

Default SessionSettings

Methods

def :: SessionSettings

type Rep SessionSettings

type Rep SessionSettings = D1 (MetaData "SessionSettings" "Servant.Server.Experimental.Auth.Cookie" "servant-auth-cookie-0.6.0-1Iu8dtw7QNMD6YVqtc0Cd9" False) (C1 (MetaCons "SessionSettings" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "ssExpirationType") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ExpirationType)) (S1 (MetaSel (Just Symbol "ssAutoRenew") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Bool))))

data ExpirationType

How to represent expiration to the client's browser.

Constructors

Expires

cookies will be provided with Expires flag. Deprecated in favour of 'Max-Age'.

MaxAge

cookies will be provided with 'Max-Age' flag. Doesn't work with older versions of IE.

Session

cookies will be removed when the user closes the browser.

Instances

Eq ExpirationType

Methods

(==) :: ExpirationType -> ExpirationType -> Bool

(/=) :: ExpirationType -> ExpirationType -> Bool

Show ExpirationType

Methods

showsPrec :: Int -> ExpirationType -> ShowS

show :: ExpirationType -> String

showList :: [ExpirationType] -> ShowS

Generic ExpirationType

Associated Types

type Rep ExpirationType :: * -> *

Methods

from :: ExpirationType -> Rep ExpirationType x

to :: Rep ExpirationType x -> ExpirationType

Serialize ExpirationType

Methods

put :: Putter ExpirationType

get :: Get ExpirationType

Default ExpirationType

Methods

def :: ExpirationType

type Rep ExpirationType

type Rep ExpirationType = D1 (MetaData "ExpirationType" "Servant.Server.Experimental.Auth.Cookie" "servant-auth-cookie-0.6.0-1Iu8dtw7QNMD6YVqtc0Cd9" False) ((:+:) (C1 (MetaCons "Expires" PrefixI False) U1) ((:+:) (C1 (MetaCons "MaxAge" PrefixI False) U1) (C1 (MetaCons "Session" PrefixI False) U1)))

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

Serialize c => CookiedWrapperClass (Handler b) (Handler (Cookied b)) c

Methods

wrapCookied :: ServerKeySet k => (AuthCookieSettings, RandomSource, k, Proxy * c) -> Maybe (PayloadWrapper c) -> Handler b -> Handler (Cookied b)

emptyEncryptedSession :: EncryptedSession

An empty EncryptedSession

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

-> SessionSettings

Session settings

-> a

Session value

-> m (Tagged SerializedEncryptedCookie ByteString)

Serialized and encrypted session

Pack session object into a cookie.

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

• TooShortProperKey
• CannotMakeIV
• BadProperKey

decryptSession

Arguments

:: (MonadIO m, MonadThrow m, ServerKeySet k, Serialize a)

=> AuthCookieSettings

Options, see AuthCookieSettings

-> k

Instance of ServerKeySet to use

-> Tagged SerializedEncryptedCookie ByteString

The ByteString to decrypt

-> m (ExtendedPayloadWrapper a)

The decrypted Cookie

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

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

• TooShortProperKey
• CannotMakeIV
• BadProperKey
• IncorrectMAC
• CookieExpired
• SessionDeserializationFailed

addSession :: AddHeader (e :: Symbol) EncryptedSession r s => AddSession r s

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

removeSession :: AddHeader (e :: Symbol) EncryptedSession r s => RemoveSession r s

Remove a session by invalidating the cookie.

addSessionToErr :: AddSession ServantErr ServantErr

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

removeSessionFromErr :: RemoveSession ServantErr 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 (ExtendedPayloadWrapper 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.

getHeaderSession :: (MonadIO m, MonadThrow m, Serialize a, ServerKeySet k) => AuthCookieSettings -> k -> Text -> m (Maybe (ExtendedPayloadWrapper a))

Get session from `Header "cookie" ByteString` in a route. Useful for checking authentication without denying access to route.

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

defaultAuthHandler :: Serialize a => AuthCookieHandler a

Cookie authentication handler.

data Cookie

Representation of a cookie.

Constructors

Cookie

Fields

• cookieIV :: Tagged IVBytes ByteString
• cookiePayload :: Tagged PayloadBytes ByteString
• cookiePadding :: Tagged PaddingBytes ByteString
• cookieMAC :: Tagged MACBytes ByteString

Instances

Serialize Cookie

Methods

put :: Putter Cookie

get :: Get Cookie

data SerializedEncryptedCookie

Tag for base64 serialized and encrypted cookie.

data EncryptedCookie

Tag for encrypted cookie.

data IVBytes

Tag for IV bytes.

data PayloadBytes

Tag for encrypted or raw payload bytes.

data PaddingBytes

Tag for pading bytes.

data MACBytes

Tag for MAC of a cookie.

base64Encode :: Tagged EncryptedCookie ByteString -> Tagged SerializedEncryptedCookie ByteString

Wrapper for encode.

base64Decode :: MonadThrow m => Tagged SerializedEncryptedCookie ByteString -> m (Tagged EncryptedCookie ByteString)

Wrapper for decode.

cerealEncode :: Serialize a => a -> Tagged b ByteString

Wrapper for encode.

cerealDecode :: (Serialize a, MonadThrow m) => Tagged b ByteString -> m a

Wrapper for decode.

renderSession :: AddSession () 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.

unProxy :: Proxy a -> a

Return bottom of type provided as Proxy tag.

mkCookieKey :: (MonadThrow m, HashAlgorithm h, BlockCipher c) => Proxy c -> Proxy h -> Tagged ServerKeyBytes ByteString -> Tagged IVBytes ByteString -> m (Tagged CookieKeyBytes ByteString)

Derives key for a cookie based on server key and IV.

mkPadding :: (MonadIO m, BlockCipher c) => RandomSource -> Proxy c -> Tagged PayloadBytes ByteString -> m (Tagged PaddingBytes ByteString)

Generates padding of random bytes to align payload's length.

mkMAC :: HashAlgorithm h => Proxy h -> Tagged ServerKeyBytes ByteString -> Cookie -> Tagged MACBytes ByteString

Generates cookie's signature.

applyCipherAlgorithm :: forall c m. (BlockCipher c, MonadThrow m) => CipherAlgorithm c -> Tagged IVBytes ByteString -> Tagged CookieKeyBytes ByteString -> Tagged PayloadBytes ByteString -> m (Tagged PayloadBytes ByteString)

Applies given encryption or decryption algorithm to given data.