Safe Haskell	None
Language	Haskell2010

Crypto.JOSE.Header

Contents

Defining header data types
Defining header parsers
Parsing headers
Encoding headers
Header fields shared by JWS and JWE

Description

Types and functions for working with JOSE header parameters.

Synopsis

data HeaderParam p a = HeaderParam p a
class Eq a => ProtectionIndicator a where
- getProtected :: a
- getUnprotected :: Maybe a
data Protection
- = Protected
- | Unprotected
protection :: Lens' (HeaderParam p a) p
isProtected :: ProtectionIndicator p => Getter (HeaderParam p a) Bool
param :: Lens' (HeaderParam p a) a
class HasParams (a :: Type -> Type) where
- params :: ProtectionIndicator p => a p -> [(Bool, Pair)]
- extensions :: Proxy a -> [Text]
- parseParamsFor :: (HasParams b, ProtectionIndicator p) => Proxy b -> Maybe Object -> Maybe Object -> Parser (a p)
headerRequired :: (FromJSON a, ProtectionIndicator p) => Text -> Maybe Object -> Maybe Object -> Parser (HeaderParam p a)
headerRequiredProtected :: FromJSON a => Text -> Maybe Object -> Maybe Object -> Parser a
headerOptional :: (FromJSON a, ProtectionIndicator p) => Text -> Maybe Object -> Maybe Object -> Parser (Maybe (HeaderParam p a))
headerOptionalProtected :: FromJSON a => Text -> Maybe Object -> Maybe Object -> Parser (Maybe a)
parseParams :: forall a p. (HasParams a, ProtectionIndicator p) => Maybe Object -> Maybe Object -> Parser (a p)
parseCrit :: (Foldable t0, Foldable t1, Traversable t2, Traversable t3, MonadFail m) => t0 Text -> t1 Text -> Object -> t2 (t3 Text) -> m (t2 (t3 Text))
protectedParamsEncoded :: (HasParams a, ProtectionIndicator p) => a p -> ByteString
unprotectedParams :: (HasParams a, ProtectionIndicator p) => a p -> Maybe Value
class HasAlg a where
- alg :: Lens' (a p) (HeaderParam p Alg)
class HasJku a where
- jku :: Lens' (a p) (Maybe (HeaderParam p URI))
class HasJwk a where
- jwk :: Lens' (a p) (Maybe (HeaderParam p JWK))
class HasKid a where
- kid :: Lens' (a p) (Maybe (HeaderParam p Text))
class HasX5u a where
- x5u :: Lens' (a p) (Maybe (HeaderParam p URI))
class HasX5c a where
- x5c :: Lens' (a p) (Maybe (HeaderParam p (NonEmpty SignedCertificate)))
class HasX5t a where
- x5t :: Lens' (a p) (Maybe (HeaderParam p Base64SHA1))
class HasX5tS256 a where
- x5tS256 :: Lens' (a p) (Maybe (HeaderParam p Base64SHA256))
class HasTyp a where
- typ :: Lens' (a p) (Maybe (HeaderParam p Text))
class HasCty a where
- cty :: Lens' (a p) (Maybe (HeaderParam p Text))
class HasCrit a where
- crit :: Lens' (a p) (Maybe (NonEmpty Text))

Defining header data types

data HeaderParam p a Source #

A header value, along with a protection indicator.

Constructors

HeaderParam p a

Instances

Instances details

Functor (HeaderParam p) Source #
Instance details Defined in Crypto.JOSE.Header Methods fmap :: (a -> b) -> HeaderParam p a -> HeaderParam p b # (<$) :: a -> HeaderParam p b -> HeaderParam p a #
(Eq p, Eq a) => Eq (HeaderParam p a) Source #
Instance details Defined in Crypto.JOSE.Header Methods (==) :: HeaderParam p a -> HeaderParam p a -> Bool # (/=) :: HeaderParam p a -> HeaderParam p a -> Bool #
(Show p, Show a) => Show (HeaderParam p a) Source #
Instance details Defined in Crypto.JOSE.Header Methods showsPrec :: Int -> HeaderParam p a -> ShowS # show :: HeaderParam p a -> String # showList :: [HeaderParam p a] -> ShowS #

class Eq a => ProtectionIndicator a where Source #

Methods

getProtected :: a Source #

Get a value for indicating protection.

getUnprotected :: Maybe a Source #

Get a Just a value for indicating no protection, or Nothing if the type does not support unprotected headers.

