Skip to main content

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.

Customer KMSholds the CEKplaintext CEK neverenters KiboAWS, GCP, Azure, VaultKibostores wrapped DEK:ciphertext(DEK, CEK_vN)plaintext DEK: volatilememory, short TTLDataencrypted under the DEKunchanged by a re-wrapwrap /unwrapDEKencryptsrevoke the CEK and the data becomes cryptographically inaccessible, including to Kilimanjaro
The customer's KMS is the root of trust: Kibo stores only wrapped DEKs, and every wrap or unwrap is a call to your KMS.

1. Supported providers​

ProviderKMS / HSM endpointNotable mechanics
AWS KMSkms.amazonaws.com — symmetric CMK (AES-256-GCM) or asymmetric CMK (RSA / ECC)Automatic key rotation; CloudTrail event subscription for rotation notifications
GCP Cloud KMScloudkms.googleapis.com — symmetric or asymmetric keycryptoKeys.encrypt / decrypt; Pub/Sub notifications via Cloud Audit Logs
Azure Key Vault*.vault.azure.net — software- or HSM-protected keywrapKey / 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:

  1. 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).
  2. Grant Kibo's workload identity the minimum required permissions:
PermissionWhy Kibo needs it
Encrypt / WrapKeyWrap a freshly generated plaintext DEK
Decrypt / UnwrapKeyUnwrap 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:

ProviderGrant
AWS KMSkms:Encrypt, kms:Decrypt, kms:GenerateDataKey, kms:DescribeKey
GCP Cloud KMSroles/cloudkms.cryptoKeyEncrypterDecrypter and roles/cloudkms.viewer, on the key
Azure Key VaultwrapKey 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.

  1. 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.

OperationCostFrequency
CEK re-wrapOne KMS decrypt and one KMS encrypt per active wrapped DEK; no data movementEvery CEK rotation event (customer-initiated or scheduled)
DEK rotation + data re-encryptionFull scan and re-encryption of every record protected by the DEK; bounded by storage size and I/O throughputOnly 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."

ciphertext(DEK, CEK_v3)wrapping under old versionciphertext(DEK, CEK_v4)wrapping under new versionKMS decrypt, then KMS encryptone atomic commit with the purgeTombstoneold wrapping purgedfrom Kibo's storeAudit trailre-wrap: v3 to v4purge of the v3 wrappinglogged separately
A re-wrap swaps the envelope from one CEK version to the next and purges the old wrapping in the same commit, with each event audited separately.

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:

ChannelMechanism
Customer-initiated rotation signalThe 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 subscriptionKibo 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:

  1. Polls each attached CEK's metadata to determine the current active version
  2. Compares against the CEK version mapped to each project's wrapped DEKs
  3. 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:

  1. Attach the new CEK to the project. Both CEKs are valid simultaneously during the transition.
  2. Re-wrap all DEKs under the new CEK. Same decrypt-then-encrypt re-wrap.
  3. Tombstone the wrappings under the old CEK once re-wrap is complete.
  4. 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.