Network.Hawk.Server

These are functions for checking authenticated requests and sending authenticated responses.

For an easy way to add Hawk authentication to a Network.Wai Application, use the Network.Hawk.Middleware module.

Authenticating Network.Wai requests

authenticateRequest :: MonadIO m => AuthReqOpts -> CredentialsFunc m t -> Request -> Maybe ByteString -> m (AuthResult t)

Checks the Authorization header of a Request and (optionally) a payload. The header will be parsed and verified with the credentials supplied.

If the request payload is provided, it will be verified. If a payload is not supplied, it can be verified later with authenticatePayload.

authenticatePayload :: AuthSuccess t -> PayloadInfo -> Either String ()

Verifies the payload hash as a separate step after other things have been check. This is useful when the request body is streamed for example.

authenticateBewitRequest :: MonadIO m => AuthReqOpts -> CredentialsFunc m t -> Request -> m (AuthResult t)

Checks the Authorization header of a Request according to the "bewit" scheme. See Network.Hawk.URI for a description of that scheme.

data AuthReqOpts

Bundle of parameters for authenticateRequest. Provides information about what the public URL of the server would be. If the application is served from a HTTP reverse proxy, then the Host header might have a different name, or the hostname:port might need to be overridden.

Constructors

AuthReqOpts

Fields

• saHostHeaderName :: Maybe (CI ByteString)

  Alternate name for Host header

• saHost :: Maybe ByteString

  Overrides the URL host

• saPort :: Maybe ByteString

  Overrides the URL port

• saBewitParam :: ByteString

  Query parameter for bewit authentication. Defaults to "bewit".

• saOpts :: AuthOpts

  Parameters for authenticate

Instances

Default AuthReqOpts

Methods

def :: AuthReqOpts

Generic variants

authenticate :: MonadIO m => AuthOpts -> CredentialsFunc m t -> HawkReq -> m (AuthResult t)

Checks the Authorization header of a generic request. The header will be parsed and verified with the credentials supplied.

If a payload is provided, it will be verified. If the payload is not supplied, it can be verified later with authenticatePayload.

authenticateBewit :: MonadIO m => AuthOpts -> CredentialsFunc m t -> HawkReq -> m (AuthResult t)

Checks the Authorization header of a request (HawkReq) according to the "bewit" scheme.

authenticateMessage

Arguments

:: MonadIO m

=> AuthOpts

Options for verification.

-> CredentialsFunc m t

Credentials lookup function.

-> ByteString

Destination host.

-> Maybe Int

Destination port.

-> ByteString

The message.

-> MessageAuth

Signed message object.

-> m (AuthResult t)

Verifies message signature with the given credentials and authorization attributes.

data HawkReq

A package of values containing the attributes of a HTTP request which are relevant to Hawk authentication.

Constructors

HawkReq

Fields

• hrqMethod :: Method
• hrqUrl :: ByteString
• hrqHost :: ByteString
• hrqPort :: Maybe Int
• hrqAuthorization :: ByteString
• hrqPayload :: Maybe PayloadInfo
• hrqBewit :: Maybe ByteString
• hrqBewitlessUrl :: ByteString

Instances

Show HawkReq

Methods

showsPrec :: Int -> HawkReq -> ShowS

show :: HawkReq -> String

showList :: [HawkReq] -> ShowS

Default HawkReq

Methods

def :: HawkReq

Options for authentication

data AuthOpts

Bundle of parameters for authenticate.

Constructors

AuthOpts

Fields

• saCheckNonce :: NonceFunc

  Nonce validation function. Defaults to a function which always returns True.

• saTimestampSkew :: NominalDiffTime

  Number of seconds of permitted clock skew for incoming timestamps. Defaults to 60 seconds. Provides a +/- skew which means actual allowed window is double the number of seconds.

• saLocaltimeOffset :: NominalDiffTime

  Offsets the local time. Defaults to 0.

Instances

Default AuthOpts

Methods

def :: AuthOpts

data Credentials

The set of data the server requires for key-based hash verification of artifacts.

Constructors

Credentials

Fields

• scKey :: Key

  Key

• scAlgorithm :: HawkAlgo

  HMAC

Instances

Eq Credentials

Methods

(==) :: Credentials -> Credentials -> Bool

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

Show Credentials

Methods

showsPrec :: Int -> Credentials -> ShowS

show :: Credentials -> String

showList :: [Credentials] -> ShowS

Generic Credentials

Associated Types

type Rep Credentials :: * -> *

Methods

from :: Credentials -> Rep Credentials x

to :: Rep Credentials x -> Credentials

type Rep Credentials

type Rep Credentials = D1 (MetaData "Credentials" "Network.Hawk.Internal.Server.Types" "hsoz-0.0.1.0-5r17DkUA43zE9P6QhuhthQ" False) (C1 (MetaCons "Credentials" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "scKey") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key)) (S1 (MetaSel (Just Symbol "scAlgorithm") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 HawkAlgo))))

type CredentialsFunc m t = ClientId -> m (Either String (Credentials, t))

A user-supplied callback to get credentials from a client identifier.

type NonceFunc = Key -> POSIXTime -> Nonce -> IO Bool

User-supplied nonce validation function. It should return True if the nonce is valid.

Checking nonces can prevent request replay attacks. If the same key and nonce have already been seen, then the request can be denied.

type Nonce = ByteString

The nonce should be a short sequence of random ASCII characters.

def :: Default a => a

The default value for this type.

Authentication result

type AuthResult t = AuthResult' (AuthSuccess t)

The end result of authentication.

type AuthResult' r = Either AuthFail r

An intermediate result of authentication.

data AuthSuccess t

Successful authentication produces a set of credentials and "artifacts". Also included in the result is the result of CredentialsFunc.

Constructors

AuthSuccess Credentials HeaderArtifacts t

Instances

Eq t => Eq (AuthSuccess t)

Methods

(==) :: AuthSuccess t -> AuthSuccess t -> Bool

(/=) :: AuthSuccess t -> AuthSuccess t -> Bool

Show t => Show (AuthSuccess t)

Methods

showsPrec :: Int -> AuthSuccess t -> ShowS

show :: AuthSuccess t -> String

showList :: [AuthSuccess t] -> ShowS

data AuthFail

Authentication can fail in multiple ways. This type includes the information necessary to generate a suitable response for the client. In the case of a stale timestamp, the client may try another authenticated request.

Constructors

AuthFailBadRequest String (Maybe HeaderArtifacts)

AuthFailUnauthorized String (Maybe Credentials) (Maybe HeaderArtifacts)

AuthFailStaleTimeStamp String POSIXTime Credentials HeaderArtifacts

Instances

Eq AuthFail

Methods

(==) :: AuthFail -> AuthFail -> Bool

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

Show AuthFail

Methods

showsPrec :: Int -> AuthFail -> ShowS

show :: AuthFail -> String

showList :: [AuthFail] -> ShowS

authValue :: AuthSuccess t -> t

The result of an AuthSuccess.

authFailMessage :: AuthFail -> String

The error message from an AuthFail.

Authenticated reponses

header :: AuthResult t -> Maybe PayloadInfo -> (Status, Header)

Generates a suitable Server-Authorization header to send back to the client. Credentials and artifacts would be provided by a previous call to authenticateRequest (or authenticate).

If a payload is supplied, its hash will be included in the header.