Univrse.Signature (Univrse v0.2.0) View Source

A Univrse Signature is a structure attached to an Univrse.Envelope.t/0, containing a set of headers and a cryptographic signature (or MAC).

An Envelope may contain one or multiple Signature structures.

The Signature structure headers must contain an alg header and may contain a kid header, to help other parties understand what key and algorithm was used to generate the signature or MAC. Once understood, the observing party can verify the signature contained in the structure.

Link to this section Summary

Types

t()

Signature struct

Functions

sign(env, key, headers \\ %{})

Signs the Envelope payload using the given key or array of keys.

verify(envelope, keys)

Verifies the Envelope signature(s) using the given Key or list of Keys.

wrap(sig, headers \\ %{})

Wraps the given signature and headers in a new Signature struct.

Link to this section Types

t()

Specs

t() :: %Univrse.Signature{header: Univrse.Header.t(), signature: binary()}

Signature struct

Link to this section Functions

sign(env, key, headers \\ %{})

Specs

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

Signs the Envelope payload using the given key or array of keys.

A map of headers must be given including at least the signature alg value.

Where a list of keys is given, 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

Creates a signature using a single key:

Signature.sign(env, oct_key, %{"alg" => "HS256"})

Creates multiple signatures using the same algorithm:

Signature.sign(env, [oct_key, app_key], %{"alg" => "HS256"})

Creates multiple signatures using different algorithms:

Signature.sign(env, [
  oct_key,
  {ec_key_1, %{"alg" => "ES256K"}},
  {ec_key_2, %{"alg" => "ES256K"}}
], %{"alg" => "HS256"})

verify(envelope, keys)

Specs

verify(Univrse.Envelope.t(), Univrse.Key.t() | [Univrse.Key.t()]) ::
  boolean() | {:error, String.t()}

Verifies the Envelope signature(s) using the given Key or list of Keys.

wrap(sig, headers \\ %{})

Specs

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

Wraps the given signature and headers in a new Signature struct.