Kibo BYOK
Bring Your Own Key is the third rung on the custody ladder. The customer holds the Customer Encryption Key (CEK) in their own cloud KMS (AWS KMS, GCP Cloud KMS, Azure Key Vault, or HashiCorp Vault Transit); Kibo wraps Data Encryption Keys (DEKs) under that CEK and stores the wrapped ciphertext. The plaintext CEK never enters Kibo's address space at any point — every wrap and unwrap is a call to the customer's KMS, invoked over an attested channel.
The customer's KMS becomes the structural root of trust for the project's encrypted data: if the customer revokes the CEK, the project's data becomes cryptographically inaccessible — including to Kilimanjaro.
1. Supported providers
| Provider | KMS / HSM endpoint | Notable mechanics |
|---|---|---|
| AWS KMS | kms.amazonaws.com — symmetric CMK (AES-256-GCM) or asymmetric CMK (RSA / ECC) | Automatic key rotation; CloudTrail event subscription for rotation notifications |
| GCP Cloud KMS | cloudkms.googleapis.com — symmetric or asymmetric key | cryptoKeys.encrypt / decrypt; Pub/Sub notifications via Cloud Audit Logs |
| Azure Key Vault | *.vault.azure.net — software- or HSM-protected key | wrapKey / unwrapKey; Event Grid notifications via Microsoft.KeyVault.KeyNewVersionCreated |
| HashiCorp Vault (Transit) | Your Vault URL, transit mount path and key name (optional namespace) | Transit encrypt / decrypt; token authentication at launch (AppRole and JWT are refused) |
The wire contract is normalised across providers — the SDK call is identical. Provider-specific differences (rotation event delivery, key-version metadata format, authentication mechanism) are handled in Kibo's KMS adapter layer.
2. Provisioning
The customer prepares the CEK in their KMS before attaching it to Kibo:
- Create the CMK / key in the chosen KMS, configured for the algorithm Kibo expects (typically AES-256-GCM for symmetric, RSA-4096 or P-384 for asymmetric).
- Grant Kibo's workload identity the minimum required permissions:
| Permission | Why Kibo needs it |
|---|---|
Encrypt / WrapKey | Wrap a freshly generated plaintext DEK |
Decrypt / UnwrapKey | Unwrap a stored ciphertext DEK on demand, including during re-wrap on rotation |
GenerateDataKey, DescribeKey (or equivalent) | Attachment-time validation only: read key metadata and check state, capabilities and region |
The concrete grants are:
| Provider | Grant |
|---|---|
| AWS KMS | kms:Encrypt, kms:Decrypt, kms:GenerateDataKey, kms:DescribeKey |
| GCP Cloud KMS | roles/cloudkms.cryptoKeyEncrypterDecrypter and roles/cloudkms.viewer, on the key |
| Azure Key Vault | wrapKey and unwrapKey on the key |
Notably absent: CreateKey, ScheduleKeyDeletion, EnableKeyRotation, DisableKey. Kibo cannot create CEKs, cannot delete them, cannot enable or disable rotation, and cannot rotate them. The customer retains exclusive control over the CEK lifecycle.
- Attach the CEK to a Kibo project through the Console's custody workflow in Vault mode. The attachment requires the KMS endpoint, the key identifier, and the role, service account or application you have named for Kibo to use; Kibo performs an attachment-time validation against the customer's KMS — a probe that exercises the wrap, unwrap, and key-state surfaces — and rejects the attachment if any step fails.
Trust binding. Every customer's grant trusts the same Kibo principal, so each grant is bound to your project to stop another project from naming your role or key. Kibo issues each project a read-only, opaque externalId, shown in the Console and returned by the attach API. On AWS, your role's trust policy requires it as sts:ExternalId and Kibo always sends it. On GCP and Azure, your workload identity federation provider or federated credential is bound to your project's subject, k9o:project:<project id>, issued by Kibo's per-region OIDC issuer. Attachment validation refuses the attach if the grant can be used without the binding. HashiCorp Vault has no equivalent, because its credential is your own token.
3. The attestation path
The customer's KMS proves Kibo never touched the plaintext CEK. Every cloud KMS issues an audit log of operations performed against the CMK; the customer's KMS audit log shows:
- The operation invoked (
Encrypt,Decrypt) - The calling principal (Kibo's workload identity)
- The CMK / key version used
- The timestamp
What it does not show — and could not show, because it does not happen — is an ExportKey, a GetKeyMaterial, or any other operation that would have surfaced plaintext key material from the KMS HSM. The KMS HSM enforces this structurally; Kibo cannot invoke an export operation if the CMK is configured with Origin = AWS_KMS (AWS), protectionLevel = HSM (GCP), or keyOps excluding decrypt of the raw key bytes (Azure).
The combination of (a) the KMS audit log + (b) the CMK's HSM-only configuration + (c) the structural absence of export operations is the customer-side proof that Kibo's wrapped-DEK records cannot be decrypted by anyone except a principal holding Decrypt permission on the CMK.
4. Decoupled lifecycle engineering
A foundational design property: routine CEK rotation does not trigger raw data-plane re-encryption. The cost profile is deliberately asymmetric.
| Operation | Cost | Frequency |
|---|---|---|
| CEK re-wrap | One KMS decrypt and one KMS encrypt per active wrapped DEK; no data movement | Every CEK rotation event (customer-initiated or scheduled) |
| DEK rotation + data re-encryption | Full scan and re-encryption of every record protected by the DEK; bounded by storage size and I/O throughput | Only on suspected DEK compromise, regulatory mandate, or scheduled cryptoperiod expiry |
Re-wrapping a DEK changes the wrapping envelope (ciphertext(DEK, CEK_version_N) → ciphertext(DEK, CEK_version_N+1)); the plaintext DEK is unchanged. The data ciphertext is unchanged. Each DEK is unwrapped under the old CEK version and wrapped under the new one (§5); the plaintext CEK never leaves your KMS.
DEK rotation — generating a new DEK and re-encrypting the underlying data — is a fundamentally different operation. It is not triggered by CEK rotation; it is triggered by evidence of DEK exposure (a Kibo enclave compromise, a confirmed CEK compromise where the attacker may have already captured wrapped DEKs, or a compliance regime that mandates periodic DEK rotation).
The threat-model trade-off — what CEK rotation defends against, what it does not, when DEK rotation becomes warranted — is in Security → Cryptographic Boundary §8.
5. Encryption Key Isolation
Kibo re-wraps with the two primitives every provider offers, decrypt and encrypt. It does not use a cross-key re-encryption primitive such as AWS ReEncrypt: the DEK is unwrapped under the old CEK version and wrapped under the new one by Kibo's isolated vault service. For the duration of that operation the plaintext DEK is held in that service's volatile memory, under the same lifetime and zeroing rules as any other DEK operation. The plaintext CEK never leaves your KMS, and the gateway never sees either key.
During normal encrypt and decrypt operations (not re-wrap), plaintext DEKs are sequestered within volatile in-process memory and are never persisted to disk, never written to log surfaces, and never serialised over the network. Plaintext DEK lifetime is bounded by a configurable short TTL and explicit zeroing on cache eviction — full detail in Security → Cryptographic Boundary §4. In Secure Key Release (SKR) mode, this in-process sequestration is additionally backed by a hardware-isolated TEE (Intel TDX / AMD SEV-SNP) with an attested channel.
6. Metadata and tombstone discipline
Every wrapped DEK is permanently mapped in Kibo's store to the specific CEK version that produced its wrapping. Each record carries enough metadata for Kibo to identify the DEK, locate the corresponding wrapping in the customer's KMS, and re-wrap on rotation: a Kibo-assigned DEK identifier, the wrapping ciphertext, the KMS provider, the customer's CEK identifier within that KMS, the specific CEK version that produced this wrapping, the wrap timestamp, and the wrapping algorithm in use.
The security law for tombstone discipline: immediately following a successful re-wrap, the historical ciphertext(DEK, CEK_version_N) is tombstoned (purged) from Kibo's persistent store. The purge is atomic with the re-wrap commit — both happen, or neither does. The tombstone close the window on historical CEK exfiltration liabilities: anyone who later compromises the old CEK version finds no wrapped DEKs encrypted under that version to decrypt.
Tombstoning is audit-logged separately from the re-wrap event, so the customer's audit trail shows both "DEK X was re-wrapped from CEK_v3 to CEK_v4" and "the prior ciphertext(DEK X, CEK_v3) was purged from store at timestamp T."
7. The trigger-fluent rotation engine
Kibo detects and processes CEK rotation through two complementary mechanisms:
7.1 On-demand ingress
The primary path. The customer's KMS or operations tooling notifies Kibo immediately when a CEK rotation occurs, through one of two channels:
| Channel | Mechanism |
|---|---|
| Customer-initiated rotation signal | The customer's operational tooling signals Kibo (via the documented rotation surface) that a CEK rotation has occurred; Kibo schedules re-wrap for the affected DEKs |
| Native KMS event subscription | Kibo subscribes to CloudTrail (AWS), Cloud Audit Logs (GCP), or Event Grid (Azure) for CEK rotation events; on event arrival, Kibo schedules re-wrap for the affected DEKs |
The on-demand path closes the historical-exposure window as quickly as event delivery + re-wrap latency allows.
7.2 The safety sweep
A background fallback that runs on the project's configured cadence (per custody policy). The safety sweep:
- Polls each attached CEK's metadata to determine the current active version
- Compares against the CEK version mapped to each project's wrapped DEKs
- For any DEK still wrapped under a non-current CEK version, schedules a re-wrap
The safety sweep catches CEK rotations that were not notified via the on-demand channel — a notification failure, a customer-side rotation that bypassed the configured event path, an event-subscription disruption. It is not the primary path; it is the structural guarantee that no DEK remains indefinitely wrapped under an outdated CEK version.
The per-DEK re-wrap cost is two KMS calls, so stricter sweep cadences impose minimal operational overhead.
8. Switching between providers
The custody ladder is fluent across providers — moving a project from AWS KMS to GCP Cloud KMS, or from BYOK to HYOK, is a custody-policy update on the project, not a code change. The migration path:
- Attach the new CEK to the project. Both CEKs are valid simultaneously during the transition.
- Re-wrap all DEKs under the new CEK. Same decrypt-then-encrypt re-wrap.
- Tombstone the wrappings under the old CEK once re-wrap is complete.
- Detach the old CEK. The customer retains the CEK in their KMS (Kibo cannot delete it); detachment removes Kibo's access to it.
The data ciphertext does not change at any point in the migration; the wrapping envelope is the only thing rotating.
9. Operational patterns
- Rotation cadence. Customer-driven. AWS automatic CMK rotation defaults to annual; many customers configure shorter cycles for high-sensitivity projects. The on-demand channel ensures Kibo re-wraps within the rotation window regardless of cadence.
- Audit trail. Two audit surfaces: Kibo's own audit ledger (every encrypt/decrypt/wrap/unwrap/rewrap operation), and the customer's KMS audit log (every CEK access). The two are cross-correlatable via the request IDs Kibo includes in KMS calls.
- Revocation drills. A periodic exercise: the customer disables the CEK in their KMS, attempts an encrypt/decrypt operation against the project, and verifies the operation fails closed (Kibo cannot fall back to plaintext, cannot proceed without the CEK). Drills are scriptable through the CLI; results contribute to the customer's compliance-evidence record.
10. See also
- Overview — the four custody modes, the Application Cryptographic Oracle Protocol, the network payload strategies.
- HYOK — climbing from BYOK to HYOK; the four cloud-managed HSM paths.
- Audit Ledger — the hash-chained, platform-signed (RSA-2048) ledger with end-user identity attribution.
- CLI — terminal-side vault secrets and offline ledger verification.
- Security → Cryptographic Boundary — the threat-model treatment of key handling, transmission, and re-wrap.
- Custody architecture — custody mode in the broader request flow.