Copyright | (c) 2016 Al Zohali |
---|---|
License | BSD3 |
Maintainer | Al Zohali <zohl@fmap.me> |
Stability | experimental |
Safe Haskell | None |
Language | Haskell2010 |
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.
- type CipherAlgorithm c = c -> IV c -> ByteString -> ByteString
- type family AuthCookieData
- data Cookie = Cookie {}
- data AuthCookieException
- data RandomSource
- mkRandomSource :: (MonadIO m, DRG d) => IO d -> Int -> m RandomSource
- getRandomBytes :: MonadIO m => RandomSource -> Int -> m ByteString
- data ServerKey
- mkServerKey :: MonadIO m => Int -> Maybe NominalDiffTime -> m ServerKey
- mkServerKeyFromBytes :: MonadIO m => ByteString -> m ServerKey
- getServerKey :: MonadIO m => ServerKey -> m ByteString
- data AuthCookieSettings where
- AuthCookieSettings :: (HashAlgorithm h, BlockCipher c) => {..} -> AuthCookieSettings
- newtype EncryptedSession = EncryptedSession ByteString
- emptyEncryptedSession :: EncryptedSession
- encryptCookie :: (MonadIO m, MonadThrow m) => AuthCookieSettings -> ServerKey -> Cookie -> m (Tagged EncryptedCookie ByteString)
- decryptCookie :: (MonadIO m, MonadThrow m) => AuthCookieSettings -> ServerKey -> Tagged EncryptedCookie ByteString -> m Cookie
- encryptSession :: (MonadIO m, MonadThrow m, Serialize a) => AuthCookieSettings -> RandomSource -> ServerKey -> a -> m (Tagged SerializedEncryptedCookie ByteString)
- decryptSession :: (MonadIO m, MonadThrow m, Serialize a) => AuthCookieSettings -> ServerKey -> Tagged SerializedEncryptedCookie ByteString -> m a
- addSession :: (MonadIO m, MonadThrow m, Serialize a, AddHeader (e :: Symbol) EncryptedSession s r) => AuthCookieSettings -> RandomSource -> ServerKey -> a -> s -> m r
- addSessionToErr :: (MonadIO m, MonadThrow m, Serialize a) => AuthCookieSettings -> RandomSource -> ServerKey -> a -> ServantErr -> m ServantErr
- getSession :: (MonadIO m, MonadThrow m, Serialize a) => AuthCookieSettings -> ServerKey -> Request -> m (Maybe a)
- renderSession :: (MonadIO m, MonadThrow m, Serialize a) => AuthCookieSettings -> RandomSource -> ServerKey -> a -> m ByteString
- defaultAuthHandler :: Serialize a => AuthCookieSettings -> ServerKey -> AuthHandler Request a
Documentation
type CipherAlgorithm c = c -> IV c -> ByteString -> ByteString Source #
A type for encryption and decryption functions operating on ByteString
s.
type family AuthCookieData Source #
A type family that maps user-defined data to AuthServerData
.
Cookie representation.
Cookie | |
|
data AuthCookieException Source #
The exception is thrown when something goes wrong with this package.
CannotMakeIV ByteString | Could not make |
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 |
SessionDeserializationFailed String |
data RandomSource Source #
A wrapper of self-resetting DRG
suitable for concurrent usage.
:: (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 |
Constructor for RandomSource
value.
:: MonadIO m | |
=> RandomSource | The source of random numbers |
-> Int | How many random bytes to generate |
-> m ByteString | The generated bytes in form of a |
Extract pseudo-random bytes from RandomSource
.
A wrapper of self-resetting ByteString
of random symbols suitable for
concurrent usage.
:: MonadIO m | |
=> Int | Size of the server key |
-> Maybe NominalDiffTime | Expiration time ( |
-> m ServerKey | New |
Constructor for ServerKey
value.
:: MonadIO m | |
=> ByteString | Predefined key |
-> m ServerKey | New |
Constructor for ServerKey
value using predefined key.
:: MonadIO m | |
=> ServerKey | The |
-> m ByteString | Its random symbol |
Extract value from ServerKey
.
data AuthCookieSettings where Source #
Options that determine authentication mechanisms. Use def
to get
default value of this type.
AuthCookieSettings :: (HashAlgorithm h, BlockCipher c) => {..} -> AuthCookieSettings | |
|
newtype EncryptedSession Source #
A newtype wrapper over ByteString
emptyEncryptedSession :: EncryptedSession Source #
An empty EncryptedSession
:: (MonadIO m, MonadThrow m) | |
=> AuthCookieSettings | Options, see |
-> ServerKey |
|
-> Cookie | The |
-> m (Tagged EncryptedCookie ByteString) | Encrypted |
Encrypt given Cookie
with server key.
The function can throw the following exceptions (of type
AuthCookieException
):
:: (MonadIO m, MonadThrow m) | |
=> AuthCookieSettings | Options, see |
-> ServerKey |
|
-> Tagged EncryptedCookie ByteString | The |
-> m Cookie | The decrypted |
Decrypt a Cookie
from ByteString
.
The function can throw the following exceptions (of type
AuthCookieException
):
:: (MonadIO m, MonadThrow m, Serialize a) | |
=> AuthCookieSettings | Options, see |
-> RandomSource | Random source to use |
-> ServerKey |
|
-> 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
.
:: (MonadIO m, MonadThrow m, Serialize a) | |
=> AuthCookieSettings | Options, see |
-> ServerKey |
|
-> 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
.
:: (MonadIO m, MonadThrow m, Serialize a, AddHeader (e :: Symbol) EncryptedSession s r) | |
=> AuthCookieSettings | Options, see |
-> RandomSource | Random source to use |
-> ServerKey |
|
-> 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
.
:: (MonadIO m, MonadThrow m, Serialize a) | |
=> AuthCookieSettings | Options, see |
-> RandomSource | Random source to use |
-> ServerKey |
|
-> 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.
:: (MonadIO m, MonadThrow m, Serialize a) | |
=> AuthCookieSettings | Options, see |
-> ServerKey |
|
-> 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 Source #
Render session cookie to ByteString
.
:: Serialize a | |
=> AuthCookieSettings | Options, see |
-> ServerKey |
|
-> AuthHandler Request a |
Cookie authentication handler.