Instances

Instances details

ProtectionIndicator () Source #
Instance details Defined in Crypto.JOSE.Header Methods getProtected :: () Source # getUnprotected :: Maybe () Source #
ProtectionIndicator Protection Source #
Instance details Defined in Crypto.JOSE.Header Methods getProtected :: Protection Source # getUnprotected :: Maybe Protection Source #

data Protection Source #

Whether a header is protected or unprotected

Constructors

Protected
Unprotected

Instances

Instances details

Eq Protection Source #
Instance details Defined in Crypto.JOSE.Header Methods (==) :: Protection -> Protection -> Bool # (/=) :: Protection -> Protection -> Bool #
Show Protection Source #
Instance details Defined in Crypto.JOSE.Header Methods showsPrec :: Int -> Protection -> ShowS # show :: Protection -> String # showList :: [Protection] -> ShowS #
ProtectionIndicator Protection Source #
Instance details Defined in Crypto.JOSE.Header Methods getProtected :: Protection Source # getUnprotected :: Maybe Protection Source #

protection :: Lens' (HeaderParam p a) p Source #

Lens for the Protection of a HeaderParam

isProtected :: ProtectionIndicator p => Getter (HeaderParam p a) Bool Source #

Getter for whether a parameter is protected

param :: Lens' (HeaderParam p a) a Source #

Lens for a HeaderParam value

Defining header parsers

The parseParamsFor function defines the parser for a header type.

parseParamsFor
  :: (HasParams a, HasParams b)
  => Proxy b -> Maybe Object -> Maybe Object -> Parser a

It is defined over two objects: the protected header and the unprotected header. The following functions are provided for parsing header parameters:

headerOptional: An optional parameter that may be protected or unprotected.
headerRequired: A required parameter that may be protected or unprotected.
headerOptionalProtected: An optional parameter that, if present, MUST be carried in the protected header.
headerRequiredProtected: A required parameter that, if present, MUST be carried in the protected header.

Duplicate headers are forbidden. The above functions all perform duplicate header detection. If you do not use them, be sure to perform this detection yourself!

An example parser:

instance HasParams ACMEHeader where
  parseParamsFor proxy hp hu = ACMEHeader
    <$> parseParamsFor proxy hp hu
    <*> headerRequiredProtected "nonce" hp hu

class HasParams (a :: Type -> Type) where Source #

A thing with parameters.

Minimal complete definition

params, parseParamsFor

Methods

params :: ProtectionIndicator p => a p -> [(Bool, Pair)] Source #

Return a list of parameters, each paired with whether it is protected or not.

extensions :: Proxy a -> [Text] Source #

List of "known extensions", i.e. keys that may appear in the "crit" header parameter.

parseParamsFor :: (HasParams b, ProtectionIndicator p) => Proxy b -> Maybe Object -> Maybe Object -> Parser (a p) Source #

Instances

Instances details

HasParams JWSHeader Source #
Instance details Defined in Crypto.JOSE.JWS Methods params :: ProtectionIndicator p => JWSHeader p -> [(Bool, Pair)] Source # extensions :: Proxy JWSHeader -> [Text] Source # parseParamsFor :: forall (b :: Type -> Type) p. (HasParams b, ProtectionIndicator p) => Proxy b -> Maybe Object -> Maybe Object -> Parser (JWSHeader p) Source #
HasParams JWEHeader Source #
Instance details Defined in Crypto.JOSE.JWE Methods params :: ProtectionIndicator p => JWEHeader p -> [(Bool, Pair)] Source # extensions :: Proxy JWEHeader -> [Text] Source # parseParamsFor :: forall (b :: Type -> Type) p. (HasParams b, ProtectionIndicator p) => Proxy b -> Maybe Object -> Maybe Object -> Parser (JWEHeader p) Source #

headerRequired :: (FromJSON a, ProtectionIndicator p) => Text -> Maybe Object -> Maybe Object -> Parser (HeaderParam p a) Source #

Parse a required parameter that may be carried in either the protected or the unprotected header.

headerRequiredProtected :: FromJSON a => Text -> Maybe Object -> Maybe Object -> Parser a Source #

Parse a required parameter that MUST be carried in the protected header.

headerOptional :: (FromJSON a, ProtectionIndicator p) => Text -> Maybe Object -> Maybe Object -> Parser (Maybe (HeaderParam p a)) Source #

