Skip to main content

Custody architecture

Every project on Kilimanjaro carries a custodyMode controlling where the encryption keys protecting that project's data live and who can receive them. The modes split across two axes: Platform-Managed and SKR (Secure Key Release) are both platform-custody modes — Kibo holds the Data Encryption Key — but they differ on which callers can receive it. BYOK (Bring Your Own Key) and HYOK (Hold Your Own Key) are sovereignty modes — Kibo never holds the plaintext key at all. Where most secrets-management services treat custody as a binary choice (vendor holds the keys, or customer does), Kilimanjaro treats custody as a structural property the customer reshapes on their own schedule — without code changes, without re-encryption events, without operational pauses.

This page covers the custody architecture as an architectural decision. The operational guide for setting custody on a project is in Guides → Sovereignty §3; the Kibo-specific mechanics live in Kibo BYOK and Kibo HYOK; the threat-model treatment of the cryptographic boundary is in Security → Cryptographic Boundary.

1. The four modes​

ModeWhere the CEK livesCustomer involvement
Platform-ManagedKibo's platform-managed, region-pinned vault (software-protected key)None — the platform generates and manages the customer encryption key inside its own vault. Rotation is on demand: a project admin rotates it with a fresh step-up, and older versions stay readable
SKR (Secure Key Release)Platform-managed enclave; released only to attested codeKibo holds the key but releases it only to your own verified, attested code. The project pins a measurement policy (allowlist + TCB floor); an unauthorized build is refused, not warned. The integrity mode.
BYOK (Bring Your Own Key)Customer's cloud KMS — AWS KMS, GCP Cloud KMS, or Azure Key VaultCustomer holds the customer encryption key in their own cloud KMS; Kibo wraps Data Encryption Keys under that CEK via cloud-native KMS primitives. The platform never holds the customer key
HYOK (Hold Your Own Key)Customer-owned HSM clusterCustomer holds the CEK in their own hardware security module; Kibo wraps DEKs through the customer's HSM API surface. Key material never leaves the customer's HSM

SKR is the integrity mode of the custody model — hardened Platform-Managed custody. Kibo still holds and uses the plaintext data-encryption key, but releases it only to your own attested code. The project pins a measurement policy (an allowlist of authorized enclave measurements plus a minimum TCB floor); every key release is verified against that policy at fetch time. A build whose measurement is not on the allowlist, or whose TCB is below the floor, is refused, not warned — and enabling SKR with no registered policy refuses release outright rather than silently passing.

SKR buys integrity: your key reaches only your verified code, defending against credential theft and a compromised host. It does not make custody sovereign — because Kibo must hold the key to enforce the attestation, the platform remains in the key path. Operator-blind, zero-knowledge custody is the BYOK and HYOK tiers, where Kibo only ever sees wrapped keys.

The custody trust structure:

  • Platform-Managed — Kibo holds the key; any valid credential receives it.
  • SKR — Kibo holds the key; only your verified, attested code receives it. (integrity)
  • BYOK / HYOK — Kibo is blind; it sees only wrapped keys. (sovereignty)

2. The Data Encryption Key / Customer Encryption Key separation​

Every custody mode follows the same architectural pattern. Application data is encrypted under per-collection or per-record Data Encryption Keys (DEKs). Each DEK is wrapped under a project-scoped Customer Encryption Key (CEK). The wrapped-DEK ciphertext is stored alongside the encrypted data; the plaintext DEK only exists transiently inside Kibo's enclave for the duration of a cryptographic operation.

The custody mode determines where the CEK lives. The DEK layer is consistent across modes:

Application dataencrypted under DEKWrapped DEKciphertext, storedwrapped under CEKCEKheld per custody modePlatform-ManagedKibo vault — any valid credentialSKRKibo vault, TEE-gated — attested code onlyBYOKcustomer KMS — platform never holds the keyHYOKcustomer HSM — key never leaves the cluster
The DEK layer is identical across modes; only where the CEK lives changes. That is what lets a project climb the custody ladder without a code change or a re-encryption event.

