Crypto.JOSE.JWS

JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JavaScript Object Notation (JSON) based data structures. It is defined in RFC 7515.

doJwsSign :: JWK -> L.ByteString -> IO (Either Error (GeneralJWS JWSHeader))
doJwsSign jwk payload = runExceptT $ do
  alg <- bestJWSAlg jwk
  signJWS payload [(newJWSHeader (Protected, alg), jwk)]

doJwsVerify :: JWK -> GeneralJWS JWSHeader -> IO (Either Error ())
doJwsVerify jwk jws = runExceptT $ verifyJWS' jwk jws

Overview

data JWS t p a

JSON Web Signature data type. The payload can only be accessed by verifying the JWS.

Parameterised by the signature container type, the header ProtectionIndicator type, and the header record type.

Use encode and decode to convert a JWS to or from JSON. When encoding a JWS [] with exactly one signature, the flattened JWS JSON serialisation syntax is used, otherwise the general JWS JSON serialisation is used. When decoding a JWS [] either serialisation is accepted.

JWS Identity uses the flattened JSON serialisation or the JWS compact serialisation (see decodeCompact and encodeCompact).

Use signJWS to create a signed/MACed JWS.

Use verifyJWS to verify a JWS and extract the payload.

Instances

Eq (t (Signature p a)) => Eq (JWS t p a)

Methods

(==) :: JWS t p a -> JWS t p a -> Bool

(/=) :: JWS t p a -> JWS t p a -> Bool

Show (t (Signature p a)) => Show (JWS t p a)

Methods

showsPrec :: Int -> JWS t p a -> ShowS

show :: JWS t p a -> String

showList :: [JWS t p a] -> ShowS

(HasParams a, ProtectionIndicator p) => ToJSON (JWS [] p a)

Methods

toJSON :: JWS [] p a -> Value

toEncoding :: JWS [] p a -> Encoding

(HasParams a, ProtectionIndicator p) => ToJSON (JWS Identity p a)

Methods

toJSON :: JWS Identity p a -> Value

toEncoding :: JWS Identity p a -> Encoding

(HasParams a, ProtectionIndicator p) => FromJSON (JWS [] p a)

Methods

parseJSON :: Value -> Parser (JWS [] p a)

(HasParams a, ProtectionIndicator p) => FromJSON (JWS Identity p a)

Methods

parseJSON :: Value -> Parser (JWS Identity p a)

HasParams a => ToCompact (JWS Identity () a)

Methods

toCompact :: JWS Identity () a -> [ByteString]

HasParams a => FromCompact (JWS Identity () a)

Methods

fromCompact :: (AsError e, MonadError e m) => [ByteString] -> m (JWS Identity () a)

type GeneralJWS = JWS [] Protection

A JWS that allows multiple signatures, and cannot use the compact serialisation. Headers may be Protected or Unprotected.

type FlattenedJWS = JWS Identity Protection

A JWS with one signature, which uses the flattened serialisation. Headers may be Protected or Unprotected.

type CompactJWS = JWS Identity ()

A JWS with one signature which only allows protected parameters. Can use the flattened serialisation or the compact serialisation.

Defining additional header parameters

Several specifications extend JWS with additional header parameters. The JWS type is parameterised over the header type; this library provides the JWSHeader type which encompasses all the JWS header parameters defined in RFC 7515. To define an extended header type declare the data type, and instances for HasJWSHeader and HasParams. For example:

data ACMEHeader p = ACMEHeader
  { _acmeJwsHeader :: JWSHeader p
  , _acmeNonce :: Base64Octets
  }

acmeJwsHeader :: Lens' (ACMEHeader p) (JWSHeader p)
acmeJwsHeader f s@(ACMEHeader { _acmeJwsHeader = a}) =
  fmap (\a' -> s { _acmeJwsHeader = a'}) (f a)

acmeNonce :: Lens' (ACMEHeader p) Types.Base64Octets
acmeNonce f s@(ACMEHeader { _acmeNonce = a}) =
  fmap (\a' -> s { _acmeNonce = a'}) (f a)

instance HasJWSHeader ACMEHeader where
  jwsHeader = acmeJwsHeader

