jose-0.6.0.2: Javascript Object Signing and Encryption and JSON Web Token library

Safe HaskellNone
LanguageHaskell98

Crypto.JOSE.JWS

Contents

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.

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

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

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

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

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

Methods

toJSON :: JWS [] p a -> Value #

toEncoding :: JWS [] p a -> Encoding #

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

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

(HasParams a, ProtectionIndicator p) => ToJSON (JWS Identity p a) Source # 
(HasParams a, ProtectionIndicator p) => FromJSON (JWS [] p a) Source # 

Methods

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

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

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

Methods

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

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

Methods

fromCompact :: (AsError e, MonadError e m) => [ByteString] -> m (JWS Identity () a) 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.

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

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

class HasAlgorithms s where Source #

Minimal complete definition

algorithms

Methods

algorithms :: Lens' s (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

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

Methods

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

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

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

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) Source # 
(HasParams a, ProtectionIndicator p) => FromJSON (Signature p a) Source # 

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

JWS headers

data Alg Source #

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

Instances

Eq Alg Source # 

Methods

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

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

Ord Alg Source # 

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

Methods

showsPrec :: Int -> Alg -> ShowS #

show :: Alg -> String #

showList :: [Alg] -> ShowS #

ToJSON Alg Source # 
FromJSON Alg Source # 

class HasJWSHeader a where Source #

Minimal complete definition

jwsHeader

Methods

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

Instances

data JWSHeader p Source #

JWS Header data type.

Instances

HasCrit JWSHeader Source # 

Methods

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

HasCty JWSHeader Source # 

Methods

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

HasTyp JWSHeader Source # 

Methods

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

HasX5tS256 JWSHeader Source # 
HasX5t JWSHeader Source # 
HasX5c JWSHeader Source # 
HasX5u JWSHeader Source # 

Methods

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

HasKid JWSHeader Source # 

Methods

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

HasJwk JWSHeader Source # 

Methods

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

HasJku JWSHeader Source # 

Methods

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

HasAlg JWSHeader Source # 

Methods

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

HasParams JWSHeader Source # 
HasJWSHeader JWSHeader Source # 

Methods

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

Eq p => Eq (JWSHeader p) Source # 

Methods

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

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

Show p => Show (JWSHeader p) Source # 

Orphan instances

HasJWSHeader a => HasCrit a Source # 

Methods

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

HasJWSHeader a => HasCty a Source # 

Methods

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

HasJWSHeader a => HasTyp a Source # 

Methods

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

HasJWSHeader a => HasX5tS256 a Source # 

Methods

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

HasJWSHeader a => HasX5t a Source # 

Methods

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

HasJWSHeader a => HasX5c a Source # 

Methods

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

HasJWSHeader a => HasX5u a Source # 

Methods

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

HasJWSHeader a => HasKid a Source # 

Methods

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

HasJWSHeader a => HasJwk a Source # 

Methods

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

HasJWSHeader a => HasJku a Source # 

Methods

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

HasJWSHeader a => HasAlg a Source # 

Methods

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