Parse an optional parameter that may be carried in either the protected or the unprotected header.

headerOptionalProtected :: FromJSON a => Text -> Maybe Object -> Maybe Object -> Parser (Maybe a) Source #

Parse an optional parameter that, if present, MUST be carried in the protected header.

Parsing headers

parseParams Source #

Arguments

:: forall a p. (HasParams a, ProtectionIndicator p)
=> Maybe Object	protected header
-> Maybe Object	unprotected header
-> Parser (a p)

Parse a pair of objects (protected and unprotected header)

This internally invokes parseParamsFor applied to a proxy for the target type. (This allows the parsing of the "crit" parameter to access "known extensions" understood by the target type.)

parseCrit Source #

Arguments

:: (Foldable t0, Foldable t1, Traversable t2, Traversable t3, MonadFail m)
=> t0 Text	reserved header parameters
-> t1 Text	recognised extensions
-> Object	full header (union of protected and unprotected headers)
-> t2 (t3 Text)	crit header
-> m (t2 (t3 Text))

Parse a "crit" header param

Fails if:

any reserved header appears in "crit" header
any value in "crit" is not a recognised extension
any value in "crit" does not have a corresponding key in the object

Encoding headers

protectedParamsEncoded :: (HasParams a, ProtectionIndicator p) => a p -> ByteString Source #

Return the base64url-encoded protected parameters

unprotectedParams Source #

Arguments

:: (HasParams a, ProtectionIndicator p)
=> a p
-> Maybe Value	Object

Return unprotected params as a JSON Value (always an object)

Header fields shared by JWS and JWE

class HasAlg a where Source #

Methods

alg :: Lens' (a p) (HeaderParam p Alg) Source #

Instances

Instances details

HasJWSHeader a => HasAlg a Source #
Instance details Defined in Crypto.JOSE.JWS Methods alg :: Lens' (a p) (HeaderParam p Alg) Source #

class HasJku a where Source #

Methods

jku :: Lens' (a p) (Maybe (HeaderParam p URI)) Source #

Instances

Instances details

HasJWSHeader a => HasJku a Source #
Instance details Defined in Crypto.JOSE.JWS Methods jku :: Lens' (a p) (Maybe (HeaderParam p URI)) Source #

class HasJwk a where Source #

Methods

jwk :: Lens' (a p) (Maybe (HeaderParam p JWK)) Source #

Instances

Instances details

HasJWSHeader a => HasJwk a Source #
Instance details Defined in Crypto.JOSE.JWS Methods jwk :: Lens' (a p) (Maybe (HeaderParam p JWK)) Source #

class HasKid a where Source #

Methods

kid :: Lens' (a p) (Maybe (HeaderParam p Text)) Source #

Instances

Instances details

HasJWSHeader a => HasKid a Source #
Instance details Defined in Crypto.JOSE.JWS Methods kid :: Lens' (a p) (Maybe (HeaderParam p Text)) Source #

class HasX5u a where Source #

Methods

x5u :: Lens' (a p) (Maybe (HeaderParam p URI)) Source #

Instances

Instances details

HasJWSHeader a => HasX5u a Source #
Instance details Defined in Crypto.JOSE.JWS Methods x5u :: Lens' (a p) (Maybe (HeaderParam p URI)) Source #

class HasX5c a where Source #

Methods

x5c :: Lens' (a p) (Maybe (HeaderParam p (NonEmpty SignedCertificate))) Source #

Instances

Instances details

HasJWSHeader a => HasX5c a Source #
Instance details Defined in Crypto.JOSE.JWS Methods x5c :: Lens' (a p) (Maybe (HeaderParam p (NonEmpty SignedCertificate))) Source #

class HasX5t a where Source #

Methods

x5t :: Lens' (a p) (Maybe (HeaderParam p Base64SHA1)) Source #

Instances

Instances details

HasJWSHeader a => HasX5t a Source #
Instance details Defined in Crypto.JOSE.JWS Methods x5t :: Lens' (a p) (Maybe (HeaderParam p Base64SHA1)) Source #

class HasX5tS256 a where Source #

Methods

x5tS256 :: Lens' (a p) (Maybe (HeaderParam p Base64SHA256)) Source #

Instances

Instances details

HasJWSHeader a => HasX5tS256 a Source #
Instance details Defined in Crypto.JOSE.JWS Methods x5tS256 :: Lens' (a p) (Maybe (HeaderParam p Base64SHA256)) Source #