AshVault.Macs.HmacSha256 (AshVault v0.2.0)

Copy Markdown View Source

HMAC-SHA256 computed in process, over a raw 32-byte :mac key.

The default AshVault.Mac for every vault whose cipher is not AshVault.Ciphers.OpenBaoTransit.

The tag is HMAC-SHA256(key, AshVault.Mac.frame(data, aad)): 32 raw bytes. hmac/2 is the bare primitive, exposed so it can be checked against the RFC 4231 vectors directly.

verify/4 recomputes the tag and compares it with :crypto.hash_equals/2, which is constant-time in the contents. A tag of the wrong length is refused before the comparison — :crypto.hash_equals/2 raises on unequal lengths, and the length of a valid tag is public anyway.

An opaque AshVault.Key handle is refused with {:error, :opaque_key_unsupported}: there are no bytes here to HMAC with, and no fallback is ever taken.

Summary

Functions

The bare HMAC-SHA256 primitive, with no framing.

The stable id, :hmac_sha256_v1.

The key size in bytes, 32.

The 32-byte tag over AshVault.Mac.frame(data, aad) under key.

Verify a tag in constant time. {:error, :invalid_tag} for anything that does not verify, including a tag of the wrong length or type.

Functions

hmac(key, message)

@spec hmac(binary(), binary()) :: binary()

The bare HMAC-SHA256 primitive, with no framing.

Examples

iex> AshVault.Macs.HmacSha256.hmac("key", "The quick brown fox jumps over the lazy dog")
...> |> Base.encode16(case: :lower)
"f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8"

id()

@spec id() :: :hmac_sha256_v1

The stable id, :hmac_sha256_v1.

key_bytes()

@spec key_bytes() :: pos_integer()

The key size in bytes, 32.

mac(data, key, aad)

@spec mac(binary(), AshVault.Key.t(), binary()) :: {:ok, binary()} | {:error, term()}

The 32-byte tag over AshVault.Mac.frame(data, aad) under key.

verify(data, tag, key, aad)

@spec verify(binary(), binary(), AshVault.Key.t(), binary()) ::
  :ok | {:error, :invalid_tag} | {:error, term()}

Verify a tag in constant time. {:error, :invalid_tag} for anything that does not verify, including a tag of the wrong length or type.