Jose.Jwe

JWE encrypted token support.

To create a JWE, you need to select two algorithms. One is an AES algorithm used to encrypt the content of your token (for example, A128GCM), for which a single-use key is generated internally. The second is used to encrypt this content-encryption key and can be either an RSA or AES-keywrap algorithm. You need to generate a suitable key to use with this, or load one from storage.

AES is much faster and creates shorter tokens, but both the encoder and decoder of the token need to have a copy of the key, which they must keep secret. With RSA anyone can send you a JWE if they have a copy of your public key.

In the example below, we show encoding and decoding using a 2048 bit RSA key pair (256 bytes). If using RSA, use one of the RSA_OAEP algorithms. RSA1_5 is deprecated due to known vulnerabilities.

>>> import Jose.Jwe
>>> import Jose.Jwa
>>> import Jose.Jwk (generateRsaKeyPair, generateSymmetricKey, KeyUse(Enc), KeyId)
>>> (kPub, kPr) <- generateRsaKeyPair 256 (KeyId "My RSA Key") Enc Nothing
>>> Right (Jwt jwt) <- jwkEncode RSA_OAEP A128GCM kPub (Claims "secret claims")
>>> Right (Jwe (hdr, claims)) <- jwkDecode kPr jwt
>>> claims
"secret claims"

Using 128-bit AES keywrap is very similar, the main difference is that we generate a 128-bit symmetric key (16 bytes):

>>> aesKey <- generateSymmetricKey 16 (KeyId "My Keywrap Key") Enc Nothing
>>> Right (Jwt jwt) <- jwkEncode A128KW A128GCM aesKey (Claims "more secret claims")
>>> Right (Jwe (hdr, claims)) <- jwkDecode aesKey jwt
>>> claims
"more secret claims"

Documentation

jwkEncode

Arguments

:: MonadRandom m

=> JweAlg

Algorithm to use for key encryption

-> Enc

Content encryption algorithm

-> Jwk

The key to use to encrypt the content key

-> Payload

The token content (claims or nested JWT)

-> m (Either JwtError Jwt)

The encoded JWE if successful

Create a JWE using a JWK. The key and algorithms must be consistent or an error will be returned.

jwkDecode :: MonadRandom m => Jwk -> ByteString -> m (Either JwtError JwtContent)

Try to decode a JWE using a JWK. If the key type does not match the content encoding algorithm, an error will be returned.

rsaEncode

Arguments

:: MonadRandom m

=> JweAlg

RSA algorithm to use (RSA_OAEP or RSA1_5)

-> Enc

Content encryption algorithm

-> PublicKey

RSA key to encrypt with

-> ByteString

The JWT claims (content)

-> m (Either JwtError Jwt)

The encoded JWE

Creates a JWE with the content key encoded using RSA.

rsaDecode

Arguments

:: MonadRandom m

=> PrivateKey

Decryption key

-> ByteString

The encoded JWE

-> m (Either JwtError Jwe)

The decoded JWT, unless an error occurs

Decrypts a JWE.