Safe Haskell	Safe-Inferred
Language	Haskell2010

Crypto.JOSE.JWK

Contents

JWK generation
Parts of a JWK
Converting from other key formats
JWK Thumbprint
JWK Set

Description

A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This module also defines a JSON Web Key Set (JWK Set) JSON data structure for representing a set of JWKs.

-- Generate RSA JWK and set "kid" param to
-- base64url-encoded SHA-256 thumbprint of key.
--
doGen :: IO JWK
doGen = do
  jwk <- genJWK (RSAGenParam (4096 `div` 8))
  let
    h = view thumbprint jwk :: Digest SHA256
    kid = view (re (base64url . digest) . utf8) h
  pure $ set jwkKid (Just kid) jwk

Synopsis

genJWK :: MonadRandom m => KeyMaterialGenParam -> m JWK
data KeyMaterialGenParam
- = ECGenParam Crv
- | RSAGenParam Int
- | OctGenParam Int
- | OKPGenParam OKPCrv
data Crv
- = P_256
- | P_384
- | P_521
- | Secp256k1
data OKPCrv
- = Ed25519
- | Ed448
- | X25519
- | X448
data JWK
class AsPublicKey k where
- asPublicKey :: Getter k (Maybe k)
jwkMaterial :: Lens' JWK KeyMaterial
jwkUse :: Lens' JWK (Maybe KeyUse)
data KeyUse
- = Sig
- | Enc
jwkKeyOps :: Lens' JWK (Maybe [KeyOp])
data KeyOp
- = Sign
- | Verify
- | Encrypt
- | Decrypt
- | WrapKey
- | UnwrapKey
- | DeriveKey
- | DeriveBits
jwkAlg :: Lens' JWK (Maybe JWKAlg)
data JWKAlg
- = JWSAlg Alg
- | JWEAlg Alg
jwkKid :: Lens' JWK (Maybe Text)
jwkX5u :: Lens' JWK (Maybe URI)
jwkX5c :: Getter JWK (Maybe (NonEmpty SignedCertificate))
setJWKX5c :: Maybe (NonEmpty SignedCertificate) -> JWK -> Maybe JWK
jwkX5t :: Lens' JWK (Maybe Base64SHA1)
jwkX5tS256 :: Lens' JWK (Maybe Base64SHA256)
fromKeyMaterial :: KeyMaterial -> JWK
fromRSA :: PrivateKey -> JWK
fromOctets :: Cons s s Word8 Word8 => s -> JWK
fromX509Certificate :: (AsError e, MonadError e m) => SignedCertificate -> m JWK
thumbprint :: HashAlgorithm a => Getter JWK (Digest a)
digest :: HashAlgorithm a => Prism' ByteString (Digest a)
base64url :: (AsEmpty s1, AsEmpty s2, Cons s1 s1 Word8 Word8, Cons s2 s2 Word8 Word8) => Prism' s1 s2
module Crypto.Hash
newtype JWKSet = JWKSet [JWK]
checkJWK :: (MonadError e m, AsError e) => JWK -> m ()
bestJWSAlg :: (MonadError e m, AsError e) => JWK -> m Alg
module Crypto.JOSE.JWA.JWK

JWK generation

genJWK :: MonadRandom m => KeyMaterialGenParam -> m JWK Source #

Generate a JWK. Apart from key parameters, no other parameters are set.

data KeyMaterialGenParam Source #

Keygen parameters.

Constructors

ECGenParam Crv	Generate an EC key with specified curve.
RSAGenParam Int	Generate an RSA key with specified size in bytes.
OctGenParam Int	Generate a symmetric key with specified size in bytes.
OKPGenParam OKPCrv	Generate an EdDSA or Edwards ECDH key with specified curve.

Instances

Instances details

Show KeyMaterialGenParam Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods showsPrec :: Int -> KeyMaterialGenParam -> ShowS # show :: KeyMaterialGenParam -> String # showList :: [KeyMaterialGenParam] -> ShowS #
Eq KeyMaterialGenParam Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods (==) :: KeyMaterialGenParam -> KeyMaterialGenParam -> Bool # (/=) :: KeyMaterialGenParam -> KeyMaterialGenParam -> Bool #

data Crv Source #

"crv" (Curve) Parameter

Constructors

P_256
P_384
P_521
Secp256k1

