Kibo HYOK
Hold Your Own Key is the fourth rung on the custody ladder. The customer runs their own key manager — a KMIP-conformant appliance or service they administer — and the Customer Encryption Key (CEK) is generated and held inside it. Kibo reaches that key manager over KMIP (the OASIS Key Management Interoperability Protocol) to wrap and unwrap Data Encryption Keys under the CEK; the plaintext CEK never crosses the key manager's boundary. Every wrap, unwrap, and re-wrap executes inside the customer's key manager, invoked over a mutually-authenticated KMIP channel.
The customer's key manager becomes the structural root of trust for the project's encrypted data. The CEK lives in hardware the customer administers; if the customer revokes Kibo's KMIP access or destroys the key, the project's data becomes cryptographically inaccessible — including to Kilimanjaro.
The difference between BYOK and HYOK is the administration boundary. Under BYOK, the customer holds the CEK in a cloud-managed KMS; the cloud provider operates the substrate. Under HYOK, the customer administers the key manager itself — its deployment, its access policies, its quorum authentication, its availability — and Kibo connects to it as a KMIP client. The added operational surface buys a stronger sovereignty story: the customer retains exclusive cryptographic and operational control over the hardware that protects the CEK.
1. Supported key-manager families
The wire value you declare is the KMIP key-manager family — the integration Kibo's KMIP client connects to, not the bare HSM behind it. The enum is closed:
keyManagerFamily | What it is |
|---|---|
cipher-trust | Thales CipherTrust Manager (HSM-rooted in Luna) — a verified KMIP server |
key-control | Entrust KeyControl (HSM-rooted in nShield) — a verified KMIP server |
native-hsm-kmip | An HSM that speaks KMIP directly, as its own KMIP server |
generic-kmip | Any OASIS-KMIP-conformant key manager not separately branded — the exact encoding of "one adapter, any conformant manager" |
Kibo connects over the OASIS-standard KMIP TLS port (5696), with a protocol-version floor of 1.4. The mTLS client certificate and trust-anchor CA are handles into the platform secret store, never inline PEM — the "no client secrets in Kibo" property holds. A generic-kmip manager attaches today without Kibo brand-claiming a vendor it hasn't verified; named families are promoted out of generic-kmip only after grounding against the vendor's official KMIP-server documentation.
AWS CloudHSM is not a HYOK path — it's reached through the AWS-KMS custom-key-store BYOK path, since it fronts a KMS API rather than acting as a KMIP server. Use BYOK for it.
2. The attach ceremony
Attaching a key manager is a deliberate four-step sequence, because the customer administers the hardware substrate rather than a managed-KMS account:
- Register the host —
POST .../vault/hyok/hostsrecords a KMIP endpoint (host, port5696, thekeyManagerFamily, and the client-cert / CA handles). - Group it into a cluster —
POST .../vault/hyok/clustersrecords the KMIP endpoint Kibo will address for this project. A HYOK cluster references a single KMIP endpoint; high availability is resolved on the customer side, behind a VIP or load balancer, and the key is addressed by its KMIPkeyUid. A cluster is registered in a region; attaching a project to a cluster in a different region is refused withK9O_HYOK_REGION_MISMATCH. - Attach the CEK to the project —
POST .../custody-mode-transitioncarryinghyokConfig: { provider: "kmip", clusterId, keyUid }moves the project's custody mode to HYOK against a specific key on that cluster. - Test the connection —
POST .../vault/hyok/testruns a live wrap/unwrap probe against the attached key and returns its result as a diagnostic. The test is advisory: it always answers200with the outcome in the body, and it never rolls anything back. What gates the attachment is the attachment validation that runs inside the custody-mode transition job, so a misconfigured cluster cannot become the live custody path for real data.
Kibo's principal is granted only the cryptographic operation set (wrap, unwrap, re-wrap). Administrative operations — key creation, deletion, rotation, policy modification — remain exclusively with the customer; Kibo's KMIP client cannot perform them.
3. The attestation path
HYOK's assurance rests on where the CEK lives and who administers it — not on a proof Kibo makes about the customer's hardware. The plaintext CEK is generated and held inside the customer's own key manager; Kibo holds only wrapped DEKs and the metadata needed to re-wrap, and reaches the CEK only over the mutually-authenticated KMIP channel to perform wrap and unwrap. Kibo does not independently prove the key's hardware residency — it records and faithfully surfaces what the customer's key manager asserts.
What the customer's KMIP manager asserts — captured at attach via a GetAttributes call and recorded on the project's custody attestation:
- The key's non-extractability attributes, as the manager reports them
- The key's type and state
- The KMIP manager family, and where the manager supplies it, the HSM it is rooted in
If the attached key reports as extractable, Kibo surfaces a warning on the attachment — it does not reject the attach. Enforcement of non-extractability is the customer's own HSM and policy, not a platform gate, so the custody attestation is recorded as a manager assertion, never as independent hardware proof.
The assurance a HYOK customer relies on is therefore the combination of (a) their own key manager's asserted non-extractability, (b) their exclusive administrative control over the key manager and the HSM behind it, and (c) Kibo holding only wrapped DEKs and metadata and faithfully recording every access in the identity-attributed key-access audit. The custody claim the platform records for an attached key is kmip-manager-asserted: it is what your manager reports, not something the platform proves about the hardware. The plaintext CEK never crosses the customer's key-manager boundary, and the project's wrapped DEKs cannot be unwrapped except by a principal holding the configured cryptographic permission on the customer's CEK.
4. Decoupled lifecycle engineering
The same asymmetric-cost design applies as in BYOK §4: routine CEK rotation triggers a re-wrap of every active wrapped DEK under the new CEK version, not data-plane re-encryption. Each re-wrap unwraps the DEK under the old CEK version and wraps it under the new one with two calls to your key manager; the plaintext CEK never leaves it, and the DEK is held only in Kibo's isolated vault memory for the operation (see BYOK §5). The data ciphertext does not change.
DEK rotation — generating a new DEK and re-encrypting the underlying data — remains a distinct operation triggered only by DEK exposure evidence, regulatory mandate, or scheduled cryptoperiod expiry. CEK rotation does not trigger DEK rotation; the two lifecycles are decoupled.
The threat-model treatment of re-wrap, historical version exposure, and tombstone discipline is shared with BYOK at Security → Cryptographic Boundary §8.
5. Encryption Key Isolation
The plaintext CEK never leaves the HSM boundary at any point. Under BYOK, this is enforced by the cloud KMS's HSM substrate — a policy property of the cloud provider's configuration. Under HYOK, the same property is enforced by the customer's own HSM hardware — a structural property of the cluster the customer administers.
During normal encrypt and decrypt operations, the plaintext DEK is unwrapped by the HSM and sequestered in volatile in-process memory under the same lifetime bounds documented in BYOK §5. The DEK is never persisted to disk, never written to log surfaces, and is explicitly zeroed on cache eviction. Plaintext-DEK lifetime is bounded by a configurable short TTL — see Security → Cryptographic Boundary §4 for the full treatment. On the hardware-attested tier, this in-process sequestration is additionally backed by a hardware-isolated TEE with an attested channel.
6. Metadata and tombstone discipline
Same as BYOK. Every wrapped DEK is permanently mapped in Kibo's store to the specific CEK version that produced its wrapping, with enough metadata to identify the DEK, locate the corresponding wrapping in the customer's HSM, and re-wrap on rotation. Tombstone discipline is enforced identically: the historical wrapping is purged from Kibo's persistent store atomically with the re-wrap commit, audit-logged separately, and unable to be reconstructed.
See BYOK §6 for the full metadata schema and tombstone semantics.
7. HSM cluster operational substance
HYOK adds operational surface that BYOK does not. The customer administers the HSM substrate, and that responsibility breaks down into four dimensions:
- Key-manager provisioning and lifecycle. Initial key-manager setup, key and capacity provisioning, and decommissioning are customer-owned. The customer administers the key manager and the HSM behind it; Kilimanjaro addresses the CEK by its KMIP
keyUidand does not manage the manager's internal layout. - Access controls. Key-manager policies — which principals can perform which cryptographic operations against which keys — are administered by the customer. Quorum authentication for sensitive administrative operations (key creation, deletion, key-manager reset) is the customer's policy decision.
- Availability monitoring. HSM cluster availability is a customer-side operational concern; Kibo's HYOK adapter surfaces cluster reachability and key-state signals (see §8) to drive the customer's availability dashboards and runbooks.
- Audit collection. The customer collects HSM cluster audit logs into their own audit infrastructure; cross-correlation with Kibo's audit ledger uses the same request-ID surface as BYOK.
The operational surface is the cost paid for the stronger sovereignty boundary. Customers electing HYOK typically have compliance regimes or threat models that justify the overhead.
8. HSM-state diagnostics
Under HYOK, HSM cluster state is surfaced directly to the customer with the semantic depth of the underlying HSM. Under BYOK, HSM-internal state — whether the underlying HSM is healthy, locked, partitioned — is folded behind a generic key-unreachable signal; the customer is not administering the HSM, so cluster-level diagnostics would not be actionable. Under HYOK, the customer is administering the HSM, so cluster-level diagnostics are exposed:
- Endpoint reachable / unreachable. Network path or key-manager availability surface.
- Key state. Whether the CEK itself — addressed by its KMIP
keyUid— is in an active, suspended, or destroyed state. - Manager state. Whether the key manager itself is reachable and unlocked; family-specific failure modes (a sealed or locked manager, an expired credential) surface distinctly.
The customer-administration model drives a deeper error surface than BYOK's. Operations that fold behind a generic key-unreachable signal under BYOK surface directly under HYOK, where the customer is operating the HSM and the granularity is actionable. Customer telemetry pipelines integrating with Kibo's HSM-state stream can rely on HYOK surfacing the resolution needed to operate the cluster.
9. Climbing from BYOK to HYOK
The custody ladder is fluent across modes. Moving a project from BYOK to HYOK — graduating from a cloud-managed CEK to a customer-administered HSM cluster — is a custody-policy update on the project, not a code change. The migration path:
- Provision the HSM cluster and create the new CEK inside it (per §2 above).
- Attach the HSM-backed CEK alongside the existing BYOK CEK; both are valid during the transition.
- Re-wrap all DEKs under the new HSM-backed CEK. The plaintext CEK never leaves its key manager during the operation; the DEKs are re-wrapped in Kibo's isolated vault memory.
- Tombstone the wrappings under the old BYOK CEK once re-wrap completes.
- Detach the old BYOK CEK. The customer retains the CEK in their cloud KMS (Kibo cannot delete it); detachment removes Kibo's access to it.
The data ciphertext does not change at any point. The SDK call surface does not change. The customer's application code does not change. Only the wrapping envelope and the substrate that holds the CEK change.
10. See also
- Overview — the four custody modes, the Application Cryptographic Oracle Protocol, the network payload strategies.
- BYOK — the rung below HYOK; cloud-managed KMS-held CEK with shared lifecycle properties.
- 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.