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 Cookie

Cookie representation.

Constructors

Cookie

Fields

• cookieIV :: ByteString

  The initialization vector

• cookieExpirationTime :: UTCTime

  The cookie's expiration time

• cookiePayload :: ByteString

  The payload

Instances

Eq Cookie

Methods

(==) :: Cookie -> Cookie -> Bool

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

Show Cookie

Methods

showsPrec :: Int -> Cookie -> ShowS

show :: Cookie -> String

showList :: [Cookie] -> ShowS

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

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):

• TooShortProperKey
• CannotMakeIV
• BadProperKey

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):

• TooShortProperKey
• CannotMakeIV
• BadProperKey
• IncorrectMAC
• CannotParseExpirationTime
• CookieExpired

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.