Univrse.Recipient (Univrse v0.2.0) View Source

A Univrse Recipient is a structure attached to an Univrse.Envelope.t/0 that helps the intended recipient(s) decrypt the encrypted payload.

An encrypted Envelope may contain one or multiple Recipient structures.

Where the Envelope is intended for a single recipient, the Recipient structure is merely a set of headers that helps the intended recipient identify what key and algorithm is needed to decrypt the payload.

Where the Envelope is intended for multiple recipients, a Recipient structure may also contain an encrypted Key. In this case, the intended recipient must decrypt the content encryption key, which they can then use to decrypt the payload.

Link to this section Summary

Types

t()

Recipient struct

Functions

decrypt(envelope_or_recipient, key, opts \\ [])

Decrypts the Envelope or Recipient, using the given encryption key.

encrypt(envelope_or_key, key, headers, opts \\ [])

Encrypts the Envelope payload using the given key or list of keys.

wrap(key, headers \\ %{})

Wraps the given key and headers in a new Recipient struct.

Link to this section Types

t()

Specs

t() :: %Univrse.Recipient{
  header: Univrse.Header.t(),
  key: binary() | Univrse.Key.t() | nil
}

Recipient struct

Link to this section Functions

decrypt(envelope_or_recipient, key, opts \\ [])

Specs

decrypt(t() | Univrse.Envelope.t(), Univrse.Key.t(), keyword()) ::
  {:ok, t() | Univrse.Envelope.t()} | {:error, any()}

Decrypts the Envelope or Recipient, using the given encryption key.

If an Envelope is being decrypted and it contains multiple recipients, it is assumed the key belongs to the first recipient. Otherwise, see Envelope.decrypt_at/4.

A keyword list of options can be given for the relevant encryption algorithm.

encrypt(envelope_or_key, key, headers, opts \\ [])

Specs

encrypt(
  Univrse.Envelope.t() | Univrse.Key.t(),
  Univrse.Key.t() | [Univrse.Key.t()] | [{Univrse.Key.t(), map()}],
  map(),
  keyword()
) :: {:ok, Univrse.Envelope.t() | t() | [t()]} | {:error, any()}

Encrypts the Envelope payload using the given key or list of keys.

A map of headersmust be given including at least the encryption alg value. A keyword list of options can be given for the relevant encryption algorithm.

Where a list of keys is given, the first key is taken as the content key and used to encrypt the payload. The content key is then encrypted by each subsequent key and included in the Recipient structs that are attached to the Envelope.

When encrypting to multiple recipients, it is possible to specify different algorithms for each key by giving a list of tuple pairs. The first element of each pair is the key and the second is a map of headers.

Examples

Encrypts for a single recipient:

Recipient.encrypt(env, aes_key, %{"alg" => "A128GCM"})

Encrypts for a multiple recipients using the same algorithm:

Recipient.encrypt(env, [aes_key, rec_key], %{"alg" => "A128GCM"})

Encrypts for a multiple recipients using different algorithms:

Recipient.encrypt(env, [
  aes_key,
  {rec1_key, %{"alg" => "ECDH-ES+A128GCM"}},
  {rec2_key, %{"alg" => "ECDH-ES+A128GCM"}}
], %{"alg" => "A128GCM"})

wrap(key, headers \\ %{})

Specs

wrap(binary() | nil, map() | Univrse.Header.t()) :: t()

Wraps the given key and headers in a new Recipient struct.