Skip to content

[Proposal] Bind an HMAC key_id to the agent_id it may sign for #306

Open
Open
[Proposal] Bind an HMAC key_id to the agent_id it may sign for#306
Labels
status:needs-triageNot yet triaged. Applied by the issue formstype:proposalNew feature or requestworkstream:specOwning workstream. Maintainers only

Description

@rocklambros
rocklambros
opened on Oct 20, 2026

Part of issue #118. Raised in the PR #272 review.

The problem

PR #272 defines HMAC key_id as "an opaque label, chosen by the deployment, that names one configured secret", and a verifier rejects an unknown one. Nothing ties a key_id to metadata.agent_id.

In a deployment where several agents share one secret (the simplest setup, and the one most people will copy), any agent can sign a request claiming to be any other agent_id. It can also derive another agent's session key from a session_id, which appears in traces. Per-agent policy keyed on agent_id is then a claim, not an authenticated identity.

Issue #11 covers key distribution and revocation more broadly. This issue is only the binding question.

Decision needed

  1. Should a Guardian resolve key_id only among the secrets configured for the request's agent_id (and tenant_id when present), treating any other as unknown?
  2. Should the spec RECOMMEND one secret per agent, and say plainly that under a shared secret agent_id is unauthenticated?
  3. Should agent_id go into the HKDF info too? That would change the derivation PR Fix the HMAC key derivation, define key_id, and record an unresolved request_id_ref #272 just pinned, so it needs to be decided before more implementations ship.

Constituencies

Guardian implementers, enterprise deployers, policy authors.

Activity

  1. rocklambros
    added
    type:proposalNew feature or request
    status:needs-triageNot yet triaged. Applied by the issue forms
    workstream:specOwning workstream. Maintainers only
    on Oct 20, 2026
  2. github-project-automation
    added this to ACS Project Trackeron Oct 20, 2026
  3. github-project-automation
    moved this to Needs triage in ACS Project Trackeron Oct 20, 2026

  4. bar-capsule commented on Oct 28, 2026

    @bar-capsule
    bar-capsule
    on Oct 28, 2026
    Collaborator

    Yes to 1 and 2, no to 3.

    • Each credential is configured with the agent (and tenant) identities it may sign for, and the Guardian rejects it for anything else.
    • Recommend separate secrets for agents that need isolation, and say plainly that a shared secret proves membership in the group holding it, not which member signed. Two key_id labels pointing to the same secret don't isolate anything either.
    • Keep the HKDF derivation from Fix the HMAC key derivation, define key_id, and record an unresolved request_id_ref #272 as it is. Adding agent_id to info doesn't stop impersonation: anyone holding the shared secret can still compute another agent's key.

    One option worth spelling out: the Guardian holds one master secret, and each agent gets its own secret derived from it with agent_id (HKDF(master, agent_id)), without ever seeing the master. The Guardian derives the expected secret from the agent_id a request claims, so signing as another agent fails on its own, with no lookup table. That gives per-agent isolation with one secret to manage, and leaves the #272 session-key derivation unchanged. Proving to a third party which agent signed still needs ACS-Crypto.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    status:needs-triageNot yet triaged. Applied by the issue formstype:proposalNew feature or requestworkstream:specOwning workstream. Maintainers only

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions