Repository navigation
[Bug] HMAC-SHA256 baseline needs defined key distribution, rotation, and per-session derivation #11
Description
Surfaced during the v0.1.0 review (PR #2). Closely tied to the conformance-baseline conversation in that PR. Filing separately so we can track the crypto details independently.
specification.md §10.1 lists HMAC-SHA256 as the RECOMMENDED default with no key distribution mechanism, no rotation rule, and no per-session derivation. key_id is just an opaque resolver.
The failure mode: reference implementations and copy-paste deployments will use a single hardcoded shared secret per Guardian fleet, since that's the path of least resistance the spec endorses. One Observed Agent compromise lets the attacker mint valid HMACs for every session in the fleet. There's no revocation path, so the only remediation is fleet-wide secret rotation with no protocol-defined mechanism for it.
Proposed direction:
- Per-session HKDF-derived key from a handshake-established secret, so a single session compromise doesn't burn the whole fleet
- Defined
key_idresolution flow including a minimum rotation policy in the normative text - Optional revocation method, could be as simple as
revoked_key_idsin subsequent handshakes
Why deferred from v0.1.0: depends on the resolution of the broader Core-baseline conversation in PR #2. If we land minimum-signing in Core, this becomes part of that work. If we don't, this lives as a SHOULD in ACS-Crypto.
References: specification.md §10.1, §10.2, request-envelope.json Signature object
Activity
rocklambros commentedon Jun 16, 2026
Adapter-side data point from #22, related but a step earlier than this issue.
The reference adapters don't sign the envelope at all. No HMAC on the way out, and the example Guardian doesn't verify a signature or check for replays. This issue is about key distribution and rotation once signing is happening. The reference skips signing entirely and leans on transport (
conformance.md:28makes the baseline signature a Core MUST, and:67says transport doesn't satisfy it).Why it belongs next to this issue: whatever key-derivation mechanism lands here (the per-session HKDF direction you sketched) has to show up in the reference adapter, or copy-paste deployments inherit an unauthenticated channel and never add signing back. The single-shared-secret failure mode you flagged is the exact thing a no-signing reference pushes people toward, since dropping in one hardcoded secret later is the path of least resistance.
Cross-linked from #22.
Fix all 12 edge cases from post-PR audit
rocklambros commentedon Sep 10, 2026
Triage note, ahead of the OWASP relaunch. This is now labelled
scope:deferred, which means tracked and scheduled rather than rejected. The project has published a Current Priority Scope committing the next ninety days to one outcome, a runnable Guardian reference implementation benchmarked against Microsoft AGT. Work that does not feed that outcome lands in the v0.2.0 window instead of being closed.Key distribution, rotation, and per-session derivation for the HMAC baseline are real gaps, and they are deferred as a set with the other crypto items rather than piecemeal. The reference implementation will exercise the baseline with a deployment-supplied key, which is exactly the arrangement this issue says is underspecified.
Nothing here needs re-filing. It stays open, keeps its labels, and moves to the backlog when the v0.2.0 window opens. If you think it belongs in the ninety-day window instead, say so on this thread and a maintainer will re-scope it.
[-]HMAC-SHA256 baseline needs defined key distribution, rotation, and per-session derivation[/-][+][Bug] HMAC-SHA256 baseline needs defined key distribution, rotation, and per-session derivation[/+]