-- |
-- Module : Network.OAuth
-- Copyright : (c) Joseph Abrahamson 2013
-- License : MIT
--
-- Maintainer : me@jspha.com
-- Stability : experimental
-- Portability : non-portable
--
-- OAuth tools for using @http-client@ for authenticated requests.
--
-- The functions here form the simplest basis for sending OAuthenticated
-- 'C.Request's. In order to generate credentials according to the OAuth
-- "three-legged workflow" use actions in the "Network.OAuth.ThreeLegged"
-- module.
--
module Network.OAuth (
-- * Authenticating a request
--
-- | The 'oauthSimple' function can be used to sign a 'C.Request' as it
-- stands. It should be performed just before the 'C.Request' is used as
-- it uses the current timestamp and thus may only be valid for a limited
-- amount of time.
--
-- 'oauthSimple' creates a /new/ random entropy pool every time it is
-- called, thus it can be both slow and cryptographically dangerous to
-- use it repeatedly as it can drain system entropy. Instead, the plain 'S.oauth'
-- function should be used which allows for threading of the random
-- source.
--
oauthSimple, S.oauth,
-- * Lower-level and pure functionality
--
-- | When necessary to control or observe the signature more
-- carefully, the lower level API can be used. This requires generating
-- a fresh set of 'O.Oa' parameters from a relevant or deterministic
-- 'O.OaPin' and then using 'S.sign' to sign the 'C.Request'.
S.sign,
-- ** Generating OAuth parameters
O.emptyOa, O.freshOa, O.emptyPin, O.freshPin,
-- * OAuth Credentials
O.Token (..), O.Cred, O.Client, O.Temporary, O.Permanent,
-- ** Creating Credentials
O.clientCred, O.temporaryCred, O.permanentCred,
O.fromUrlEncoded,
-- * OAuth Configuration
O.Server (..), O.defaultServer,
O.ParameterMethod (..), O.SignatureMethod (..), O.Version (..),
) where
import qualified Crypto.Random as R
import qualified Network.HTTP.Client as C
import qualified Network.OAuth.Signing as S
import qualified Network.OAuth.Types.Credentials as O
import qualified Network.OAuth.Types.Params as O
-- | Sign a request with a fresh set of parameters. Creates a fresh
-- 'R.SystemRNG' using new entropy for each signing and thus is potentially
-- /dangerous/ if used too frequently. In almost all cases, 'S.oauth'
-- should be used instead.
oauthSimple :: O.Cred ty -> O.Server -> C.Request -> IO C.Request
oauthSimple cr srv req = do
entropy <- R.createEntropyPool
(req', _) <- S.oauth cr srv req (R.cprgCreate entropy :: R.SystemRNG)
return req'