Key Management
This page describes the intended design recorded in ADR#0023 (accepted) and ADR#0030 and ADR#0033 (both draft). The portable wrapping values and operation ports are implemented in trogon-key-management, with a test-support conformance harness. The standalone secrets service, backend registry and real KMS adapters described below remain implementation work. The wrapping contract defines the implemented foundation and its evidence limits.
The portable identity and adapter roadmap records the implementation inventory, wrapping backends, signing/bootstrap boundaries and proposed ADR reconciliation. It distinguishes this business KMS from SPIRE's CA key manager and OpenBao's production seal. Its work packages are proposals and do not establish adapter support.
Service topology
A platform secrets service is the only process that holds a provider client or provider credential. Callers never talk to a provider directly: they hold opaque references and resolve them through the secrets service on demand (ADR#0023 Decision 3).
Sensitive values move on one path only: authenticated, encrypted NATS core request/reply between an authorized caller and the secrets service. A DEK crosses the service boundary this way, into the service for wrap_dek and back to the caller after unwrap_dek, and never by any other route. It never enters JetStream, another durable transport, a log, or a trace (ADR#0030 Decision 2).
JetStream carries only the metadata that surrounds key material, never the material itself: rotation, revocation, and invalidation events, plus the correlation metadata recorded with a business-context audit record (ADR#0023 Decision 3 and Decision 6). Audit records states what that metadata does and does not claim about a provider's own audit log.
Ports
Business code sees two typed ports, never a generic provider interface or a provider SDK type.
SecretStore stores and resolves retrievable credentials. A caller holds a SecretRef, an opaque handle the service resolves internally to tenant, vault, and key. The value itself is retrievable, and that is the point: tokens, webhook signing secrets, and API credentials belong here.
KeyManagement performs cryptographic operations against a KeyRef with an explicit key purpose. The key material is never retrieved by a caller. This page covers only the EnvelopeWrapping capability of KeyManagement, the wrap and unwrap contract that ADR#0030 defines (ADR#0023 Decision 2).
Concepts
Dek
A Dek (data-encryption key) is generated by the authorized encryption caller from a cryptographically secure random source. The wrapping baseline uses a 32-byte Dek. Accepted ADR#0083 fixes the sealing purpose's payload cipher, nonce construction and envelope separately; this narrow port does not choose a payload format for unrelated data owners. Every application-held usable copy lives in a single-owner secret wrapper that zeroizes its buffer on every operation exit path, success, error, cancellation, or retry. A Dek is never copied into application state, a reusable cache, a log, a trace, or a durable transport.
For the sealing purpose only, accepted ADR#0083 permits a zeroizing derived data-key cache for at most sixty seconds after provider unwrap, with its invalidation and authority checks. That scoped exception does not permit ordinary wrapping callers to pre-unwrap keys for later use or retain them in general caches. The sealing service owns the two-share derivation for customer managed content; wrapping still participates in one exact backend per share.
WrappedDek
A WrappedDek is a platform-owned, versioned envelope. It contains provider ciphertext behind an adapter-private payload codec, and that ciphertext is opaque to everything outside its own adapter: no provider marker or format appears at the boundary. The data-owning subsystem persists the KeyRef, the WrappedDek, the binding version, and the payload ciphertext together, but it never parses the WrappedDek. Raw provider ciphertext carried as an opaque payload inside a WrappedDek is the only exception to the rule that provider artifacts never cross the service boundary (ADR#0030 Decision 2).
KeyRef
A KeyRef is an opaque, service-resolved reference to a key-encryption key. It is bound immutably to exactly one KeyBackendId and one native provider locator; the binding cannot change in place. A data-plane caller never selects a backend, supplies a provider resource name, or parses a KeyRef. Moving ciphertext to a different backend always creates a new KeyRef through the rewrap migration described under Operations, never a change to an existing one (ADR#0030 Decision 1 and Decision 4).
AuthenticatedBinding
An AuthenticatedBinding is a typed, versioned, deterministic, non-secret value derived from the authenticated tenant, the authoritative resource identity, the key purpose, and the binding schema version. It never derives tenant or resource identity from a caller-supplied envelope field. The identical binding is required to unwrap a Dek, which prevents a WrappedDek from being moved to a different tenant, resource, or purpose.
Each adapter maps an AuthenticatedBinding onto the provider's own authenticated-data mechanism:
- OpenBao Transit
associated_dataon a supported AEAD key type. OpenBaocontext, which controls key derivation, is not the common binding. - AWS KMS
EncryptionContext, which is case-sensitive and appears in plaintext in AWS audit logs. The binding therefore contains no secrets. - Google Cloud KMS
additionalAuthenticatedData.
(ADR#0030 Decision 2.)
KeyBackendRegistration and KeyBackendId
A KeyBackendRegistration is durable product state owned by one tenant or by the platform. It owns connection, authentication, and trust configuration for one backend, but no key locator. It has an opaque KeyBackendId, a typed provider variant, ownership, lifecycle status, admission, observed connection health, provider access parameters, and a non-secret authentication profile. Raw credentials never appear in configuration, an event, or the registration itself; an unavoidable secret is represented by a CredentialRef and stays behind SecretStore. Platform-owned registrations back the managed and dedicated tiers of ADR#0033 and follow every rule on this page. The platform may hold more than one platform-owned registration at a time, for example while it migrates its tiers to another backend. Tenant-facing projections drop the platform registration's identity, provider, and locator, so a managed key exposes no key identity and a dedicated key exposes only an opaque KeyRef (ADR#0033 Decision 3).
KeyBackendId identifies an immutable provider account, project, or OpenBao security boundary. A credential, trust root, authorization principal, or OpenBao endpoint update may create a new registration revision under the same KeyBackendId only when validation proves continuity with the same boundary and its already-bound keys. An account, project, or unproven endpoint change requires a new KeyBackendId instead. Lifecycle, admission, and health fields may change without changing identity (ADR#0030 Decision 3).
A registration's state is held in separate dimensions, and none of them stands in for another:
- Lifecycle is owned by the platform:
PendingValidation,Active, orRetired. A failed validation keeps the registration pending and records the reason. A new revision takes effect only after it validates, and the current revision stays in force until then. - Admission is controlled by the registration's owner and is authoritative:
EnabledorPaused. Only the owner may change it. See Pause and resume. - Observed connection health is advisory and is never an admission input. Its status is
Unknown,Connected, orFailed, and a failure carries a typed reason:AuthenticationFailed,AccessDenied,TlsFailure,Unreachable,Timeout,InvalidResponse, orCapabilityMissing. Health also carries the observation time, trust expiry signals, and latency observations. The provider call itself fails closed, so health never needs to block anything.
Trust expiry signals are not-after timestamps for the endpoint's server certificate, the client certificate, and the trust root, plus the credential's issued-at or expiry time when a CredentialRef is in use. A value that is not known stays absent and is never reported as zero. Warning thresholds are product policy. Expiry never blocks admission, and the TLS handshake fails closed when a certificate or trust root actually expires (ADR#0030 Decision 3).
Purpose
A key purpose is part of both resolution and binding. On wrap_dek, the service resolves a KeyRef from the authenticated tenant, the purpose, and tenant policy. On unwrap_dek and inside every AuthenticatedBinding, the purpose must match what was bound at wrap time, or the operation fails closed.
Purposes come from a catalogue declared by the data-plane services that own the wrapped payloads. A purpose names one service-owned payload kind. Secrets and platform control-plane state are never purposes, and tenant surfaces list purposes from the catalogue rather than inventing them (ADR#0033 Decision 6). Each declaration ships with the code that first wraps its payload, so the catalogue stays empty until a data-plane service adopts KeyManagement.
Operations
wrap_dek
wrap_dek(KeyRef, Dek, AuthenticatedBinding) -> WrappedDekThe service resolves the KeyRef server-side from the authenticated tenant, the purpose, and tenant policy. A caller never selects a provider or supplies a KeyRef on this path; the reference returned to the port is a service-owned argument produced after that resolution, not an authoritative caller choice (ADR#0030 Decision 1).
unwrap_dek
unwrap_dek(KeyRef, WrappedDek, AuthenticatedBinding) -> DekA caller may return the opaque KeyRef stored alongside an envelope, but the service treats it as untrusted input. It verifies that the KeyRef's bound tenant and purpose match the authenticated operation before invoking an adapter. A mismatch fails as BindingMismatch, never as a silent fallback.
BindExternalKey
An authorized control-plane operation, never a data-plane one. After a customer provisions a key in their own provider, BindExternalKey accepts one KeyBackendId, one exact native locator, the key's purpose, and its required capabilities. The service validates provider identity, access, and a complete authenticated-data round trip, then returns a new opaque KeyRef. Provider and locator selection are allowed only here, never on wrap_dek or unwrap_dek (ADR#0030 Decision 4).
The tenant that owns a customer managed binding may read back that binding's locator in the binding's detail, so it can match the binding to the key in its provider's console and audit log. The locator never appears in a wrap_dek or unwrap_dek request or response, in a projection consumed by another service or another tenant, or for a platform-owned binding (ADR#0030 Decision 1).
Rewrap migration
Moving ciphertext to another backend is an explicit migration, not a configuration cutover. It creates a new KeyRef bound to the new backend, unwraps under the old KeyRef, wraps under the new KeyRef, and commits the new reference and WrappedDek as one transactional or compare-and-set mutation against the envelope's expected version, recording a stable migration operation ID. If provider wrapping succeeds but the mutation conflicts, no partial pair is committed, and the currently committed pair remains authoritative. Both backends must be available for the duration of the migration, and there is no fallback from one backend to the other. The same flow moves a tenant between custody tiers in either direction, including from a customer managed key back to a managed or dedicated key (ADR#0033 Decision 4).
This rewrap flow applies only to a custody migration when the old key-encryption key is not compromised. A suspected compromise requires new DEKs and payload re-encryption under ADR#0023, not reuse of the existing DEKs (ADR#0030 Decision 4).
Pause and resume
The owner of a registration can pause it and resume it. A pause is a platform-side admission control that takes effect without waiting on the provider and can be reversed. It is not the customer's veto: disabling the key or revoking access in the provider remains the authoritative stop, because the customer's guarantee must not depend on the platform honoring its own flag (ADR#0030 Decision 6).
After a service instance observes that a registration is paused:
- The platform makes no provider call for it, probes included.
wrap_dek,unwrap_dek,BindExternalKey, set-as-default, migration source use, and migration target use all fail withKeyUseDeniedand the denial reasonBackendPaused. A public response may coarsen the denial like any other.
An operation against an existing KeyRef checks in a fixed order: authenticate the caller and resolve the reference, including the tenant and purpose binding check, require the registration lifecycle to be Active, check the registration's admission, apply the key-state and capability matrix in Key States, and only then call the provider. PendingValidation and Retired registrations stop before provider access even when admission is Enabled. Every retry inside the operation deadline repeats the lifecycle and admission checks before its next attempt.
BindExternalKey has no existing KeyRef to resolve. It authenticates the caller, authorizes the tenant's use of the supplied backend, locator, purpose, and capabilities, requires the registration lifecycle to be Active, checks the registration's admission, and only then performs provider validation and applies the discovered key-state and capability gates before creating the reference.
A pause is acknowledged once the admission fact is durably committed, not once every service instance has observed it. Instances enforce it through pushed invalidation of their admission view with a hard time-to-live backstop. Until a measured propagation target is published, a stale instance may admit and start a provider request after acknowledgement but before it observes the pause, and a request already in flight may complete. The no-provider-call guarantee begins when the serving instance observes the pause.
The platform never pauses a customer registration automatically from health signals. That would turn a transient provider fault into a platform-initiated denial and hide the real failure category.
An update submitted while paused is staged without validation, because validating it would call the provider. Resume validates the newest staged revision end to end, or the current revision when none is staged, so renewed trust material submitted during a pause takes effect on resume. Admission resumes, and a staged revision becomes current, only when validation succeeds; otherwise the registration stays paused on its current revision and records the validation reason. The key-state matrix still applies after a resume.
Custody tiers
KeyManagement backends are provider adapters, not customer-facing tiers. The product offers a managed key, a dedicated key, and a customer managed key. Tier is a question of who owns the backend registration and whether the key wraps one tenant or many, never which vendor implements it. See ADR#0033 and Key Custody for the full model and the reasoning behind it.
| Backend | Registration owner | Wraps | Tier |
|---|---|---|---|
| Platform-operated OpenBao Transit | Platform | Many tenants | Managed key |
| Platform-operated OpenBao Transit | Platform | One tenant | Dedicated key |
| Platform-owned AWS KMS or Google Cloud KMS key | Platform | Many tenants or one tenant | Managed key or dedicated key |
| Customer AWS KMS key | Customer | One tenant | Customer managed key |
| Customer Google Cloud KMS key | Customer | One tenant | Customer managed key |
| Customer-operated OpenBao Transit | Customer | One tenant | Customer managed key |
Failure handling
Every wrap_dek and unwrap_dek outcome maps to one of eight stable domain failure categories (ADR#0030 Decision 6). BindExternalKey has its own rejection rules, described under BindExternalKey (ADR#0030 Decision 7):
| Category | Includes | Automatic retry | Audit classification |
|---|---|---|---|
KeyUseDenied | Customer authorization denial, a disabled, destroyed, or missing key, or a paused registration (denial reason BackendPaused) | No; external customer action, or the owner's resume of a pause, must change first | Security denial |
ProviderUnavailable | Transport failure, timeout, or provider service failure | Bounded backoff within the operation deadline | Operational failure |
ProviderThrottled | Explicit provider quota or rate limit | Bounded provider-directed backoff | Capacity failure |
BindingMismatch | KeyRef tenant or purpose does not match the authenticated operation | No | Security violation |
TransportIntegrityMismatch | Provider request checksum rejection or response checksum mismatch | Limited same-provider retry; persistent mismatch is terminal | Transport integrity violation |
IntegrityFailure | Cryptographic authenticated-data or ciphertext validation fails | No | Cryptographic integrity violation |
UnsupportedCapability | The bound key lacks the requested typed capability | No | Contract rejection |
InternalFailure | Unmapped provider error, malformed response, or adapter invariant violation | No | Adapter fault |
Standing rules that hold across every category:
- The service fails closed. No wrap or unwrap succeeds without participation by the backend bound to the
KeyRef, and a failure never produces a successful degraded mode. - There is no fallback between backends, at any category, for any tenant.
- A retry never switches providers; a
ProviderUnavailableorProviderThrottledretry stays bounded and stays on the same backend. - Each provider attempt has a timeout no larger than the remaining operation deadline, and an attempt timeout maps to
ProviderUnavailable. Latency is recorded per registration and operation kind. The published per-call budget for customer backends is deferred until it is measured against real providers (ADR#0030 Decision 6). - A public response may coarsen denied, missing, and disabled outcomes to avoid giving an unauthenticated or cross-tenant caller a resource oracle, while the internal category and audit record retain the full detail.
Audit records
Each operation produces one audit record. It identifies the tenant, KeyRef, KeyBackendId, purpose, provider, outcome, and correlation ID, and it lists every provider attempt the operation made. Each attempt entry carries:
- The attempt number.
- The start time and the duration.
- The outcome category.
- The request identifier the provider returned, or an explicit absence reason:
NotProvidedByProviderwhen the provider responded without one, andNoResponsewhen the attempt received no response.
The platform never synthesizes a request identifier. A per-attempt value never enters the AuthenticatedBinding, which must be identical at wrap_dek and unwrap_dek (ADR#0030 Decision 7).
A recorded identifier is the identifier the provider returned, and nothing more is claimed for it. This page and the product surfaces describe it as joining a provider's own audit log, such as CloudTrail or an OpenBao audit device, only after a conformance case proves that join for that provider.
What the service never does
- Retain a usable, unwrapped
Dekin application state or a cache after its in-flight operation completes. - Pre-unwrap a
Dekfor later use. - Fall back to a platform key when a customer-controlled backend denies or fails.
- Let a provider artifact (a path, a token, a policy name, a ciphertext version marker, an SDK type) cross the service boundary outside the opaque payload carried inside a
WrappedDek, apart from the owner's read-back of its own customer managed binding's locator. - Accept backend or locator selection from a caller on
wrap_dekorunwrap_dek.
Open decisions
- Additional payload formats. Accepted ADR#0083 settles the sealing purpose: AES-256-GCM, random nonces, its
SealedContentenvelope and 32-byte wrapping inputs. Additional data-plane purposes need their own versioned payload formats; they cannot infer one from a provider's ciphertext representation. The generalWrappedDekadapter codec remains opaque to its data owner. - Scheduled destruction waiting period. ADR#0023 fixes that destruction of a platform-managed key is scheduled and reviewable rather than immediate, but does not fix how long the waiting period is (ADR#0023 Decision 6).
- Console and API request shapes. Neither ADR#0030 nor ADR#0033 defines console screens or API request and response shapes; both fix only the vocabulary and boundaries those surfaces must respect (ADR#0033 Non-Goals).
- Multi-Region replica sets. Whether a
KeyRefmay model an explicit, customer-approved replica set of a multi-Region AWS key is undecided. Until it is, each replica is a separateKeyRefand the platform never fails over between them (ADR#0030 Open Questions). - Private connectivity. How private connectivity to a customer endpoint is provided is undecided. Any private path must be operator-provisioned and declared per registration, never a free-form customer-supplied private address (ADR#0030 Open Questions).
- Measured numbers. The pause enforcement target and the published per-call latency budget for customer backends are recorded after measurement against real providers (ADR#0030 Decision 6).
