Couchbase Encryption at Rest

ينطبق على:

DuoKey Cockpit v2Couchbase Server 7.1+ Enterprise EditionKMIP-sourced Key Encryption Key

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.

Distinct from generic disk encryption

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.

Architecture

Couchbase to the DuoKey KMIP server

Couchbase owns its Data Encryption Keys end to end; only the Key Encryption Key wrapping them crosses the KMIP connection to DuoKey.

Two ways Couchbase can use the KMIP connection

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.

Enrollment steps returned with the bundleTEXT

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 key

Cluster status

The 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

Swimlane

From KEK provisioning to Couchbase applying it

Steps 1-2 happen in DuoKey Cockpit; steps 3-5 are the operator applying the connection details 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.

Coordinate rotation with Couchbase's own re-wrap

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.

Overview​

Configuration​

Enrollment flow​