Skip to content

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_data on a supported AEAD key type. OpenBao context, 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, or Retired. 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: Enabled or Paused. 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, or Failed, and a failure carries a typed reason: AuthenticationFailed, AccessDenied, TlsFailure, Unreachable, Timeout, InvalidResponse, or CapabilityMissing. 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 ​

text
wrap_dek(KeyRef, Dek, AuthenticatedBinding) -> WrappedDek

The 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 ​

text
unwrap_dek(KeyRef, WrappedDek, AuthenticatedBinding) -> Dek

A 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 with KeyUseDenied and the denial reason BackendPaused. 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.

BackendRegistration ownerWrapsTier
Platform-operated OpenBao TransitPlatformMany tenantsManaged key
Platform-operated OpenBao TransitPlatformOne tenantDedicated key
Platform-owned AWS KMS or Google Cloud KMS keyPlatformMany tenants or one tenantManaged key or dedicated key
Customer AWS KMS keyCustomerOne tenantCustomer managed key
Customer Google Cloud KMS keyCustomerOne tenantCustomer managed key
Customer-operated OpenBao TransitCustomerOne tenantCustomer 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):

CategoryIncludesAutomatic retryAudit classification
KeyUseDeniedCustomer 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 firstSecurity denial
ProviderUnavailableTransport failure, timeout, or provider service failureBounded backoff within the operation deadlineOperational failure
ProviderThrottledExplicit provider quota or rate limitBounded provider-directed backoffCapacity failure
BindingMismatchKeyRef tenant or purpose does not match the authenticated operationNoSecurity violation
TransportIntegrityMismatchProvider request checksum rejection or response checksum mismatchLimited same-provider retry; persistent mismatch is terminalTransport integrity violation
IntegrityFailureCryptographic authenticated-data or ciphertext validation failsNoCryptographic integrity violation
UnsupportedCapabilityThe bound key lacks the requested typed capabilityNoContract rejection
InternalFailureUnmapped provider error, malformed response, or adapter invariant violationNoAdapter 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 ProviderUnavailable or ProviderThrottled retry 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: NotProvidedByProvider when the provider responded without one, and NoResponse when 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 Dek in application state or a cache after its in-flight operation completes.
  • Pre-unwrap a Dek for 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_dek or unwrap_dek.

Open decisions ​

  • Additional payload formats. Accepted ADR#0083 settles the sealing purpose: AES-256-GCM, random nonces, its SealedContent envelope 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 general WrappedDek adapter 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 KeyRef may model an explicit, customer-approved replica set of a multi-Region AWS key is undecided. Until it is, each replica is a separate KeyRef and 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).

See also ​

Released under the Apache License 2.0.