Network.Hawk.Internal.Client

Note that this is essentially the "kitchen sink" export module, including many functions intended only to be used internally by this package. No API stability is guaranteed for this module. If you see functions here which you believe should be promoted to a stable API, please contact the author.

Documentation

header

Arguments

:: Text

The request URL

-> Method

The request method

-> Credentials

Credentials used to generate the header

-> Maybe PayloadInfo

Optional request payload

-> NominalDiffTime

Time offset to sync with server time

-> Maybe ExtData

Application-specific ext data

-> IO Header

Generates the Hawk authentication header for a request.

headerOz

Arguments

:: Text

The request URL

-> Method

The request method

-> Credentials

Credentials used to generate the header

-> Maybe PayloadInfo

Optional request payload

-> NominalDiffTime

Time offset to sync with server time

-> Maybe ExtData

Application-specific ext data

-> Text

Oz application identifier

-> Maybe Text

Oz delegated application

-> IO Header

Generates the Hawk authentication header for an Oz request. Oz requires another attribute -- the application id. It also has an optional delegated-by attribute, which is the application id of the application the credentials were directly issued to.

headerBase :: Text -> Method -> Credentials -> Maybe PayloadInfo -> NominalDiffTime -> Maybe ExtData -> Maybe Text -> Maybe Text -> IO Header

headerBase' :: Text -> Method -> Credentials -> Maybe PayloadInfo -> NominalDiffTime -> Maybe ExtData -> Maybe Text -> Maybe Text -> POSIXTime -> ByteString -> Header

message

Arguments

:: Credentials

Credentials for encryption.

-> ByteString

Destination host.

-> Maybe Int

Destination port.

-> ByteString

The message.

-> NominalDiffTime

Time offset to sync with server time.

-> IO MessageAuth

Generates an authorization object for a Hawk signed message.

message'

Arguments

:: Credentials

Credentials for encryption.

-> ByteString

Destination host.

-> Maybe Int

Destination port.

-> ByteString

The message.

-> NominalDiffTime

Time offset to sync with server time.

-> POSIXTime

Message timestamp.

-> ByteString

Random nonce string.

-> MessageAuth

Generates an authorization object for a Hawk signed message. This variation allows the user to provide the message timestamp and nonce string.

artsMsg :: Credentials -> HeaderArtifacts -> MessageAuth

Signs a message stored in the given artifacts bundle.

header' :: HawkType -> Text -> Method -> Credentials -> Maybe PayloadInfo -> NominalDiffTime -> Maybe ExtData -> Maybe Text -> Maybe Text -> POSIXTime -> ByteString -> HeaderArtifacts

headerArtifacts :: POSIXTime -> ByteString -> Method -> ByteString -> Maybe ByteString -> Maybe ByteString -> Maybe Text -> Maybe Text -> ClientId -> ByteString -> HeaderArtifacts

Constructs artifacts bundle from header params.

clientHawkAuth :: HeaderArtifacts -> ByteString

clientMac :: Credentials -> HawkType -> HeaderArtifacts -> ByteString

hawkHeaderItems :: [(ByteString, Maybe ByteString)] -> [(ByteString, ByteString)]

splitUrl :: ByteString -> Maybe SplitURL

genNonce :: IO ByteString

data ServerAuthorizationCheck

Whether the client wants to check the received Server-Authorization header depends on the application.

Constructors

ServerAuthorizationNotRequired

ServerAuthorizationRequired

Instances

Show ServerAuthorizationCheck

Methods

showsPrec :: Int -> ServerAuthorizationCheck -> ShowS

show :: ServerAuthorizationCheck -> String

showList :: [ServerAuthorizationCheck] -> ShowS

authenticate

Arguments

:: Response body

Response from server.

-> Credentials

Credentials used for signing the request.

-> HeaderArtifacts

The result of sign.

-> Maybe ByteString

Optional payload body from response.

-> ServerAuthorizationCheck

Whether a valid Server-Authorization header is required.

-> IO (Either String (Maybe ServerAuthorizationHeader))

Error message if authentication failed.

Validates the server response from a signed request. If the payload body is provided, its hash will be checked.

authenticate' :: Response body -> Credentials -> HeaderArtifacts -> Maybe ByteString -> ServerAuthorizationCheck -> POSIXTime -> Either String (Maybe ServerAuthorizationHeader)

responseHeader :: HeaderName -> Response body -> Maybe ByteString

checkWwwAuthenticateHeader :: Credentials -> ByteString -> Either String (Maybe POSIXTime)

The protocol relies on a clock sync between the client and server. To accomplish this, the server informs the client of its current time when an invalid timestamp is received.