Instances

Instances details

FromJSON Crv Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods parseJSON :: Value -> Parser Crv # parseJSONList :: Value -> Parser [Crv] #
ToJSON Crv Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods toJSON :: Crv -> Value # toEncoding :: Crv -> Encoding # toJSONList :: [Crv] -> Value # toEncodingList :: [Crv] -> Encoding #
Show Crv Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods showsPrec :: Int -> Crv -> ShowS # show :: Crv -> String # showList :: [Crv] -> ShowS #
Eq Crv Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods (==) :: Crv -> Crv -> Bool # (/=) :: Crv -> Crv -> Bool #
Ord Crv Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods compare :: Crv -> Crv -> Ordering # (<) :: Crv -> Crv -> Bool # (<=) :: Crv -> Crv -> Bool # (>) :: Crv -> Crv -> Bool # (>=) :: Crv -> Crv -> Bool # max :: Crv -> Crv -> Crv # min :: Crv -> Crv -> Crv #

data OKPCrv Source #

Constructors

Ed25519
Ed448
X25519
X448

Instances

Instances details

Show OKPCrv Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods showsPrec :: Int -> OKPCrv -> ShowS # show :: OKPCrv -> String # showList :: [OKPCrv] -> ShowS #
Eq OKPCrv Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods (==) :: OKPCrv -> OKPCrv -> Bool # (/=) :: OKPCrv -> OKPCrv -> Bool #

data JWK Source #

RFC 7517 §4. JSON Web Key (JWK) Format

Instances

Instances details

FromJSON JWK Source #
Instance details Defined in Crypto.JOSE.JWK Methods parseJSON :: Value -> Parser JWK # parseJSONList :: Value -> Parser [JWK] #
ToJSON JWK Source #
Instance details Defined in Crypto.JOSE.JWK Methods toJSON :: JWK -> Value # toEncoding :: JWK -> Encoding # toJSONList :: [JWK] -> Value # toEncodingList :: [JWK] -> Encoding #
Show JWK Source #
Instance details Defined in Crypto.JOSE.JWK Methods showsPrec :: Int -> JWK -> ShowS # show :: JWK -> String # showList :: [JWK] -> ShowS #
Eq JWK Source #
Instance details Defined in Crypto.JOSE.JWK Methods (==) :: JWK -> JWK -> Bool # (/=) :: JWK -> JWK -> Bool #
AsPublicKey JWK Source #
Instance details Defined in Crypto.JOSE.JWK Methods asPublicKey :: Getter JWK (Maybe JWK) Source #
Applicative m => VerificationKeyStore m h s JWK Source #	Use a `JWK` as a `VerificationKeyStore`. Can be used with any payload type. Header and payload are ignored. No filtering is performed.
Instance details Defined in Crypto.JOSE.JWK.Store Methods getVerificationKeys :: h -> s -> JWK -> m [JWK] Source #

class AsPublicKey k where Source #

Keys that may have have public material

Methods

asPublicKey :: Getter k (Maybe k) Source #

Get the public key

Instances

Instances details

AsPublicKey ECKeyParameters Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods asPublicKey :: Getter ECKeyParameters (Maybe ECKeyParameters) Source #
AsPublicKey KeyMaterial Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods asPublicKey :: Getter KeyMaterial (Maybe KeyMaterial) Source #
AsPublicKey OKPKeyParameters Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods asPublicKey :: Getter OKPKeyParameters (Maybe OKPKeyParameters) Source #
AsPublicKey RSAKeyParameters Source #
Instance details Defined in Crypto.JOSE.JWA.JWK Methods asPublicKey :: Getter RSAKeyParameters (Maybe RSAKeyParameters) Source #
AsPublicKey JWK Source #
Instance details Defined in Crypto.JOSE.JWK Methods asPublicKey :: Getter JWK (Maybe JWK) Source #

Parts of a JWK

jwkMaterial :: Lens' JWK KeyMaterial Source #

jwkUse :: Lens' JWK (Maybe KeyUse) Source #

data KeyUse Source #

RFC 7517 §4.2. "use" (Public Key Use) Parameter

Constructors

Sig
Enc

Instances

Instances details