instance HasParams ACMEHeader where
  parseParamsFor proxy hp hu = ACMEHeader
    <$> parseParamsFor proxy hp hu
    <*> headerRequiredProtected "nonce" hp hu
  params h =
    (True, "nonce" .= view acmeNonce h)
    : params (view acmeJwsHeader h)
  extensions = const ["nonce"]

See also:

• HasParams
• headerRequired
• headerRequiredProtected
• headerOptional
• headerOptionalProtected

JWS creation

newJWSHeader :: (p, Alg) -> JWSHeader p

Construct a minimal header with the given algorithm and protection indicator for the alg header.

signJWS

Arguments

:: (Cons s s Word8 Word8, HasJWSHeader a, HasParams a, MonadRandom m, AsError e, MonadError e m, Traversable t, ProtectionIndicator p)

=> s

Payload

-> t (a p, JWK)

Traversable of header, key pairs

-> m (JWS t p a)

Create a signed or MACed JWS with the given payload by traversing a collection of (header, key) pairs.

JWS verification

verifyJWS

Arguments

:: (HasAlgorithms a, HasValidationPolicy a, AsError e, MonadError e m, HasJWSHeader h, HasParams h, JWKStore k, Cons s s Word8 Word8, AsEmpty s, Foldable t, ProtectionIndicator p)

=> a

validation settings

-> k

key or key store

-> JWS t p h

JWS

-> m s

Verify a JWS.

Signatures made with an unsupported algorithms are ignored. If the validation policy is AnyValidated, a single successfully validated signature is sufficient. If the validation policy is AllValidated then all remaining signatures (there must be at least one) must be valid.

Returns the payload if successfully verified.

verifyJWS'

Arguments

:: (AsError e, MonadError e m, HasJWSHeader h, HasParams h, JWKStore k, Cons s s Word8 Word8, AsEmpty s, Foldable t, ProtectionIndicator p)

=> k

key or key store

-> JWS t p h

JWS

-> m s

Verify a JWS with the default validation settings.

See also defaultValidationSettings.

JWS validation settings

defaultValidationSettings :: ValidationSettings

The default validation settings.

• All algorithms except "none" are acceptable.
• All signatures must be valid (and there must be at least one signature.)

data ValidationSettings

Validation settings:

• The set of acceptable signature algorithms
• The validation policy

Instances

HasValidationSettings ValidationSettings

Methods

validationSettings :: Lens' ValidationSettings ValidationSettings

validationSettingsAlgorithms :: Lens' ValidationSettings (Set Alg)

validationSettingsValidationPolicy :: Lens' ValidationSettings ValidationPolicy

data ValidationPolicy

Validation policy.

Constructors

AnyValidated

One successfully validated signature is sufficient

AllValidated

All signatures in all configured algorithms must be validated. No signatures in configured algorithms is also an error.

Instances

Eq ValidationPolicy

Methods

(==) :: ValidationPolicy -> ValidationPolicy -> Bool

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

class HasValidationSettings a where

Minimal complete definition

validationSettings

Methods

validationSettings :: Lens' a ValidationSettings

validationSettingsAlgorithms :: Lens' a (Set Alg)

validationSettingsValidationPolicy :: Lens' a ValidationPolicy

Instances

HasValidationSettings ValidationSettings

Methods

validationSettings :: Lens' ValidationSettings ValidationSettings

validationSettingsAlgorithms :: Lens' ValidationSettings (Set Alg)

validationSettingsValidationPolicy :: Lens' ValidationSettings ValidationPolicy

HasValidationSettings JWTValidationSettings

Methods

validationSettings :: Lens' JWTValidationSettings ValidationSettings

validationSettingsAlgorithms :: Lens' JWTValidationSettings (Set Alg)

validationSettingsValidationPolicy :: Lens' JWTValidationSettings ValidationPolicy

class HasAlgorithms s where

Minimal complete definition

algorithms

Methods

algorithms :: Lens' s (Set Alg)

Instances

HasValidationSettings a => HasAlgorithms a

Methods

algorithms :: Lens' a (Set Alg)

class HasValidationPolicy s where

Minimal complete definition

validationPolicy

Methods

