| Safe Haskell | None |
|---|---|
| Language | GHC2021 |
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 (EitherError(GeneralJWSJWSHeader)) doJwsSign jwk payload =runJOSE$ do alg <-bestJWSAlgjwksignJWSpayload [(newJWSHeader(Protected, alg), jwk)] doJwsVerify ::JWK->GeneralJWSJWSHeader-> IO (EitherError()) doJwsVerify jwk jws =runJOSE$verifyJWS'jwk jws
Synopsis
- data JWS (t :: Type -> Type) (p :: k) (a :: k -> Type)
- type GeneralJWS = JWS [] OptionalProtection
- type FlattenedJWS = JWS Identity OptionalProtection
- type CompactJWS = JWS Identity RequiredProtection
- newJWSHeader :: (p, Alg) -> JWSHeader p
- newJWSHeaderProtected :: ProtectionSupport p => Alg -> JWSHeader p
- makeJWSHeader :: (MonadError e m, AsError e, ProtectionSupport p) => JWK -> m (JWSHeader p)
- signJWS :: (Cons s s Word8 Word8, HasJWSHeader a, HasParams a, MonadRandom m, AsError e, MonadError e m, Traversable t, ProtectionSupport p) => s -> t (a p, JWK) -> m (JWS t p a)
- verifyJWS :: forall a e m (h :: Type -> Type) p s k (t :: Type -> Type). (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 -> k -> JWS t p h -> m s
- verifyJWS' :: forall e m (h :: Type -> Type) p s k (t :: Type -> Type). (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 -> JWS t p h -> m s
- verifyJWSWithPayload :: forall a e m (h :: Type -> Type) p payload k s (t :: Type -> Type). (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, ProtectionSupport p) => (s -> m payload) -> a -> k -> JWS t p h -> m payload
- defaultValidationSettings :: ValidationSettings
- data ValidationSettings
- data ValidationPolicy
- class HasValidationSettings a where
- class HasAlgorithms s where
- algorithms :: Lens' s (Set Alg)
- class HasValidationPolicy s where
- unsafeGetPayload :: forall {k1} {k2} s m (payload :: k1) (t :: Type -> Type) (p :: k2) (a :: k2 -> Type). (Cons s s Word8 Word8, AsEmpty s) => (s -> m payload) -> JWS t p a -> m payload
- signatures :: forall {k} (t :: Type -> Type) (p :: k) (a :: k -> Type). Foldable t => Fold (JWS t p a) (Signature p a)
- data Signature (p :: k) (a :: k -> Type)
- header :: forall {k} (p :: k) a f. (Contravariant f, Functor f) => (a p -> f (a p)) -> Signature p a -> f (Signature p a)
- signature :: forall {k} s (p :: k) (a :: k -> Type). (Cons s s Word8 Word8, AsEmpty s) => Getter (Signature p a) s
- rawProtectedHeader :: forall (a :: Type -> Type) p. (HasParams a, ProtectionSupport p) => Signature p a -> ByteString
- data Alg
- class HasJWSHeader (a :: Type -> Type) where
- data JWSHeader p
- module Crypto.JOSE.Error
- module Crypto.JOSE.Header
- module Crypto.JOSE.JWK
Overview
data JWS (t :: Type -> Type) (p :: k) (a :: k -> Type) Source #
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 []JWS []
JWS IdentitydecodeCompact and
encodeCompact).
Use signJWS to create a signed/MACed JWS.
Instances
| (HasParams a, ProtectionSupport p) => FromJSON (JWS Identity p a) Source # | |
| (HasParams a, ProtectionSupport p) => FromJSON (JWS [] p a) Source # | |
| (HasParams a, ProtectionSupport p) => ToJSON (JWS Identity p a) Source # | |
| (HasParams a, ProtectionSupport p) => ToJSON (JWS [] p a) Source # | |
| Show (t (Signature p a)) => Show (JWS t p a) Source # | |
| Eq (t (Signature p a)) => Eq (JWS t p a) Source # | |
| HasParams a => FromCompact (JWS Identity RequiredProtection a) Source # | |
Defined in Crypto.JOSE.JWS Methods fromCompact :: (AsError e, MonadError e m) => [ByteString] -> m (JWS Identity RequiredProtection a) Source # | |
| HasParams a => ToCompact (JWS Identity RequiredProtection a) Source # | |
Defined in Crypto.JOSE.JWS Methods toCompact :: JWS Identity RequiredProtection a -> [ByteString] Source # | |
type GeneralJWS = JWS [] OptionalProtection Source #
A JWS that allows multiple signatures, and cannot use
the compact serialisation. Headers may be Protected
or Unprotected.
type FlattenedJWS = JWS Identity OptionalProtection Source #
A JWS with one signature, which uses the
flattened serialisation. Headers may be Protected
or Unprotected.
type CompactJWS = JWS Identity RequiredProtection 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 value for the "alg" header.
newJWSHeaderProtected :: ProtectionSupport p => Alg -> JWSHeader p Source #
Construct a minimal JWS header with the given "alg" header
value, to be carried as a protected header.
makeJWSHeader :: (MonadError e m, AsError e, ProtectionSupport 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.
Arguments
| :: (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
Arguments
| :: forall a e m (h :: Type -> Type) p s k (t :: Type -> Type). (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.
Arguments
| :: forall e m (h :: Type -> Type) p s k (t :: Type -> Type). (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.
See also defaultValidationSettings.
Arguments
| :: forall a e m (h :: Type -> Type) p payload k s (t :: Type -> Type). (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, ProtectionSupport p) | |
| => (s -> m payload) | payload decoder |
| -> a | validation settings |
| -> k | key or key store |
| -> JWS t p h | JWS |
| -> m payload |
Verify a JWS, with explicit payload decoding. This variant enables the key store to use information in the payload to locate verification key(s).
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 ValidationSettings Source #
Validation settings:
- The set of acceptable signature algorithms
- The validation policy
Instances
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
| Eq ValidationPolicy Source # | |
Defined in Crypto.JOSE.JWS Methods (==) :: ValidationPolicy -> ValidationPolicy -> Bool # (/=) :: ValidationPolicy -> ValidationPolicy -> Bool # | |
class HasValidationSettings a where Source #
Minimal complete definition
Methods
validationSettings :: Lens' a ValidationSettings Source #
validationSettingsAlgorithms :: Lens' a (Set Alg) Source #
validationSettingsValidationPolicy :: Lens' a ValidationPolicy Source #
Instances
class HasAlgorithms s where Source #
Instances
| HasValidationSettings a => HasAlgorithms a Source # | |
Defined in Crypto.JOSE.JWS | |
class HasValidationPolicy s where Source #
Methods
Instances
| HasValidationSettings a => HasValidationPolicy a Source # | |
Defined in Crypto.JOSE.JWS Methods | |
Access payload without verification
Arguments
| :: forall {k1} {k2} s m (payload :: k1) (t :: Type -> Type) (p :: k2) (a :: k2 -> Type). (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
signatures :: forall {k} (t :: Type -> Type) (p :: k) (a :: k -> Type). Foldable t => Fold (JWS t p a) (Signature p a) Source #
data Signature (p :: k) (a :: k -> Type) 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.
header :: forall {k} (p :: k) a f. (Contravariant f, Functor f) => (a p -> f (a p)) -> Signature p a -> f (Signature p a) Source #
Getter for header of a signature
signature :: forall {k} s (p :: k) (a :: k -> Type). (Cons s s Word8 Word8, AsEmpty s) => Getter (Signature p a) s Source #
Getter for signature bytes
rawProtectedHeader :: forall (a :: Type -> Type) p. (HasParams a, ProtectionSupport 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
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 |
class HasJWSHeader (a :: Type -> Type) where Source #
JWS Header data type.
module Crypto.JOSE.Error
module Crypto.JOSE.Header
module Crypto.JOSE.JWK
Orphan instances
| HasJWSHeader a => HasAlg a Source # | |
| HasJWSHeader a => HasCty a Source # | |
| HasJWSHeader a => HasJku a Source # | |
| HasJWSHeader a => HasJwk a Source # | |
| HasJWSHeader a => HasKid a Source # | |
| HasJWSHeader a => HasTyp a Source # | |
| HasJWSHeader a => HasX5c a Source # | |
Methods x5c :: Lens' (a p) (Maybe (HeaderParam p (NonEmpty SignedCertificate))) Source # | |
| HasJWSHeader a => HasX5t a Source # | |
Methods x5t :: Lens' (a p) (Maybe (HeaderParam p Base64SHA1)) Source # | |
| HasJWSHeader a => HasX5tS256 a Source # | |
Methods x5tS256 :: Lens' (a p) (Maybe (HeaderParam p Base64SHA256)) Source # | |
| HasJWSHeader a => HasX5u a Source # | |
| HasJWSHeader a => HasCrit (a :: Type -> Type) Source # | |