# flare.crypto.hmac

> A module of flare_mlake's API.

HMAC-SHA256 + URL-safe base64 over the OpenSSL FFI.

The C-side wrapper (``flare/tls/ffi/openssl_wrapper.cpp``) exports
``flare_hmac_sha256`` and ``flare_hmac_sha256_verify``; the latter
uses ``CRYPTO_memcmp`` so the verify path is constant-time. Both
are reached through an ``OwnedDLHandle`` against
``libflare_tls.so`` (resolved by the same helper TLS uses).

This module is the only path through which flare touches HMAC; the
``flare.http.session`` layer composes ``hmac_sha256`` +
``base64url_*`` into ``SignedCookie`` / ``Session`` /
``SessionStore``.

## Base64 URL-safe (RFC 4648 paragraph 5)

``base64url_encode`` produces no padding; ``base64url_decode``
accepts both padded and unpadded inputs. The alphabet is
``A-Z a-z 0-9 - _``. Cookie bodies must avoid ``;`` / ``,`` / ``=``;
the no-padding URL-safe variant is the canonical choice (matches
JSON Web Signature compact serialisation).

## Functions

### `hmac_sha256`

```mojo
def hmac_sha256(key: List[UInt8], msg: List[UInt8]) -> List[UInt8]
```

Compute HMAC-SHA256(key, msg). Returns a 32-byte digest.

Args:

- `key`: Secret key bytes (any length, including empty per
     RFC 4231 vector 1).
- `msg`: Message bytes.

Raises: Error: If the underlying FFI call fails (e.g. OpenSSL
misconfiguration).

### `hmac_sha256_verify`

```mojo
def hmac_sha256_verify(key: List[UInt8], msg: List[UInt8], mac: List[UInt8]) -> Bool
```

Verify an HMAC-SHA256 tag in constant time.

Args:

- `key`: Secret key bytes.
- `msg`: Message bytes.
- `mac`: Candidate 32-byte MAC tag.

Raises: Error: If the underlying FFI call fails.

### `base64url_encode`

```mojo
def base64url_encode(data: List[UInt8]) -> String
```

Encode bytes as URL-safe base64 (no padding).

Alphabet: ``A-Za-z0-9-_``. ``+`` / ``/`` from RFC 4648 paragraph 4
are replaced by ``-`` / ``_``; trailing ``=`` padding is stripped
so the output is cookie-safe.

### `base64url_decode`

```mojo
def base64url_decode(s: String) -> List[UInt8]
```

Decode URL-safe base64 (with or without trailing ``=``).

Args:

- `s`: Encoded string. Trailing ``=`` characters are tolerated.

Raises: Error: When ``s`` contains a character outside the base64
alphabet, or its length is invalid.