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

data ServerKey

A wrapper of self-resetting ByteString of random symbols suitable for concurrent usage.

mkServerKey

Arguments

:: MonadIO m

=> Int

Size of the server key

-> Maybe NominalDiffTime

Expiration time (Nothing is eternity)

-> m ServerKey

New ServerKey

Constructor for ServerKey value.

mkServerKeyFromBytes

Arguments

:: MonadIO m

=> ByteString

Predefined key

-> m ServerKey

New ServerKey

Constructor for ServerKey value using predefined key.

getServerKey

Arguments

:: MonadIO m

=> ServerKey

The ServerKey

-> m ByteString

Its random symbol

Extract value from ServerKey.

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)

=> AuthCookieSettings

Options, see AuthCookieSettings

-> ServerKey

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

=> AuthCookieSettings

Options, see AuthCookieSettings

-> ServerKey

ServerKey to use

-> Tagged EncryptedCookie ByteString

The ByteString to decrypt

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

=> AuthCookieSettings

Options, see AuthCookieSettings

-> RandomSource

Random source to use

-> ServerKey

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

=> AuthCookieSettings

Options, see AuthCookieSettings

-> ServerKey

ServerKey to use

-> Tagged SerializedEncryptedCookie ByteString

Cookie in binary form

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

=> AuthCookieSettings

Options, see AuthCookieSettings

-> RandomSource

Random source to use

-> ServerKey

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

=> AuthCookieSettings

Options, see AuthCookieSettings

-> RandomSource

Random source to use

-> ServerKey

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

=> AuthCookieSettings

Options, see AuthCookieSettings

-> ServerKey

ServerKey to use

-> Request

The request

-> m (Maybe 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.

renderSession :: (MonadIO m, MonadThrow m, Serialize a) => AuthCookieSettings -> RandomSource -> ServerKey -> 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.

defaultAuthHandler

Arguments

:: Serialize a

=> AuthCookieSettings

Options, see AuthCookieSettings

-> ServerKey

ServerKey to use

-> AuthHandler Request a

Cookie authentication handler.