validationPolicy :: Lens' s ValidationPolicy

Instances

HasValidationSettings a => HasValidationPolicy a

Methods

validationPolicy :: Lens' a ValidationPolicy

Signature data

signatures :: Foldable t => Fold (JWS t p a) (Signature p a)

data Signature p a

Signature object containing header, and signature bytes.

If it was decoded from a serialised JWS, it "remembers" how the protected header was encoded; the remembered value is used when computing the signing input and when serialising the object.

The remembered value is not used in equality checks, i.e. two decoded signatures with differently serialised by otherwise equal protected headers, and equal signature bytes, are equal.

Instances

Eq (a p) => Eq (Signature p a)

Methods

(==) :: Signature p a -> Signature p a -> Bool

(/=) :: Signature p a -> Signature p a -> Bool

Show (a p) => Show (Signature p a)

Methods

showsPrec :: Int -> Signature p a -> ShowS

show :: Signature p a -> String

showList :: [Signature p a] -> ShowS

(HasParams a, ProtectionIndicator p) => ToJSON (Signature p a)

Methods

toJSON :: Signature p a -> Value

toEncoding :: Signature p a -> Encoding

(HasParams a, ProtectionIndicator p) => FromJSON (Signature p a)

Methods

parseJSON :: Value -> Parser (Signature p a)

header :: Getter (Signature p a) (a p)

Getter for header of a signature

signature :: (Cons s s Word8 Word8, AsEmpty s) => Getter (Signature p a) s

Getter for signature bytes

JWS headers

data Alg

RFC 7518 §3.1. "alg" (Algorithm) Header Parameters Values for JWS

Constructors

HS256

HS384

HS512

RS256

RS384

RS512

ES256

ES384

ES512

PS256

PS384

PS512

None

EdDSA

Instances

Eq Alg

Methods

(==) :: Alg -> Alg -> Bool

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

Ord Alg

Methods

compare :: Alg -> Alg -> Ordering

(<) :: Alg -> Alg -> Bool

(<=) :: Alg -> Alg -> Bool

(>) :: Alg -> Alg -> Bool

(>=) :: Alg -> Alg -> Bool

max :: Alg -> Alg -> Alg

min :: Alg -> Alg -> Alg

Show Alg

Methods

showsPrec :: Int -> Alg -> ShowS

show :: Alg -> String

showList :: [Alg] -> ShowS

ToJSON Alg

Methods

toJSON :: Alg -> Value

toEncoding :: Alg -> Encoding

FromJSON Alg

Methods

parseJSON :: Value -> Parser Alg

class HasJWSHeader a where

Minimal complete definition

jwsHeader

Methods

jwsHeader :: Lens' (a p) (JWSHeader p)

Instances

HasJWSHeader JWSHeader

Methods

jwsHeader :: Functor f => (JWSHeader p -> f (JWSHeader p)) -> JWSHeader p -> f (JWSHeader p)

data JWSHeader p

JWS Header data type.

Instances

HasCrit JWSHeader

Methods

crit :: Functor f => (Maybe (NonEmpty Text) -> f (Maybe (NonEmpty Text))) -> JWSHeader p -> f (JWSHeader p)

HasCty JWSHeader

Methods

cty :: Functor f => (Maybe (HeaderParam p String) -> f (Maybe (HeaderParam p String))) -> JWSHeader p -> f (JWSHeader p)

HasTyp JWSHeader

Methods

typ :: Functor f => (Maybe (HeaderParam p String) -> f (Maybe (HeaderParam p String))) -> JWSHeader p -> f (JWSHeader p)

HasX5tS256 JWSHeader

Methods

x5tS256 :: Functor f => (Maybe (HeaderParam p Base64SHA256) -> f (Maybe (HeaderParam p Base64SHA256))) -> JWSHeader p -> f (JWSHeader p)

HasX5t JWSHeader

Methods

x5t :: Functor f => (Maybe (HeaderParam p Base64SHA1) -> f (Maybe (HeaderParam p Base64SHA1))) -> JWSHeader p -> f (JWSHeader p)

HasX5c JWSHeader

Methods

