AshVault.Macaroon.Chain (AshVault v0.2.0)

Copy Markdown View Source

The macaroon signature chain.

sig_0 = Vault.mac_at!(root_data(token), token.key_version, ctx)
sig_i = HMAC-SHA256(sig_{i-1}, "ashvault:macaroon:caveat:v1|" <> len64(caveat_i) <> caveat_i)
token.sig = sig_n

sig_0 is computed by the vault under the scope's :mac key — inside OpenBao for AshVault.Macs.OpenBaoTransit — and is itself bound to the scope, resource and macaroon name through the vault's associated data. Every later link is computed locally with AshVault.Macs.HmacSha256.hmac/2, keyed by the previous signature: a holder can append a caveat (extend the chain) but cannot remove one, because that would need the earlier signature, which the token does not carry.

Each link carries its own domain prefix and a 64-bit length frame, so a chain step can never collide with the vault's ashvault:mac:v1| frame or with any other HMAC an application computes, and a caveat boundary can never be re-split.

Comparison of the final signature is constant-time (:crypto.hash_equals/2).

Summary

Functions

Constant-time comparison of two signatures. false for anything not 32 bytes.

Fold caveats onto sig, in order.

The bytes the root signature covers: the prefix, envelope version, scope, key version and identity, each length-framed.

One link of the chain: the signature after appending caveat to sig.

Functions

equal?(a, b)

@spec equal?(term(), term()) :: boolean()

Constant-time comparison of two signatures. false for anything not 32 bytes.

extend(sig, caveats)

@spec extend(binary(), [binary()]) :: binary()

Fold caveats onto sig, in order.

root_data(token)

@spec root_data(AshVault.Macaroon.Envelope.t()) :: binary()

The bytes the root signature covers: the prefix, envelope version, scope, key version and identity, each length-framed.

step(sig, caveat)

@spec step(binary(), binary()) :: binary()

One link of the chain: the signature after appending caveat to sig.