Customer-managed keys (BYOK)

BYOK binds a dedicated service to the customer’s own external KMS. Providers are validated with a live round-trip against the customer’s key before any binding is applied.

1. What BYOK is (and isn’t)

BYOK is architecturally identical to the Dedicated tier, plus a validated binding to the customer’s external key-management service (KMS). What the key does depends on the service’s engine:

• OpenBao (the default engine) — the customer’s key seals the server: it must decrypt the vault’s root key every time the server starts. If the customer disables or revokes the key, the server can’t unseal and all access is fenced. While unsealed, the managed control plane still operates the box.
• Infisical — the customer’s key backs project encryption. If the customer revokes its access, the service can no longer decrypt those projects.

Either way, a lost key fails closed rather than silently.

Accurate claims only

Shared and Dedicated are described as “AES-256-GCM at rest, per-organization/project isolation, audit-logged. Encryption keys are operator-managed for this tier.” BYOK adds that the customer-managed external KMS controls auto-unseal (OpenBao) or backs project encryption (Infisical). The module never claims zero-knowledge, end-to-end, or customer-held-root-key encryption for any tier — that copy is blocked in code.

2. Supported KMS providers

Five providers are recognized. Four have a live validator; PKCS#11 HSM validates configuration shape only and fails closed for live validation and binding.

KMS provider	Slug	Auth methods	Status
AWS KMS	aws	iam_role, access_key	Live validator
GCP Cloud KMS	gcp	service_account	Live validator
Azure Key Vault	azure	client_cert, access_key	Live validator
HashiCorp Vault Transit	vault	token	Live validator
PKCS#11 HSM	pkcs11_hsm	client_cert, access_key	Shape-only, fail-closed

OpenBao services can seal with any of the four validated providers. On Infisical services, the module can bind only AWS KMS and GCP Cloud KMS (it creates the Infisical external-KMS record for those two), so Azure Key Vault and Vault Transit BYOK work on OpenBao services only.

Only sell what validates

Offer BYOK only for providers with a live validator, on an engine that can bind them. PKCS#11 HSM validates the configuration shape but fails closed for live validation and binding on both engines.

3. The binding flow

BYOK is customer-initiated from the client area and validated before anything is bound:

1. On the service’s Settings tab, the customer’s BYOK setup walks through Provider → Credentials → Validate → Provision: they choose the KMS provider and enter the auth method, endpoint, key identifier, and scoped API credentials — never raw key material.
2. Validate runs a live round-trip against the key — encrypt/decrypt, or wrap/unwrap on Azure Key Vault. PKCS#11 HSM validates shape only and fails closed.
3. Only after validation passes can provisioning/binding proceed. An existing dedicated box is converted in place — no new VPS is created.
4. The weekly reseal cron re-validates each key that hasn’t been validated in the past 7 days, and completes a key rotation the customer requested (Rotate or update your KMS key), moving the binding from the previous key reference to the newly validated one.

Credential payloads are stored encrypted, and the env contributor masks sensitive values with ***.

4. Migrations into and around BYOK

BYOK participates in the module’s tracked, resumable migration engine:

Migration	Shape
dedicated_to_byok	In-place — started by a WHMCS plan change from Dedicated to BYOK; converts the existing dedicated box after KMS validation, no new VPS

A move from Shared straight to BYOK is refused: upgrade to Dedicated first, then to BYOK once that migration has cut over. Key rotation isn’t a migration job — it runs through the reseal cron (on OpenBao, as a seal migration on the same server).

The migration cron (every 5 minutes) advances jobs. A Shared-to-Dedicated migration moves through provisioning → replicating → validating → cutover_pending; when it is cutover-pending, the customer (or you) triggers the final cutover from the service’s Overview. Long jobs checkpoint so a retry does not restart from scratch.

5. Operating BYOK

• A sudden BYOK decryption failure is a customer-side KMS policy change first — check whether the customer revoked or rotated key access before assuming a module fault. Decryption failing closed is by design.
• Keep BYOK offerings limited to providers whose validator you have proven end to end.
• Rotations run through the weekly reseal cron, which moves the binding to a newly validated key reference rather than mutating the live one.