jose-0.10: JSON Object Signing and Encryption (JOSE) and JSON Web Token (JWT) library
Safe HaskellSafe-Inferred
LanguageHaskell2010

Crypto.JOSE.JWS

Description

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
Synopsis

Overview

data JWS t p a Source #

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

Instances details
(HasParams a, ProtectionIndicator p) => FromJSON (JWS Identity p a) Source # 
Instance details

Defined in Crypto.JOSE.JWS

(HasParams a, ProtectionIndicator p) => FromJSON (JWS [] p a) Source # 
Instance details

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) Source # 
Instance details

Defined in Crypto.JOSE.JWS

(HasParams a, ProtectionIndicator p) => ToJSON (JWS [] p a) Source # 
Instance details

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) Source # 
Instance details

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) Source # 
Instance details

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) Source # 
Instance details

Defined in Crypto.JOSE.JWS

Methods

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

HasParams a => ToCompact (JWS Identity () a) Source # 
Instance details

Defined in Crypto.JOSE.JWS

Methods

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

type GeneralJWS = JWS [] Protection Source #

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

type FlattenedJWS = JWS Identity Protection Source #

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

type CompactJWS = JWS Identity () Source #

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:

JWS creation

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

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

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 Source #

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 Source #

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' Source #

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 Source #

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 Source #

The default validation settings.

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

data ValidationPolicy Source #

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

Instances details
Eq ValidationPolicy Source # 
Instance details

Defined in Crypto.JOSE.JWS

class HasAlgorithms s where Source #

Methods

algorithms :: Lens' s (Set Alg) Source #

Instances

Instances details
HasValidationSettings a => HasAlgorithms a Source # 
Instance details

Defined in Crypto.JOSE.JWS

Methods

algorithms :: Lens' a (Set Alg) Source #

Signature data

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

data Signature p a Source #

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

Instances details
(HasParams a, ProtectionIndicator p) => FromJSON (Signature p a) Source # 
Instance details

Defined in Crypto.JOSE.JWS

(HasParams a, ProtectionIndicator p) => ToJSON (Signature p a) Source # 
Instance details

Defined in Crypto.JOSE.JWS

Show (a p) => Show (Signature p a) Source # 
Instance details

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) Source # 
Instance details

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

Getter for header of a signature

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

Getter for signature bytes

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

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 Source #

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

Instances

Instances details
FromJSON Alg Source # 
Instance details

Defined in Crypto.JOSE.JWA.JWS

ToJSON Alg Source # 
Instance details

Defined in Crypto.JOSE.JWA.JWS

Show Alg Source # 
Instance details

Defined in Crypto.JOSE.JWA.JWS

Methods

showsPrec :: Int -> Alg -> ShowS #

show :: Alg -> String #

showList :: [Alg] -> ShowS #

Eq Alg Source # 
Instance details

Defined in Crypto.JOSE.JWA.JWS

Methods

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

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

Ord Alg Source # 
Instance details

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 Source #

Methods

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

Instances

Instances details
HasJWSHeader JWSHeader Source # 
Instance details

Defined in Crypto.JOSE.JWS

data JWSHeader p Source #

JWS Header data type.

Instances

Instances details
HasParams JWSHeader Source # 
Instance details

Defined in Crypto.JOSE.JWS

HasJWSHeader JWSHeader Source # 
Instance details

Defined in Crypto.JOSE.JWS

Show p => Show (JWSHeader p) Source # 
Instance details

Defined in Crypto.JOSE.JWS

Eq p => Eq (JWSHeader p) Source # 
Instance details

Defined in Crypto.JOSE.JWS

Methods

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

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

Orphan instances

HasJWSHeader a => HasAlg a Source # 
Instance details

Methods

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

HasJWSHeader a => HasCrit a Source # 
Instance details

Methods

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

HasJWSHeader a => HasCty a Source # 
Instance details

Methods

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

HasJWSHeader a => HasJku a Source # 
Instance details

Methods

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

HasJWSHeader a => HasJwk a Source # 
Instance details

Methods

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

HasJWSHeader a => HasKid a Source # 
Instance details

Methods

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

HasJWSHeader a => HasTyp a Source # 
Instance details

Methods

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

HasJWSHeader a => HasX5c a Source # 
Instance details

HasJWSHeader a => HasX5t a Source # 
Instance details

Methods

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

HasJWSHeader a => HasX5tS256 a Source # 
Instance details

HasJWSHeader a => HasX5u a Source # 
Instance details

Methods

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