Modulejose-0.13GHC2021

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

9 types
4 classes
13 values

Packagejose-0.13
Exports26
LanguageGHC2021
LicenceApache-2.0
SourceJWS.hs

Overview

4 declarations

datadata JWS (t :: Type -> Type) (p :: k) (a :: k -> Type)

JSON Web Signature data type.

Parameterised by the signature container type, the header ProtectionSupport 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.

Instances8Eq, Show, FromJSON, ToJSON, FromCompact, ToCompact, …

Eq (t (Signature p a)) => Eq (JWS t p a)Defined in jose-0.13 · Crypto.JOSE.JWS
Show (t (Signature p a)) => Show (JWS t p a)Defined in jose-0.13 · Crypto.JOSE.JWS
(HasParams a, ProtectionSupport p) => FromJSON (JWS Identity p a)Defined in jose-0.13 · Crypto.JOSE.JWS
(HasParams a, ProtectionSupport p) => FromJSON (JWS [] p a)Defined in jose-0.13 · Crypto.JOSE.JWS
(HasParams a, ProtectionSupport p) => ToJSON (JWS Identity p a)Defined in jose-0.13 · Crypto.JOSE.JWS
(HasParams a, ProtectionSupport p) => ToJSON (JWS [] p a)Defined in jose-0.13 · Crypto.JOSE.JWS
HasParams a => FromCompact (JWS Identity RequiredProtection a)Defined in jose-0.13 · Crypto.JOSE.JWS
HasParams a => ToCompact (JWS Identity RequiredProtection a)Defined in jose-0.13 · Crypto.JOSE.JWS

typetype GeneralJWS = JWS [] OptionalProtection

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

typetype FlattenedJWS = JWS Identity OptionalProtection

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

typetype CompactJWS = JWS Identity RequiredProtection

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"]

JWS creation

4 declarations

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

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

valuenewJWSHeaderProtected :: ProtectionSupport p => Alg -> JWSHeader p

Construct a minimal JWS header with the given "alg" header value, to be carried as a protected header.

valuemakeJWSHeader

:: (MonadError e m, AsError e, ProtectionSupport 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.

valuesignJWS

:: (Cons s s Word8 Word8, HasJWSHeader a, HasParams a, MonadRandom m, AsError e, MonadError e m, Traversable t, ProtectionSupport 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

3 declarations

valueverifyJWS

:: (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, ProtectionSupport 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.

valueverifyJWS'

:: (AsError e, MonadError e m, HasJWSHeader h, HasParams h, VerificationKeyStore m (h p) s k, Cons s s Word8 Word8, AsEmpty s, Foldable t, ProtectionSupport p)
=> k
key or key store
-> JWS t p h
JWS
-> m s

Verify a JWS with the default validation settings.

JWS validation settings

valuedefaultValidationSettings :: ValidationSettings

The default validation settings.

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

datadata ValidationSettings

Validation settings:

The set of acceptable signature algorithms
The validation policy

Instances1HasValidationSettings

HasValidationSettings ValidationSettingsDefined in jose-0.13 · Crypto.JOSE.JWS

datadata 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.

Instances1Eq

Eq ValidationPolicyDefined in jose-0.13 · Crypto.JOSE.JWS

classclass HasValidationSettings a where

Methods

validationSettings :: Lens' a ValidationSettings
validationSettingsAlgorithms :: Lens' a (Set Alg)
validationSettingsValidationPolicy :: Lens' a ValidationPolicy

Instances2HasValidationSettings

HasValidationSettings ValidationSettingsDefined in jose-0.13 · Crypto.JOSE.JWS
HasJWTValidationSettings a => HasValidationSettings aDefined in jose-0.13 · Crypto.JWT · orphan

classclass HasAlgorithms s where

Methods

algorithms :: Lens' s (Set Alg)

Instances1HasAlgorithms

HasValidationSettings a => HasAlgorithms aDefined in jose-0.13 · Crypto.JOSE.JWS

classclass HasValidationPolicy s where

Methods

validationPolicy :: Lens' s ValidationPolicy

Instances1HasValidationPolicy

HasValidationSettings a => HasValidationPolicy aDefined in jose-0.13 · Crypto.JOSE.JWS

Access payload without verification

1 declaration

valueunsafeGetPayload

:: (Cons s s Word8 Word8, AsEmpty s)
=> (s -> m payload)
Function to decode payload
-> JWS t p a
JWS
-> m payload

Get the payload without verifying it. Do not use this function unless you have a compelling reason.

Most applications should use verifyJWSWithPayload, verifyJWS or verifyJWS' to verify the JWS and access the payload.

Signature data

5 declarations

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

datadata Signature (p :: k) (a :: k -> Type)

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.

Instances4Eq, Show, FromJSON, ToJSON

Eq (a p) => Eq (Signature p a)Defined in jose-0.13 · Crypto.JOSE.JWS
Show (a p) => Show (Signature p a)Defined in jose-0.13 · Crypto.JOSE.JWS
(HasParams a, ProtectionSupport p) => FromJSON (Signature p a)Defined in jose-0.13 · Crypto.JOSE.JWS
(HasParams a, ProtectionSupport p) => ToJSON (Signature p a)Defined in jose-0.13 · Crypto.JOSE.JWS