x5c :: Functor f => (Maybe (HeaderParam p (NonEmpty Base64X509)) -> f (Maybe (HeaderParam p (NonEmpty Base64X509)))) -> JWSHeader p -> f (JWSHeader p)

HasX5u JWSHeader

Methods

x5u :: Functor f => (Maybe (HeaderParam p URI) -> f (Maybe (HeaderParam p URI))) -> JWSHeader p -> f (JWSHeader p)

HasKid JWSHeader

Methods

kid :: Functor f => (Maybe (HeaderParam p String) -> f (Maybe (HeaderParam p String))) -> JWSHeader p -> f (JWSHeader p)

HasJwk JWSHeader

Methods

jwk :: Functor f => (Maybe (HeaderParam p JWK) -> f (Maybe (HeaderParam p JWK))) -> JWSHeader p -> f (JWSHeader p)

HasJku JWSHeader

Methods

jku :: Functor f => (Maybe (HeaderParam p URI) -> f (Maybe (HeaderParam p URI))) -> JWSHeader p -> f (JWSHeader p)

HasAlg JWSHeader

Methods

alg :: Functor f => (HeaderParam p Alg -> f (HeaderParam p Alg)) -> JWSHeader p -> f (JWSHeader p)

HasParams JWSHeader

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)

HasJWSHeader JWSHeader

Methods

jwsHeader :: Functor f => (JWSHeader p -> f (JWSHeader p)) -> JWSHeader p -> f (JWSHeader p)

Eq p => Eq (JWSHeader p)

Methods

(==) :: JWSHeader p -> JWSHeader p -> Bool

(/=) :: JWSHeader p -> JWSHeader p -> Bool

Show p => Show (JWSHeader p)

Methods

showsPrec :: Int -> JWSHeader p -> ShowS

show :: JWSHeader p -> String

showList :: [JWSHeader p] -> ShowS

module Crypto.JOSE.Error

module Crypto.JOSE.Header

module Crypto.JOSE.JWK

Orphan instances

HasJWSHeader a => HasCrit a

Methods

crit :: Functor f => (Maybe (NonEmpty Text) -> f (Maybe (NonEmpty Text))) -> a p -> f (a p)

HasJWSHeader a => HasCty a

Methods

cty :: Functor f => (Maybe (HeaderParam p String) -> f (Maybe (HeaderParam p String))) -> a p -> f (a p)

HasJWSHeader a => HasTyp a

Methods

typ :: Functor f => (Maybe (HeaderParam p String) -> f (Maybe (HeaderParam p String))) -> a p -> f (a p)

HasJWSHeader a => HasX5tS256 a

Methods

x5tS256 :: Functor f => (Maybe (HeaderParam p Base64SHA256) -> f (Maybe (HeaderParam p Base64SHA256))) -> a p -> f (a p)

HasJWSHeader a => HasX5t a

Methods

x5t :: Functor f => (Maybe (HeaderParam p Base64SHA1) -> f (Maybe (HeaderParam p Base64SHA1))) -> a p -> f (a p)

HasJWSHeader a => HasX5c a

Methods

x5c :: Functor f => (Maybe (HeaderParam p (NonEmpty Base64X509)) -> f (Maybe (HeaderParam p (NonEmpty Base64X509)))) -> a p -> f (a p)

HasJWSHeader a => HasX5u a

Methods

x5u :: Functor f => (Maybe (HeaderParam p URI) -> f (Maybe (HeaderParam p URI))) -> a p -> f (a p)

HasJWSHeader a => HasKid a

Methods

kid :: Functor f => (Maybe (HeaderParam p String) -> f (Maybe (HeaderParam p String))) -> a p -> f (a p)

HasJWSHeader a => HasJwk a

Methods

jwk :: Functor f => (Maybe (HeaderParam p JWK) -> f (Maybe (HeaderParam p JWK))) -> a p -> f (a p)

HasJWSHeader a => HasJku a

Methods

jku :: Functor f => (Maybe (HeaderParam p URI) -> f (Maybe (HeaderParam p URI))) -> a p -> f (a p)

HasJWSHeader a => HasAlg a

Methods

alg :: Functor f => (HeaderParam p Alg -> f (HeaderParam p Alg)) -> a p -> f (a p)