FromJSON KeyUse Source #
Instance details Defined in Crypto.JOSE.JWK Methods parseJSON :: Value -> Parser KeyUse # parseJSONList :: Value -> Parser [KeyUse] #
ToJSON KeyUse Source #
Instance details Defined in Crypto.JOSE.JWK Methods toJSON :: KeyUse -> Value # toEncoding :: KeyUse -> Encoding # toJSONList :: [KeyUse] -> Value # toEncodingList :: [KeyUse] -> Encoding #
Show KeyUse Source #
Instance details Defined in Crypto.JOSE.JWK Methods showsPrec :: Int -> KeyUse -> ShowS # show :: KeyUse -> String # showList :: [KeyUse] -> ShowS #
Eq KeyUse Source #
Instance details Defined in Crypto.JOSE.JWK Methods (==) :: KeyUse -> KeyUse -> Bool # (/=) :: KeyUse -> KeyUse -> Bool #
Ord KeyUse Source #
Instance details Defined in Crypto.JOSE.JWK Methods compare :: KeyUse -> KeyUse -> Ordering # (<) :: KeyUse -> KeyUse -> Bool # (<=) :: KeyUse -> KeyUse -> Bool # (>) :: KeyUse -> KeyUse -> Bool # (>=) :: KeyUse -> KeyUse -> Bool # max :: KeyUse -> KeyUse -> KeyUse # min :: KeyUse -> KeyUse -> KeyUse #

jwkKeyOps :: Lens' JWK (Maybe [KeyOp]) Source #

data KeyOp Source #

RFC 7517 §4.3. "key_ops" (Key Operations) Parameter

Constructors

Sign
Verify
Encrypt
Decrypt
WrapKey
UnwrapKey
DeriveKey
DeriveBits

Instances

Instances details

FromJSON KeyOp Source #
Instance details Defined in Crypto.JOSE.JWK Methods parseJSON :: Value -> Parser KeyOp # parseJSONList :: Value -> Parser [KeyOp] #
ToJSON KeyOp Source #
Instance details Defined in Crypto.JOSE.JWK Methods toJSON :: KeyOp -> Value # toEncoding :: KeyOp -> Encoding # toJSONList :: [KeyOp] -> Value # toEncodingList :: [KeyOp] -> Encoding #
Show KeyOp Source #
Instance details Defined in Crypto.JOSE.JWK Methods showsPrec :: Int -> KeyOp -> ShowS # show :: KeyOp -> String # showList :: [KeyOp] -> ShowS #
Eq KeyOp Source #
Instance details Defined in Crypto.JOSE.JWK Methods (==) :: KeyOp -> KeyOp -> Bool # (/=) :: KeyOp -> KeyOp -> Bool #
Ord KeyOp Source #
Instance details Defined in Crypto.JOSE.JWK Methods compare :: KeyOp -> KeyOp -> Ordering # (<) :: KeyOp -> KeyOp -> Bool # (<=) :: KeyOp -> KeyOp -> Bool # (>) :: KeyOp -> KeyOp -> Bool # (>=) :: KeyOp -> KeyOp -> Bool # max :: KeyOp -> KeyOp -> KeyOp # min :: KeyOp -> KeyOp -> KeyOp #

jwkAlg :: Lens' JWK (Maybe JWKAlg) Source #

data JWKAlg Source #

RFC 7517 §4.4. "alg" (Algorithm) Parameter

See also RFC 7518 §6.4. which states that for "oct" keys, an "alg" member SHOULD be present to identify the algorithm intended to be used with the key, unless the application uses another means or convention to determine the algorithm used.

Constructors

JWSAlg Alg
JWEAlg Alg

Instances

Instances details

FromJSON JWKAlg Source #
Instance details Defined in Crypto.JOSE.JWK Methods parseJSON :: Value -> Parser JWKAlg # parseJSONList :: Value -> Parser [JWKAlg] #
ToJSON JWKAlg Source #
Instance details Defined in Crypto.JOSE.JWK Methods toJSON :: JWKAlg -> Value # toEncoding :: JWKAlg -> Encoding # toJSONList :: [JWKAlg] -> Value # toEncodingList :: [JWKAlg] -> Encoding #
Show JWKAlg Source #
Instance details Defined in Crypto.JOSE.JWK Methods showsPrec :: Int -> JWKAlg -> ShowS # show :: JWKAlg -> String # showList :: [JWKAlg] -> ShowS #
Eq JWKAlg Source #
Instance details Defined in Crypto.JOSE.JWK Methods (==) :: JWKAlg -> JWKAlg -> Bool # (/=) :: JWKAlg -> JWKAlg -> Bool #