This is the load-bearing architectural decision. Because the DEK layer is consistent, every read or write request follows the same code path regardless of custody mode — the gateway hands the wrapped DEK to Kibo, Kibo unwraps it (or delegates to the customer's KMS / HSM for BYOK and HYOK), the plaintext DEK exists transiently in process memory for the duration of the operation and is zeroized after use, and the operation completes. The customer's application code does not know which custody mode the project is in.

3. Climbing without code change​

The architectural property that follows from the DEK/CEK separation: changing custody mode is a custody-policy update on the project, not a code change. A project that starts in Platform-Managed and graduates to BYOK runs the same SDK code through the same gateway against the same data plane. The only thing that changes is where the CEK lives and how it gets invoked at unwrap time.

This is not just a developer-experience win. It is a structural sovereignty property: a customer evaluating whether to commit to higher custody can climb without committing engineering cost. A team running on Platform-Managed can move to BYOK on a Tuesday afternoon without standing up a code-migration project; a regulated workload that needs HYOK can move there from BYOK without rewriting the application.

The same Kibo SDK calls work against every mode. Code written against Platform-Managed runs unchanged against HYOK.

Application-level encryption follows the same rule. One call, crypto.encrypt, crypto.decrypt or crypto.rewrap over a keyring, has the same shape and the same result in every custody mode, and the SDK picks the path, not the developer:

  • Platform-Managed (and a self-deployed Sovereign Perimeter): the call goes to the platform's encryption route, which seals the value under the project key.
  • BYOK and HYOK on a cloud-managed project: encryption runs in your process. The SDK takes a short-lived federated token from Gate (the only call to the platform), generates the data key locally, has your KMS wrap it, and seals the value with AES-256-GCM in-process. The plaintext and the unwrapped data key never leave your process, and the platform stores only ciphertext and the wrapped key.

Both paths produce the same sealed container, whose provider tag names who can open it, so stored ciphertext stays readable whichever mode produced it. The server never opens a container sealed under your own key. A raw HTTP caller that bypasses the SDK and targets a BYOK or HYOK project is refused with K9O_ZK_STORE_FLOW_REQUIRED. A runtime that cannot load the client-side core gets K9O_ZK_CLIENT_CORE_UNAVAILABLE on such a project, which is a deployment requirement of choosing your own key, not a change to the API.

There are three separate constructions, and none of them opens another's ciphertext: client-side Kibo encryption under your own key, the platform's application encryption route, and the extension route. A value sealed by one cannot be opened by another. Erasure of values sealed by the application encryption route follows the project key's lifecycle only, never a per-subject erasure (Cryptographic erasure).

4. Upgrade frictionless, downgrade gated​

Climbing the ladder (lower → higher custody) is operationally frictionless: the new mode's onboarding is the only cost. The customer creates the new key material (in their KMS for BYOK, in their HSM for HYOK), attaches it to the project, and the platform re-wraps the existing DEKs under the new CEK at the next rotation event.

Descending the ladder (higher → lower custody) requires admin attestation through the IRREVERSIBLE_ACTION_GATE policy family. The friction is deliberate. Moving keys from a stronger custody mode to a weaker one erodes a security guarantee that customer audit trails, compliance evidence packages, and contractual commitments may have anchored against. Any two distinct modes transition directly, and each descent — however many rungs it spans — earns exactly one multi-party attestation:

  • SKR → Platform-Managed = one IRREVERSIBLE_ACTION_GATE
  • BYOK → SKR or Platform-Managed = one IRREVERSIBLE_ACTION_GATE
  • HYOK → BYOK = one IRREVERSIBLE_ACTION_GATE
  • HYOK → Platform-Managed or SKR = one IRREVERSIBLE_ACTION_GATE (a direct transition, not one gate per rung)

The asymmetry is the structural protection. Adding custody is always permitted (the customer reclaims control); surrendering it requires proof of intent. A misconfigured automation, a compromised admin account, or an accidental click cannot quietly downgrade the project's custody mode — every step generates a maker-checker chain with cryptographic attestation by named approvers.

5. Where this composes​

The custody architecture composes with the rest of the platform's structural decisions:

  • Region pin — the CEK is region-co-located with the data it wraps. A project in de01 keeps its CEK inside EU jurisdiction regardless of custody mode; a project in us01 keeps it inside US jurisdiction. See Regions & residency.
  • Audit ledger — every cryptographic operation against the CEK emits a signed audit entry (CEK invocation, DEK wrap or unwrap, key rotation, custody-mode transition). The audit chain is the forensic surface customer compliance evidence packages reference.
  • Unified Policy — the IRREVERSIBLE_ACTION_GATE family that protects custody downgrades is the same policy primitive that governs other irreversible actions (project deletion, member-role escalation, key revocation). See Unified Policy → §5.
  • Identity-Aware Kernel — the operator attempting a custody-mode transition is identity-bound through Gate; the IRREVERSIBLE_ACTION_GATE's not_originator and role_required constraints reference the same identity claims every other policy expression evaluates against.

The custody mode is not a feature bolted onto an existing platform; it is one of the structural decisions the rest of the architecture composes against.

6. See also​

  • Overview — where custody mode sits in the broader platform model.
  • Kibo Overview — the Application Cryptographic Oracle Protocol that backs the DEK/CEK separation.
  • Kibo SKR — the integrity mode: measurement policy, CI registration, per-release enforcement.
  • Kibo BYOK — the three cloud KMS provider lanes and the wrap / re-wrap mechanics.
  • Kibo HYOK — the customer-owned HSM cluster paths.
  • Security → Cryptographic Boundary — the threat-model treatment of plaintext sequestration, transmission, and re-wrap.
  • Unified Policy — the IRREVERSIBLE_ACTION_GATE family that governs custody downgrades.
  • Guides → Sovereignty §3 — the operational guide for setting custody on a project.