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.

import Crypto.JOSE

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

doJwsVerify :: JWK -> GeneralJWS JWSHeader -> IO (Either Error ())
doJwsVerify jwk jws = runJOSE $
  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

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

Defined in Crypto.JOSE.JWS

Methods

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

parseJSONList :: Value -> Parser [JWS Identity p a]

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

Defined in Crypto.JOSE.JWS

Methods

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

parseJSONList :: Value -> Parser [JWS [] p a]

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

Defined in Crypto.JOSE.JWS

Methods

toJSON :: JWS Identity p a -> Value

toEncoding :: JWS Identity p a -> Encoding

toJSONList :: [JWS Identity p a] -> Value

toEncodingList :: [JWS Identity p a] -> Encoding

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

Defined in Crypto.JOSE.JWS

Methods

toJSON :: JWS [] p a -> Value

toEncoding :: JWS [] p a -> Encoding

toJSONList :: [JWS [] p a] -> Value

toEncodingList :: [JWS [] p a] -> Encoding

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

Defined in Crypto.JOSE.JWS

Methods

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

show :: JWS t p a -> String

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

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

Defined in Crypto.JOSE.JWS

Methods

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

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

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

Defined in Crypto.JOSE.JWS

Methods

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

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

Defined in Crypto.JOSE.JWS

Methods

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

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
• headerOptional'
• headerOptionalProtected

JWS creation

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

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

makeJWSHeader :: forall e m p. (MonadError e m, AsError e, ProtectionIndicator p) => JWK -> m (JWSHeader p)

Make a JWS header for the given signing key.

Uses bestJWSAlg to choose the algorithm. If set, the JWK's "kid", "x5u", "x5c", "x5t" and "x5t#S256" parameters are copied to the JWS header (as protected parameters).

May return KeySizeTooSmall or KeyMismatch.

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, VerificationKeyStore m (h p) s 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, VerificationKeyStore m (h p) s 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.

verifyJWSWithPayload

Arguments

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

=> (s -> m payload)

payload decoder

-> a

validation settings

-> k

key or key store

-> JWS t p h

JWS

-> m payload

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

Defined in Crypto.JOSE.JWS

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

Defined in Crypto.JOSE.JWS

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

Defined in Crypto.JOSE.JWS

Methods

validationSettings :: Lens' ValidationSettings ValidationSettings

validationSettingsAlgorithms :: Lens' ValidationSettings (Set Alg)

validationSettingsValidationPolicy :: Lens' ValidationSettings ValidationPolicy

HasJWTValidationSettings a => HasValidationSettings a

Defined in Crypto.JWT

Methods

validationSettings :: Lens' a ValidationSettings

validationSettingsAlgorithms :: Lens' a (Set Alg)

validationSettingsValidationPolicy :: Lens' a ValidationPolicy

class HasAlgorithms s where

Methods

algorithms :: Lens' s (Set Alg)

Instances

HasValidationSettings a => HasAlgorithms a

Defined in Crypto.JOSE.JWS

Methods

algorithms :: Lens' a (Set Alg)

class HasValidationPolicy s where

Methods

validationPolicy :: Lens' s ValidationPolicy

Instances

HasValidationSettings a => HasValidationPolicy a

Defined in Crypto.JOSE.JWS

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

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

Defined in Crypto.JOSE.JWS

Methods

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

parseJSONList :: Value -> Parser [Signature p a]

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

Defined in Crypto.JOSE.JWS

Methods

toJSON :: Signature p a -> Value

toEncoding :: Signature p a -> Encoding

toJSONList :: [Signature p a] -> Value

toEncodingList :: [Signature p a] -> Encoding

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

Defined in Crypto.JOSE.JWS

Methods

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

show :: Signature p a -> String

showList :: [Signature p a] -> ShowS

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

Defined in Crypto.JOSE.JWS

Methods

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

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

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

rawProtectedHeader :: (HasParams a, ProtectionIndicator p) => Signature p a -> ByteString

Return the raw base64url-encoded protected header value. If the Signature was decoded from JSON, this returns the original string value as-is.

Application code should never need to use this. It is exposed for testing purposes.

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

ES256K

PS256

PS384

PS512

None

EdDSA

Instances

FromJSON Alg

Defined in Crypto.JOSE.JWA.JWS

Methods

parseJSON :: Value -> Parser Alg

parseJSONList :: Value -> Parser [Alg]

ToJSON Alg

Defined in Crypto.JOSE.JWA.JWS

Methods

toJSON :: Alg -> Value

toEncoding :: Alg -> Encoding

toJSONList :: [Alg] -> Value

toEncodingList :: [Alg] -> Encoding

Show Alg

Defined in Crypto.JOSE.JWA.JWS

Methods

showsPrec :: Int -> Alg -> ShowS

show :: Alg -> String

showList :: [Alg] -> ShowS

Eq Alg

Defined in Crypto.JOSE.JWA.JWS

Methods

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

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

Ord Alg

Defined in Crypto.JOSE.JWA.JWS

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

class HasJWSHeader a where

Methods

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

Instances

HasJWSHeader JWSHeader

Defined in Crypto.JOSE.JWS

Methods

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

data JWSHeader p

JWS Header data type.

Instances

HasParams JWSHeader

Defined in Crypto.JOSE.JWS

Methods

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

extensions :: Proxy JWSHeader -> [Text]

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

HasJWSHeader JWSHeader

Defined in Crypto.JOSE.JWS

Methods

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

Show p => Show (JWSHeader p)

Defined in Crypto.JOSE.JWS

Methods

showsPrec :: Int -> JWSHeader p -> ShowS

show :: JWSHeader p -> String

showList :: [JWSHeader p] -> ShowS

Eq p => Eq (JWSHeader p)

Defined in Crypto.JOSE.JWS

Methods

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

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

module Crypto.JOSE.Error

module Crypto.JOSE.Header

module Crypto.JOSE.JWK

Orphan instances

HasJWSHeader a => HasAlg a

Methods

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

HasJWSHeader a => HasCrit a

Methods

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

HasJWSHeader a => HasCty a

Methods

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

HasJWSHeader a => HasJku a

Methods

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

HasJWSHeader a => HasJwk a

Methods

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

HasJWSHeader a => HasKid a

Methods

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

HasJWSHeader a => HasTyp a

Methods

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

HasJWSHeader a => HasX5c a

Methods

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

HasJWSHeader a => HasX5t a

Methods

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

HasJWSHeader a => HasX5tS256 a

Methods

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

HasJWSHeader a => HasX5u a

Methods

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