Crypto.JOSE.JWK

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

JWK generation

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

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

data KeyMaterialGenParam

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

Show KeyMaterialGenParam

Defined in Crypto.JOSE.JWA.JWK

Methods

showsPrec :: Int -> KeyMaterialGenParam -> ShowS

show :: KeyMaterialGenParam -> String

showList :: [KeyMaterialGenParam] -> ShowS

Eq KeyMaterialGenParam

Defined in Crypto.JOSE.JWA.JWK

Methods

(==) :: KeyMaterialGenParam -> KeyMaterialGenParam -> Bool

(/=) :: KeyMaterialGenParam -> KeyMaterialGenParam -> Bool

data Crv

"crv" (Curve) Parameter

Constructors

P_256

P_384

P_521

Secp256k1

Instances

FromJSON Crv

Defined in Crypto.JOSE.JWA.JWK

Methods

parseJSON :: Value -> Parser Crv

parseJSONList :: Value -> Parser [Crv]

ToJSON Crv

Defined in Crypto.JOSE.JWA.JWK

Methods

toJSON :: Crv -> Value

toEncoding :: Crv -> Encoding

toJSONList :: [Crv] -> Value

toEncodingList :: [Crv] -> Encoding

Show Crv

Defined in Crypto.JOSE.JWA.JWK

Methods

showsPrec :: Int -> Crv -> ShowS

show :: Crv -> String

showList :: [Crv] -> ShowS

Eq Crv

Defined in Crypto.JOSE.JWA.JWK

Methods

(==) :: Crv -> Crv -> Bool

(/=) :: Crv -> Crv -> Bool

Ord Crv

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

Constructors

Ed25519

Ed448

X25519

X448

Instances

Show OKPCrv

Defined in Crypto.JOSE.JWA.JWK

Methods

showsPrec :: Int -> OKPCrv -> ShowS

show :: OKPCrv -> String

showList :: [OKPCrv] -> ShowS

Eq OKPCrv

Defined in Crypto.JOSE.JWA.JWK

Methods

(==) :: OKPCrv -> OKPCrv -> Bool

(/=) :: OKPCrv -> OKPCrv -> Bool

data JWK

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

Instances

FromJSON JWK

Defined in Crypto.JOSE.JWK

Methods

parseJSON :: Value -> Parser JWK

parseJSONList :: Value -> Parser [JWK]

ToJSON JWK

Defined in Crypto.JOSE.JWK

Methods

toJSON :: JWK -> Value

toEncoding :: JWK -> Encoding

toJSONList :: [JWK] -> Value

toEncodingList :: [JWK] -> Encoding

Show JWK

Defined in Crypto.JOSE.JWK

Methods

showsPrec :: Int -> JWK -> ShowS

show :: JWK -> String

showList :: [JWK] -> ShowS

Eq JWK

Defined in Crypto.JOSE.JWK

Methods

(==) :: JWK -> JWK -> Bool

(/=) :: JWK -> JWK -> Bool

AsPublicKey JWK

Defined in Crypto.JOSE.JWK

Methods

asPublicKey :: Getter JWK (Maybe JWK)

Applicative m => VerificationKeyStore m h s JWK

Use a JWK as a VerificationKeyStore. Can be used with any payload type. Header and payload are ignored. No filtering is performed.

Defined in Crypto.JOSE.JWK.Store

Methods

getVerificationKeys :: h -> s -> JWK -> m [JWK]

class AsPublicKey k where

Keys that may have have public material

Methods

asPublicKey :: Getter k (Maybe k)

Get the public key

Instances

AsPublicKey ECKeyParameters

Defined in Crypto.JOSE.JWA.JWK

Methods

asPublicKey :: Getter ECKeyParameters (Maybe ECKeyParameters)

AsPublicKey KeyMaterial

Defined in Crypto.JOSE.JWA.JWK

Methods

asPublicKey :: Getter KeyMaterial (Maybe KeyMaterial)

AsPublicKey OKPKeyParameters

Defined in Crypto.JOSE.JWA.JWK

Methods

asPublicKey :: Getter OKPKeyParameters (Maybe OKPKeyParameters)

AsPublicKey RSAKeyParameters

Defined in Crypto.JOSE.JWA.JWK

Methods

asPublicKey :: Getter RSAKeyParameters (Maybe RSAKeyParameters)

AsPublicKey JWK

Defined in Crypto.JOSE.JWK

Methods

asPublicKey :: Getter JWK (Maybe JWK)

Parts of a JWK

jwkMaterial :: Lens' JWK KeyMaterial

jwkUse :: Lens' JWK (Maybe KeyUse)

data KeyUse

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

Constructors

Sig

