Couchbase Encryption at Rest
A DuoKey-held Key Encryption Key, wrapping Couchbase's own Data Encryption Keys over KMIP.
Overview
Couchbase Server (7.1+ Enterprise Edition) ships a database-internal Native Encryption at Rest feature: Couchbase itself generates and manages Data Encryption Keys (DEKs) protecting buckets, indexes, logs, audit data and configuration on disk. Those DEKs are, in turn, wrapped by a Key Encryption Key (KEK) that Couchbase sources from an external KMS over KMIP (or AWS KMS).
This app provisions that KEK in a DuoKey vault and emits a KMIP enrollment bundle — host, port, key ID, and client certificate identity — that an operator pastes into Couchbase's own Security > Encryption at Rest configuration screen. Couchbase does its own key wrapping internally over the KMIP connection; DuoKey's role is entirely on the key-custody side.
This is a genuinely different mechanism from a generic OS-level disk-encryption app (PKCS#11/CNG-KSP volume unlock): Couchbase's own /settings/security/encryptionAtRest configuration drives the wrap, not an OS-level volume unlock.
Couchbase owns its Data Encryption Keys end to end; only the Key Encryption Key wrapping them crosses the KMIP connection to DuoKey.
Couchbase's own KMIP client offers two modes: "Use KMIP Get & encrypt locally", where it fetches the KEK bytes once and wraps/unwraps DEKs on the node, or "Use KMIP native Encrypt/Decrypt operation", where Couchbase instead sends wrapped DEK material to the KMIP server to encrypt or decrypt, so the KEK bytes never leave DuoKey at all. Either way, DuoKey never sees a DEK or bucket data — only, in the first mode, the KEK material for that connection.
| Property | Value |
|---|---|
| Encryption model | Engine-native DEK/KEK wrap — KEK sourced externally over KMIP |
| Key type | AES-256 KEK, generated in the DuoKey vault |
| Onboarding | App detail page — no wizard entry |
| Proof status | KEK provisioning and the KMIP enrollment bundle are real (a genuine vault key is created); applying the bundle inside Couchbase is a manual operator step, not yet automated end to end |
Configuration
| Field | Purpose |
|---|---|
cluster_hosts | Informational list of cluster node hostnames. |
bucket_scope | `cluster` — one KEK for the whole cluster (default) — or `per_bucket`. |
vault_id | The DuoKey vault the KEK is created in. |
Deploying the app creates the Couchbase encryption app together with a first cluster record. Enrolling that cluster is a separate step that actually provisions the KEK.
Enrollment flow
Deploy the app
Create the app and its first cluster record, choosing whether the KEK scope is cluster-wide or per-bucket.
Enroll the cluster
Trigger enrollment. The Cockpit creates a real AES-256 KEK in the selected vault (or the tenant's default software vault if none is specified) and generates a stable KMIP Unique Identifier for it.
Apply the enrollment bundle in Couchbase
Follow the returned steps inside the Couchbase Web Console to point Couchbase at the DuoKey KMIP server and install the client mTLS identity.
Enable Encryption at Rest
Apply the KEK to the cluster (or per bucket) in Couchbase and confirm the DEKs report an encrypted status.
The enrollment bundle
| Field | Purpose | |
|---|---|---|
kmip_host | kmip_port | Where Couchbase should dial — the Cockpit KMIP server (default port 5696). |
kmip_key_id | The KEK's KMIP-visible Unique Identifier. | |
client_cert_alias | The client identity Couchbase authenticates with over mutual TLS. |
1. Open the Couchbase Web Console
Security > Encryption at Rest > Add Encryption Key
2. Configure the key
Key Type: KMIP
Host / Port: <kmip-host> / 5696
KMIP key ID: <kmip-key-id>
Client certificate: install the <client-cert-alias> mTLS identity
Encryption approach: "Use KMIP Get & encrypt locally" or
"Use KMIP native Encrypt/Decrypt operation"
3. Apply the key
Cluster-wide: Security > Encryption at Rest > set the cluster default key
Per bucket: Buckets > <bucket> > Edit > Advanced bucket settings >
Encryption at Rest > select the keyThe app exposes a status check reporting the cluster's enrollment state, whether a KEK is bound, and whether the vault holding it is currently reachable — useful for confirming the KEK side is healthy before troubleshooting on the Couchbase side.
Enrollment sequence
Steps 1-2 happen in DuoKey Cockpit; steps 3-5 are the operator applying the bundle inside Couchbase.
Key rotation
Rotating a cluster's KEK creates a new AES-256 key in the same vault and a new KMIP identifier, under the same client certificate identity — the operator re-applies the new kmip_key_id on the Couchbase side following the same enrollment steps.
Couchbase must re-wrap its DEKs under the new KEK once you switch the KMIP key ID; follow Couchbase's own encryption-at-rest key-rotation guidance for the sequencing on the Couchbase side.