jwkKid :: Lens' JWK (Maybe Text) Source #

jwkX5u :: Lens' JWK (Maybe URI) Source #

jwkX5c :: Getter JWK (Maybe (NonEmpty SignedCertificate)) Source #

Get the certificate chain. Not a lens, because the key of the first certificate in the chain must correspond be the public key of the JWK. To set the certificate chain use setJWKX5c.

setJWKX5c :: Maybe (NonEmpty SignedCertificate) -> JWK -> Maybe JWK Source #

Set the "x5c" Certificate Chain parameter. If setting the list, checks that the key in the first certificate matches the JWK; returns Nothing if it does not.

jwkX5t :: Lens' JWK (Maybe Base64SHA1) Source #

jwkX5tS256 :: Lens' JWK (Maybe Base64SHA256) Source #

Converting from other key formats

fromKeyMaterial :: KeyMaterial -> JWK Source #

fromRSA :: PrivateKey -> JWK Source #

Convert RSA private key into a JWK

fromOctets :: Cons s s Word8 Word8 => s -> JWK Source #

Convert octet string into a JWK

fromX509Certificate :: (AsError e, MonadError e m) => SignedCertificate -> m JWK Source #

Convert an X.509 certificate into a JWK.

Supports RSA and ECDSA (when the curve is supported). Other key types will throw AlgorithmNotImplemented.

The "x5c" field of the resulting JWK contains the certificate.

JWK Thumbprint

thumbprint :: HashAlgorithm a => Getter JWK (Digest a) Source #

Compute the JWK Thumbprint of a JWK

digest :: HashAlgorithm a => Prism' ByteString (Digest a) Source #

Prism from ByteString to HashAlgorithm a => Digest a.

Use re digest to view the bytes of a digest

base64url :: (AsEmpty s1, AsEmpty s2, Cons s1 s1 Word8 Word8, Cons s2 s2 Word8 Word8) => Prism' s1 s2 Source #

Prism for encoding / decoding base64url.

To encode, review base64url. To decode, preview base64url.

Works with any combinations of strict/lazy ByteString.

module Crypto.Hash

JWK Set

newtype JWKSet Source #

RFC 7517 §5. JWK Set Format

Constructors

JWKSet [JWK]

Instances

Instances details

FromJSON JWKSet Source #
Instance details Defined in Crypto.JOSE.JWK Methods parseJSON :: Value -> Parser JWKSet # parseJSONList :: Value -> Parser [JWKSet] #
ToJSON JWKSet Source #
Instance details Defined in Crypto.JOSE.JWK Methods toJSON :: JWKSet -> Value # toEncoding :: JWKSet -> Encoding # toJSONList :: [JWKSet] -> Value # toEncodingList :: [JWKSet] -> Encoding #
Show JWKSet Source #
Instance details Defined in Crypto.JOSE.JWK Methods showsPrec :: Int -> JWKSet -> ShowS # show :: JWKSet -> String # showList :: [JWKSet] -> ShowS #
Eq JWKSet Source #
Instance details Defined in Crypto.JOSE.JWK Methods (==) :: JWKSet -> JWKSet -> Bool # (/=) :: JWKSet -> JWKSet -> Bool #
Applicative m => VerificationKeyStore m h s JWKSet Source #	Use a `JWKSet` as a `VerificationKeyStore`. Can be used with any payload type. Returns all keys in the set; header and payload are ignored. No filtering is performed.
Instance details Defined in Crypto.JOSE.JWK.Store Methods getVerificationKeys :: h -> s -> JWKSet -> m [JWK] Source #

checkJWK :: (MonadError e m, AsError e) => JWK -> m () Source #

Sanity-check a JWK.

Return an appropriate error if the key is size is too small to be used with any JOSE algorithm, or for other problems that mean the key cannot be used.

bestJWSAlg :: (MonadError e m, AsError e) => JWK -> m Alg Source #

Choose the cryptographically strongest JWS algorithm for a given key. The JWK "alg" algorithm parameter is ignored.

module Crypto.JOSE.JWA.JWK