Enc

Instances

FromJSON KeyUse

Defined in Crypto.JOSE.JWK

Methods

parseJSON :: Value -> Parser KeyUse

parseJSONList :: Value -> Parser [KeyUse]

ToJSON KeyUse

Defined in Crypto.JOSE.JWK

Methods

toJSON :: KeyUse -> Value

toEncoding :: KeyUse -> Encoding

toJSONList :: [KeyUse] -> Value

toEncodingList :: [KeyUse] -> Encoding

Show KeyUse

Defined in Crypto.JOSE.JWK

Methods

showsPrec :: Int -> KeyUse -> ShowS

show :: KeyUse -> String

showList :: [KeyUse] -> ShowS

Eq KeyUse

Defined in Crypto.JOSE.JWK

Methods

(==) :: KeyUse -> KeyUse -> Bool

(/=) :: KeyUse -> KeyUse -> Bool

Ord KeyUse

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])

data KeyOp

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

Constructors

Sign

Verify

Encrypt

Decrypt

WrapKey

UnwrapKey

DeriveKey

DeriveBits

Instances

FromJSON KeyOp

Defined in Crypto.JOSE.JWK

Methods

parseJSON :: Value -> Parser KeyOp

parseJSONList :: Value -> Parser [KeyOp]

ToJSON KeyOp

Defined in Crypto.JOSE.JWK

Methods

toJSON :: KeyOp -> Value

toEncoding :: KeyOp -> Encoding

toJSONList :: [KeyOp] -> Value

toEncodingList :: [KeyOp] -> Encoding

Show KeyOp

Defined in Crypto.JOSE.JWK

Methods

showsPrec :: Int -> KeyOp -> ShowS

show :: KeyOp -> String

showList :: [KeyOp] -> ShowS

Eq KeyOp

Defined in Crypto.JOSE.JWK

Methods

(==) :: KeyOp -> KeyOp -> Bool

(/=) :: KeyOp -> KeyOp -> Bool

Ord KeyOp

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)

data JWKAlg

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

FromJSON JWKAlg

Defined in Crypto.JOSE.JWK

Methods

parseJSON :: Value -> Parser JWKAlg

parseJSONList :: Value -> Parser [JWKAlg]

ToJSON JWKAlg

Defined in Crypto.JOSE.JWK

Methods

toJSON :: JWKAlg -> Value

toEncoding :: JWKAlg -> Encoding

toJSONList :: [JWKAlg] -> Value

toEncodingList :: [JWKAlg] -> Encoding

Show JWKAlg

Defined in Crypto.JOSE.JWK

Methods

showsPrec :: Int -> JWKAlg -> ShowS

show :: JWKAlg -> String

showList :: [JWKAlg] -> ShowS

Eq JWKAlg

Defined in Crypto.JOSE.JWK

Methods

(==) :: JWKAlg -> JWKAlg -> Bool

(/=) :: JWKAlg -> JWKAlg -> Bool

jwkKid :: Lens' JWK (Maybe Text)

jwkX5u :: Lens' JWK (Maybe URI)

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

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

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)

jwkX5tS256 :: Lens' JWK (Maybe Base64SHA256)

Converting from other key formats

fromKeyMaterial :: KeyMaterial -> JWK

fromRSA :: PrivateKey -> JWK

Convert RSA private key into a JWK

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

Convert octet string into a JWK

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

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)

Compute the JWK Thumbprint of a JWK

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

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

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

RFC 7517 §5. JWK Set Format

Constructors

JWKSet [JWK]

Instances

FromJSON JWKSet

Defined in Crypto.JOSE.JWK

Methods

parseJSON :: Value -> Parser JWKSet

parseJSONList :: Value -> Parser [JWKSet]

ToJSON JWKSet

Defined in Crypto.JOSE.JWK

Methods

toJSON :: JWKSet -> Value

toEncoding :: JWKSet -> Encoding

toJSONList :: [JWKSet] -> Value

toEncodingList :: [JWKSet] -> Encoding

Show JWKSet

Defined in Crypto.JOSE.JWK

Methods

showsPrec :: Int -> JWKSet -> ShowS

show :: JWKSet -> String

showList :: [JWKSet] -> ShowS

Eq JWKSet

Defined in Crypto.JOSE.JWK

Methods

(==) :: JWKSet -> JWKSet -> Bool

(/=) :: JWKSet -> JWKSet -> Bool

Applicative m => VerificationKeyStore m h s JWKSet

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.

Defined in Crypto.JOSE.JWK.Store

Methods

getVerificationKeys :: h -> s -> JWKSet -> m [JWK]

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

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

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

module Crypto.JOSE.JWA.JWK