| Safe Haskell | None |
|---|---|
| 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.
doJwsSign ::JWK-> L.ByteString -> IO (EitherError(GeneralJWSJWSHeader)) doJwsSign jwk payload = runExceptT $ do alg <-bestJWSAlgjwksignJWSpayload [(newJWSHeader(Protected, alg), jwk)] doJwsVerify ::JWK->GeneralJWSJWSHeader-> IO (EitherError()) doJwsVerify jwk jws = runExceptT $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
- validationSettings :: Lens' a ValidationSettings
- validationSettingsAlgorithms :: Lens' a (Set Alg)
- validationSettingsValidationPolicy :: Lens' a ValidationPolicy
- class HasAlgorithms s where
- algorithms :: Lens' s (Set Alg)
- class HasValidationPolicy s where
- validationPolicy :: Lens' s ValidationPolicy
- 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
| Eq (t (Signature p a)) => Eq (JWS t p a) Source # | |
| Show (t (Signature p a)) => Show (JWS t p a) Source # | |
| HasParams a => ToCompact (JWS Identity () a) Source # | |
Defined in Crypto.JOSE.JWS | |
| 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, ProtectionIndicator p) => FromJSON (JWS [] p a) Source # | |
Defined in Crypto.JOSE.JWS | |
| (HasParams a, ProtectionIndicator p) => FromJSON (JWS Identity p a) Source # | |
Defined in Crypto.JOSE.JWS Methods parseJSON :: Value -> Parser (JWS Identity p a) parseJSONList :: Value -> Parser [JWS Identity p a] | |
| (HasParams a, ProtectionIndicator p) => ToJSON (JWS [] p a) Source # | |
Defined in Crypto.JOSE.JWS Methods 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 # | |
Defined in Crypto.JOSE.JWS Methods toJSON :: JWS Identity p a -> Value toEncoding :: JWS Identity p a -> Encoding toJSONList :: [JWS Identity p a] -> Value toEncodingList :: [JWS Identity p a] -> Encoding | |
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
| HasValidationSettings ValidationSettings Source # | |
Defined in Crypto.JOSE.JWS Methods validationSettings :: Lens' ValidationSettings ValidationSettings Source # validationSettingsAlgorithms :: Lens' ValidationSettings (Set Alg) Source # validationSettingsValidationPolicy :: Lens' ValidationSettings ValidationPolicy Source # | |
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
| HasJWTValidationSettings a => HasValidationSettings a Source # | |
Defined in Crypto.JWT Methods validationSettings :: Lens' a ValidationSettings Source # validationSettingsAlgorithms :: Lens' a (Set Alg) Source # validationSettingsValidationPolicy :: Lens' a ValidationPolicy Source # | |
| HasValidationSettings ValidationSettings Source # | |
Defined in Crypto.JOSE.JWS Methods validationSettings :: Lens' ValidationSettings ValidationSettings Source # validationSettingsAlgorithms :: Lens' ValidationSettings (Set Alg) Source # validationSettingsValidationPolicy :: Lens' ValidationSettings ValidationPolicy Source # | |
class HasAlgorithms s where Source #
Methods
algorithms :: Lens' s (Set Alg) Source #
Instances
| HasValidationSettings a => HasAlgorithms a Source # | |
Defined in Crypto.JOSE.JWS Methods algorithms :: Lens' a (Set Alg) Source # | |
class HasValidationPolicy s where Source #
Methods
validationPolicy :: Lens' s ValidationPolicy Source #
Instances
| HasValidationSettings a => HasValidationPolicy a Source # | |
Defined in Crypto.JOSE.JWS Methods validationPolicy :: Lens' a ValidationPolicy Source # | |
Signature data
signatures :: Foldable t => Fold (JWS t p a) (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 # | |
| Show (a p) => Show (Signature p a) Source # | |
| (HasParams a, ProtectionIndicator p) => FromJSON (Signature p a) Source # | |
Defined in Crypto.JOSE.JWS | |
| (HasParams a, ProtectionIndicator p) => ToJSON (Signature p a) Source # | |
Defined in Crypto.JOSE.JWS Methods toJSON :: Signature p a -> Value toEncoding :: Signature p a -> Encoding toJSONList :: [Signature p a] -> Value toEncodingList :: [Signature p a] -> Encoding | |
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
Instances
| Eq Alg Source # | |
| Ord Alg Source # | |
| Show Alg Source # | |
| FromJSON Alg Source # | |
Defined in Crypto.JOSE.JWA.JWS | |
| ToJSON Alg Source # | |
Defined in Crypto.JOSE.JWA.JWS | |
class HasJWSHeader a where Source #
Instances
JWS Header data type.
Instances
| HasParams JWSHeader Source # | |
Defined in Crypto.JOSE.JWS Methods params :: ProtectionIndicator p => JWSHeader p -> [(Bool, Pair)] Source # extensions :: Proxy JWSHeader -> [Text] Source # parseParamsFor :: forall (b :: Type -> Type) p. (HasParams b, ProtectionIndicator p) => Proxy b -> Maybe Object -> Maybe Object -> Parser (JWSHeader p) Source # | |
| HasJWSHeader JWSHeader Source # | |
| Eq p => Eq (JWSHeader p) Source # | |
| Show p => Show (JWSHeader p) Source # | |
module Crypto.JOSE.Error
module Crypto.JOSE.Header
module Crypto.JOSE.JWK