Skip to main content

​
BYOK: register, activate, rotate, and revoke customer-managed keys

Bring Your Own Key (BYOK) is Orbit’s key-management control plane for compliance evidence: it records which encryption key — held in your external KMS — governs your organization’s key-management posture, and lets you prove and revoke that posture at will. This guide walks the full lifecycle from the dashboard, step by step. The Customer-Managed Keys page lives at Settings → Compliance → Customer-Managed Keys and is guarded to owner and admin roles. The full endpoint surface, provider-by-provider reference formats, and error-code tables are in the BYOK reference; this page is the walkthrough.
Every step here is a tenant-owned control: you pick the key, you grant and revoke access in your own KMS, and you register the posture for evidence. No step is gated or mandated by the platform — and no step weakens the platform-managed encryption that always protects tenant data at rest.

​
1. The BYOK model: your KMS, no key material in Orbit

BYOK supports four providers, each validated against its canonical reference format: Three properties define the model:
  • No key material ever leaves your KMS. Orbit stores only the key reference and its fingerprint. Read views echo back a truncated fingerprint — never the raw ARN or vault path — so a lower-privileged viewer can’t see the exact location of your key.
  • This surface makes no KMS network call. Registration is a control-plane recording: Orbit validates the reference’s shape and fingerprints it, but the custody of the key itself stays with you, inside your own KMS boundary.
  • Platform-managed encryption stays authoritative. Tenant data at rest is protected by Orbit’s encrypt-everything envelope regardless of your BYOK config’s state. Registration and enforcement record your compliance posture; they do not re-encrypt tenant data under your key. Do not read an active, enforced config as “tenant data is encrypted under my key.”
A key moves through one state machine, and every transition writes an audit-log entry:

​
2. Register a key

Open Settings → Compliance → Customer-Managed Keys → Register a customer-managed key. You need the owner or admin role.
  1. KMS provider — pick the provider that holds the key. The reference-format hint below the input updates to match.
  2. Key reference — paste the canonical identifier (ARN, resource name, vault URL, or transit path). The server validates it against the provider’s grammar; a malformed reference is refused with 409 BYOK_INVALID_KEY_REFERENCE.
  3. Key alias (optional) — a human-readable label shown wherever the fingerprint would be cryptic.
  4. Justification (optional) — free text recorded with the registration; use it to cite the policy or clause that requires customer-managed keys (e.g. a security addendum).
Select Register key. The key lands in pending state with one audit-log entry.
Registering replaces the recorded posture for the whole organization. Register is only available when no key exists or the previous key was revoked — while a key is pending or active, the register card is hidden and the action is refused.

​
3. Activate, and what enforcement records

From pending, the page asks two things of you before activation:
  1. Grant Orbit’s service identity decrypt access on the key in your KMS (a key policy statement in AWS, a CryptoKey IAM binding in Google Cloud, an access policy in Azure, a Vault policy in HashiCorp). The key stays pending until your side of the access grant exists.
  2. Activate — with the optional Enforce immediately checkbox.
The enforcement checkbox records this key as your organization’s governing key-management policy for compliance evidence:
  • It does not re-encrypt tenant data — the platform envelope stays authoritative, as above.
  • While enforcement is on, platform field-encryption calls that consult BYOK fail closed with 409 BYOK_KEY_UNAVAILABLE when the key is revoked, unprovisioned, or its wrapped key is unrecoverable. They never fall back silently to the platform key when your recorded policy says a customer key must govern.
  • Enforcement is cleared by revocation — that is the deliberate exit ramp, and it’s irreversible (see Section 4).
Activate without enforcement to keep the registration advisory; you can rotate or revoke either way. Every activation writes an audit entry with the fingerprint and the enforcement flag.

​
4. Rotate with zero downtime — and revoke deliberately

​
Rotate

From pending or active, select Rotate key and submit a new reference in the same form as registration. Rotation is a control-plane re-wrap, not a data migration:
  • An active key stays active and its enforcement is preserved — no re-registration, no downtime window.
  • The rotation count increments for provenance, so your audit trail shows each replacement as a first-class event.
  • For an enforced key, the internal data-encryption key is unwrapped under the old reference and re-wrapped under the new one in the same operation. If the old wrapped key cannot be recovered, the rotation is refused with 409 BYOK_REWRAP_FAILED rather than silently dropping enforcement — fix the reference and retry, or revoke and re-register as below.

​
Revoke

Revoke is the deliberate off-boarding step — contract termination, a security addendum lapsing, or a key retirement policy:
  1. Select Revoke key, optionally record a justification (e.g. the termination clause), and confirm in the destructive-action dialog.
  2. Revocation clears the key from your recorded enforcement policy and destroys the wrapped data-encryption key, so it can never be unwrapped again. This confirmation step is intentional — re-enabling BYOK after revocation means registering a fresh key.
  3. Revoking does not re-encrypt or crypto-shred tenant data. Platform-managed encryption is the system of record for tenant data throughout, so no stored field becomes unreadable.
Revoking an already-revoked key returns 409 BYOK_ALREADY_REVOKED. To re-enable BYOK after a revoke, register a fresh key from Section 2.

​
5. Operations: health, failure modes, and the audit tie

Monitor key health. The config card shows the provider, alias, fingerprint, enforcement flag, rotation count, and the registered / activated / last-rotated timestamps, refreshed every 60 seconds — a sister tab’s change lands on yours without a manual reload. GET /compliance/byok returns the same picture for automation: the config, the provider catalog, and the resolved posture. Failure modes when the KMS is unreachable. This surface never calls out to your KMS, so a KMS outage cannot block registration or the dashboard. The failure modes live at the boundaries:
  • If Orbit’s service identity loses decrypt access on the key (a revoked grant, a deleted key version, a suspended KMS account), pending registration and rotation still work — but an enforced key’s fail-closed seam refuses with 409 BYOK_KEY_UNAVAILABLE, and an active key’s re-wrap on rotation refuses with 409 BYOK_REWRAP_FAILED. Restore the grant in your KMS, then retry the operation that failed.
  • A malformed or abandoned reference (deleted key in a recycled ARN region, a retired vault path) fails loudly at register or rotate time with 409 BYOK_INVALID_KEY_REFERENCE on the shape, or at re-wrap time against the old fingerprint.
  • Enforcement refusing with a retryable failure means the recorded policy still stands; revocation is the only exit that clears it, and that too writes an audit entry.
Audit trail. Every register, activate, rotate, and revoke writes an audit-log entry with the provider, the fingerprint, the enforcement flag, and (for revokes) your justification. Filter Settings → Audit log by the key’s fingerprint to reconstruct the full lifecycle — see the audit log guide for filtering and export. For SOC 2 or ISO 27001 evidence, point auditors at that trail and cite the resolved BYOK posture in your evidence binder.

​
See also