Crypto.JOSE.Header

Types and functions for working with JOSE header parameters.

Defining header data types

data HeaderParam p a

A header value, along with a protection indicator.

Constructors

HeaderParam p a

Instances

Functor (HeaderParam p)

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)

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)

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

Methods

getProtected :: a

Get a value for indicating protection.

getUnprotected :: Maybe a

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

Instances

ProtectionIndicator ()

Defined in Crypto.JOSE.Header

Methods

getProtected :: ()

getUnprotected :: Maybe ()

ProtectionIndicator Protection

Defined in Crypto.JOSE.Header

Methods

getProtected :: Protection

getUnprotected :: Maybe Protection

data Protection

Whether a header is protected or unprotected

Constructors

Protected

Unprotected

Instances

Eq Protection

Defined in Crypto.JOSE.Header

Methods

(==) :: Protection -> Protection -> Bool

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

Show Protection

Defined in Crypto.JOSE.Header

Methods

showsPrec :: Int -> Protection -> ShowS

show :: Protection -> String

showList :: [Protection] -> ShowS

ProtectionIndicator Protection

Defined in Crypto.JOSE.Header

Methods

getProtected :: Protection

getUnprotected :: Maybe Protection

protection :: Lens' (HeaderParam p a) p

Lens for the Protection of a HeaderParam

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

Getter for whether a parameter is protected

param :: Lens' (HeaderParam p a) a

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 :: * -> *) where

A thing with parameters.

Minimal complete definition

params, parseParamsFor

Methods

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

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

extensions :: Proxy a -> [Text]

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)

Instances

HasParams JWSHeader

Defined in Crypto.JOSE.JWS

Methods

params :: ProtectionIndicator p => JWSHeader p -> [(Bool, Pair)]

extensions :: Proxy JWSHeader -> [Text]

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

HasParams JWEHeader

Defined in Crypto.JOSE.JWE

Methods

params :: ProtectionIndicator p => JWEHeader p -> [(Bool, Pair)]

extensions :: Proxy JWEHeader -> [Text]

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

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

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

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))

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)

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

Parsing headers

parseParams

Arguments

:: (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

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

Return the base64url-encoded protected parameters

unprotectedParams

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

Methods

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

Instances

HasJWSHeader a => HasAlg a

Defined in Crypto.JOSE.JWS

Methods

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

class HasJku a where

Methods

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

Instances

HasJWSHeader a => HasJku a

Defined in Crypto.JOSE.JWS

Methods

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

class HasJwk a where

Methods

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

Instances

HasJWSHeader a => HasJwk a

Defined in Crypto.JOSE.JWS

Methods

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

class HasKid a where

Methods

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

Instances

HasJWSHeader a => HasKid a

Defined in Crypto.JOSE.JWS

Methods

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

class HasX5u a where

Methods

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

Instances

HasJWSHeader a => HasX5u a

Defined in Crypto.JOSE.JWS

Methods

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

class HasX5c a where

Methods

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

Instances

HasJWSHeader a => HasX5c a

Defined in Crypto.JOSE.JWS

Methods

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

class HasX5t a where

Methods

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

Instances

HasJWSHeader a => HasX5t a

Defined in Crypto.JOSE.JWS

Methods

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

class HasX5tS256 a where

Methods

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

Instances

HasJWSHeader a => HasX5tS256 a

Defined in Crypto.JOSE.JWS

Methods

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

class HasTyp a where

Methods

typ :: Lens' (a p) (Maybe (HeaderParam p Text))

Instances

HasJWSHeader a => HasTyp a

Defined in Crypto.JOSE.JWS

Methods

typ :: Lens' (a p) (Maybe (HeaderParam p Text))

class HasCty a where

Methods

cty :: Lens' (a p) (Maybe (HeaderParam p Text))

Instances

HasJWSHeader a => HasCty a

Defined in Crypto.JOSE.JWS

Methods

cty :: Lens' (a p) (Maybe (HeaderParam p Text))

class HasCrit a where

Methods

crit :: Lens' (a p) (Maybe (NonEmpty Text))

Instances

HasJWSHeader a => HasCrit a

Defined in Crypto.JOSE.JWS

Methods

crit :: Lens' (a p) (Maybe (NonEmpty Text))