JOSEUtils.JWE (jose_utils v0.4.0) View Source

Convenience function to work with encrypted JWTs

Link to this section Summary

Types

Serialized JWE encrypted token

Functions

Decrypts a JWE encrypted token and returns the decryption key

Encrypts a payload with a JWK given an key derivation algorithm and an encryption algorithm

Returns the JOSE algorithm name from a %JOSE.JWE{} structure

Returns the JOSE encryption algorithm name from a %JOSE.JWE{} structure

Returns the unverified header

Link to this section Types

Specs

serialized() :: String.t()

Serialized JWE encrypted token

For instance:

"eyJhbGciOiJBMTI4R0NNS1ciLCJlbmMiOiJBMTI4R0NNIiwiaXYiOiJzODNFNjhPNjhsWlM5ZVprIiwidGFnIjoieF9Ea2M5dm1LMk5RQV8tU2hvTkFRdyJ9.8B2qX8fVEa-s61RsZXqkCg.J7yJ8sKLbUlzyor6.FRs.BhBwImTv9B14NwVuxmfU6A"

Link to this section Functions

Link to this function

decrypt(jwe, jwk, allowed_algs, allowed_encs)

View Source

Specs

decrypt(
  jwe :: serialized(),
  jwk_or_jwks :: JOSEUtils.JWK.t() | [JOSEUtils.JWK.t()],
  allowed_algs :: [JOSEUtils.JWA.enc_alg()],
  allowed_encs :: [JOSEUtils.JWA.enc_enc()]
) :: {:ok, {decrypted_message :: binary(), JOSEUtils.JWK.t()}} | :error

Decrypts a JWE encrypted token and returns the decryption key

It filters the keys to select only those suitable for decryption, using JOSEUtils.JWKS.decryption_keys/3. If the JWE has an identifier ("kid"), it only uses that specific key.

Example

iex> jwk_oct256 = JOSE.JWK.from_oct(<<0::256>>)
iex> jwk_oct256_map = JOSE.JWK.from_oct(<<0::256>>) |> JOSE.JWK.to_map() |> elem(1)
iex> encrypted_a256gcmkw = JOSE.JWE.block_encrypt(jwk_oct256, "{}", %{ "alg" => "A256GCMKW", "enc" => "A256GCM" }) |> JOSE.JWE.compact |> elem(1)
iex> JOSEUtils.JWE.decrypt(encrypted_a256gcmkw, jwk_oct256_map, ["A256KW"], ["A256GCM"])
:error
iex> JOSEUtils.JWE.decrypt(encrypted_a256gcmkw, jwk_oct256_map, ["A256KW", "A256GCMKW"], ["A256GCM"])
{:ok, {"{}", %{"kty" => "oct"}}}
Link to this function

encrypt(payload, jwk, alg, enc, additional_headers \\ %{})

View Source

Specs

encrypt(
  payload :: any(),
  JOSEUtils.JWK.t() | {JOSEUtils.JWK.t(), JOSEUtils.JWK.t()},
  JOSEUtils.JWA.enc_alg(),
  JOSEUtils.JWA.enc_enc(),
  header :: %{optional(String.t()) => any()}
) :: {:ok, serialized()} | {:error, Exception.t()}

Encrypts a payload with a JWK given an key derivation algorithm and an encryption algorithm

The payload can be a string, in which case it is signed directly, or any other data type which will first be converted into text using JSON serialization.

If the JWK has a key id ("kid" member), it is automatically added to the resulting JWS.

Link to this function

encrypt!(payload, jwk, alg, enc, additional_headers \\ %{})

View Source

Specs

encrypt!(
  payload :: any(),
  JOSEUtils.JWK.t() | {JOSEUtils.JWK.t(), JOSEUtils.JWK.t()},
  JOSEUtils.JWA.enc_alg(),
  JOSEUtils.JWA.enc_enc(),
  header :: %{optional(String.t()) => any()}
) :: serialized()

Specs

jose_alg(%JOSE.JWE{alg: term(), enc: term(), fields: term(), zip: term()}) ::
  JOSEUtils.JWA.enc_alg()

Returns the JOSE algorithm name from a %JOSE.JWE{} structure

iex> jwk_oct128 = JOSE.JWK.from_oct(<<0::128>>)
iex> encrypted_a128gcmkw = JOSE.JWE.block_encrypt(jwk_oct128, "{}", %{ "alg" => "A128GCMKW", "enc" => "A128GCM" }) |> JOSE.JWE.compact |> elem(1)
iex> JOSE.JWE.block_decrypt(jwk_oct128, encrypted_a128gcmkw) |> elem(1) |> JOSEUtils.JWE.jose_alg()
"A128GCMKW"

Specs

jose_enc(%JOSE.JWE{alg: term(), enc: term(), fields: term(), zip: term()}) ::
  JOSEUtils.JWA.enc_enc()

Returns the JOSE encryption algorithm name from a %JOSE.JWE{} structure

Specs

peek_header(serialized()) ::
  {:ok, %{optional(String.t()) => any()}} | {:error, Exception.t()}

Returns the unverified header

It ensures that the "alg" and "enc" mandatory parameters are present.

Examples

iex> JOSEUtils.JWE.peek_header("eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..jBt5tTa1Q0N3uFPEkf30MQ.Ei49MvTLLje7bsZ5EZCZMA.gMWOAmhZSq9ksHCZm6VSoA")
{:ok, %{"alg" => "dir", "enc" => "A128CBC-HS256"}}

iex> JOSEUtils.JWE.peek_header("this is obviously invalid")
{:error, %JOSEUtils.JWE.MalformedError{message: "malformed JWE"}}