# `AshVault.Macs.HmacSha256`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/macs/hmac_sha256.ex#L1)

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.

# `hmac`

```elixir
@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`

```elixir
@spec id() :: :hmac_sha256_v1
```

The stable id, `:hmac_sha256_v1`.

# `key_bytes`

```elixir
@spec key_bytes() :: pos_integer()
```

The key size in bytes, `32`.

# `mac`

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

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

# `verify`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
