jose_utils v0.3.0 JOSEUtils.JWE 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

Link to this type

serialized()

View Source
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
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
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.

Notice that additional headers from the JWK or the additional_headers parameters are not serialized into the result JWE, because of lack of support by the underlying library.

Link to this function

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

View Source
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()
Link to this function

jose_alg(jwe)

View Source
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"
Link to this function

jose_enc(jwe)

View Source
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

Link to this function

peek_header(jwe)

View Source
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"}}