If an attacker is able to manipulate this information and cause the client to use an incorrect time, it would be able to cause the client to generate authenticated requests using time in the future. Such requests will fail when sent by the client, and will not likely leave a trace on the server (given the common implementation of nonce, if at all enforced). The attacker will then be able to replay the request at the correct time without detection.

The client must only use the time information provided by the server if:

• it was delivered over a TLS connection and the server identity has been verified, or
• the tsm MAC digest calculated using the same client credentials over the timestamp has been verified.

checkServerAuthorizationHeader :: Credentials -> HeaderArtifacts -> ServerAuthorizationCheck -> POSIXTime -> Maybe ByteString -> Either String (Maybe ServerAuthorizationHeader)

responseArtifacts :: ServerAuthorizationHeader -> HeaderArtifacts -> HeaderArtifacts

Updates the artifacts which were used for client authentication with values from there server's response.

getBewit

Arguments

:: Credentials

Credentials used to generate the bewit.

-> NominalDiffTime

Time-to-live (TTL) value.

-> Maybe ExtData

Optional application-specific data.

-> NominalDiffTime

Time offset to sync with server time.

-> ByteString

URI.

-> IO (Maybe ByteString)

Base-64 encoded bewit value. fixme: javascript version supports deconstructed parsed uri objects fixme: not much point having two time interval arguments? Maybe just have a single expiry time argument.

Generate a bewit value for a given URI. If the URI can't be parsed, Nothing will be returned.

See Network.Hawk.URI for more information about bewits.

bewitArtifacts :: ByteString -> POSIXTime -> Maybe ExtData -> Maybe HeaderArtifacts

encodeBewit :: Credentials -> HeaderArtifacts -> ByteString

bewitString :: ClientId -> POSIXTime -> ByteString -> Maybe ExtData -> ByteString

Constructs a bewit: idexpmacext

sign

Arguments

:: MonadIO m

=> Credentials

Credentials for signing

-> Maybe ExtData

Optional application-specific data.

-> Maybe PayloadInfo

Optional payload to hash

-> NominalDiffTime

Time offset to sync with server time

-> Request

The request to sign

-> m (HeaderArtifacts, Request)

Modifies a Request to include the Authorization header necessary for Hawk.

addAuth :: Header -> Request -> Request

data HawkException

Client exceptions specific to Hawk.

Constructors

HawkServerAuthorizationException String

The returned Server-Authorization header did not validate.

Instances

Show HawkException

Methods

showsPrec :: Int -> HawkException -> ShowS

show :: HawkException -> String

showList :: [HawkException] -> ShowS

Exception HawkException

Methods

toException :: HawkException -> SomeException

fromException :: SomeException -> Maybe HawkException

displayException :: HawkException -> String

withHawk

Arguments

:: (MonadIO m, MonadCatch m)

=> Credentials

Credentials for signing the request.

-> Maybe ExtData

Optional application-specific data.

-> Maybe PayloadInfo

Optional payload to sign.

-> ServerAuthorizationCheck

Whether to verify the server's response.

-> (Request -> m (Response body))

The action to run with the request.

-> Request

The request to sign.

-> m (Response body)

The result of the action.

Signs and executes a request, then checks the server's response. Handles retrying of requests if the server and client clocks are out of sync.

A HawkException will be thrown if the server's response fails to authenticate.

withHawkPayload :: (MonadIO m, MonadCatch m) => Credentials -> Maybe ExtData -> PayloadInfo -> ServerAuthorizationCheck -> (Request -> m (Response body)) -> Request -> m (Response body)

withHawkBase :: (MonadIO m, MonadThrow m, MonadCatch m) => Credentials -> Maybe ExtData -> Maybe PayloadInfo -> ServerAuthorizationCheck -> (Request -> m (Response body)) -> Request -> m (Response body)

Makes a Hawk signed request. If the server responds saying "Stale timestamp", then retry using an adjusted timestamp.

makeExpiryHandler :: MonadCatch m => Credentials -> Request -> m a -> m (Either NominalDiffTime a)

doSignedRequest :: (MonadIO m, MonadThrow m) => NominalDiffTime -> Credentials -> Maybe ExtData -> Maybe PayloadInfo -> ServerAuthorizationCheck -> (Request -> m (Response body)) -> Request -> m (Response body)

Signs a request, runs it, then authenticates the response.

authResponse :: MonadIO m => Credentials -> HeaderArtifacts -> ServerAuthorizationCheck -> Response body -> m (Either String (Maybe ServerAuthorizationHeader))

Authenticates the server's response if required.

wasStale :: Request -> Response () -> Credentials -> Maybe NominalDiffTime

hawkTs :: Credentials -> ResponseHeaders -> Maybe POSIXTime

Gets the WWW-Authenticate header value and returns the server timestamp, if the response contains an authenticated timestamp.