| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
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 p a
- type GeneralJWS = JWS [] Protection
- type FlattenedJWS = JWS Identity Protection
- type CompactJWS = JWS Identity ()
- newJWSHeader :: (p, Alg) -> JWSHeader p
- makeJWSHeader :: forall e m p. (MonadError e m, AsError e, ProtectionIndicator p) => JWK -> m (JWSHeader p)
- signJWS :: (Cons s s Word8 Word8, HasJWSHeader a, HasParams a, MonadRandom m, AsError e, MonadError e m, Traversable t, ProtectionIndicator p) => s -> t (a p, JWK) -> m (JWS t p a)
- verifyJWS :: (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 -> k -> JWS t p h -> m s
- verifyJWS' :: (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 -> JWS t p h -> m s
- verifyJWSWithPayload :: (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) -> 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
- signatures :: Foldable t => Fold (JWS t p a) (Signature p a)
- data Signature p a
- header :: Getter (Signature p a) (a p)
- signature :: (Cons s s Word8 Word8, AsEmpty s) => Getter (Signature p a) s
- rawProtectedHeader :: (HasParams a, ProtectionIndicator p) => Signature p a -> ByteString
- data Alg
- class HasJWSHeader a where
- data JWSHeader p
- module Crypto.JOSE.Error
- module Crypto.JOSE.Header
- module Crypto.JOSE.JWK
Overview
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 []JWS []
JWS IdentitydecodeCompact 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) Source # | |
| (HasParams a, ProtectionIndicator p) => FromJSON (JWS [] p a) Source # | |
| (HasParams a, ProtectionIndicator p) => ToJSON (JWS Identity p a) Source # | |
| (HasParams a, ProtectionIndicator p) => ToJSON (JWS [] p a) Source # | |
Defined in Crypto.JOSE.JWS | |
| 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 () a) Source # | |
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 # | |
Defined in Crypto.JOSE.JWS | |
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.
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
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.
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.
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 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 | |
Signature data
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.
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
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 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 => HasCrit 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 # | |