MongoDB Client-Side Field-Level Encryption (CSFLE)
Specific document fields are encrypted by the driver before they leave the application — MongoDB itself only ever stores and returns opaque ciphertext.
Overview
MongoDB Client-Side Field-Level Encryption (CSFLE) encrypts selected document fields in the driver, before the write ever reaches the MongoDB server, and decrypts them on read — the server never sees plaintext for those fields, and fields encrypted this way are opaque to queries: MongoDB can store and return the ciphertext, but cannot filter, sort, or index on it.
Each encrypted field is protected by a per-field Data Encryption Key (DEK), stored in a MongoDB collection called the key vault collection. Those DEKs are themselves wrapped by a Customer Master Key (CMK) sourced from a KMS provider. This app's role is that KMS provider: DuoKey custodies the CMK and hands the driver the reference it needs to create and unwrap DEKs.
Architecture
MongoDB CSFLE: where encryption happens
Only the driver process ever sees plaintext for an encrypted field; MongoDB itself stores and returns ciphertext only.
| Property | Value |
|---|---|
| Encryption model | Client-side field-level encryption — opaque, non-queryable ciphertext |
| Key custody | DuoKey vault key wraps the DEKs stored in the MongoDB key vault collection |
| Onboarding | Guided multi-step wizard |
| Proof status | Deployment/config generation real; self-test currently simulated — see below |
The self-test and health-check endpoints for this integration currently return simulated, hardcoded results rather than performing a live round-trip against a running MongoDB deployment. The app record, the linked vault key, and the generated configuration are real; the pass/fail signal from the self-test is not yet backed by a live encrypt/decrypt call.
Configuration
| Field | Purpose |
|---|---|
mongodb_uri | MongoDB connection URI (`mongodb://` or `mongodb+srv://`) — supports Atlas and self-hosted deployments. |
database | Target database. |
key_vault_namespace | Namespace (`database.collection`) MongoDB uses to store encrypted data keys. Defaults to `encryption.__keyVault`. |
kms_provider | KMS provider type the driver uses to reach the master key: `kmip` (DuoKey, recommended), `aws`, `azure`, `gcp`, or `local` (development only). |
encryption_schema | JSON schema declaring which fields to encrypt and how (deterministic or randomized). |
linked_key_id | The DuoKey vault key acting as the master key wrapping the DEKs. |
Onboarding via the wizard
MongoDB connection
Enter the connection URI and target database.
KMS provider
Select the KMS provider — KMIP is recommended for DuoKey-backed deployments.
Encryption schema
Define which fields to encrypt and their algorithm (deterministic enables equality matching on ciphertext; random does not).
Key vault
Configure the key vault namespace where MongoDB stores the encrypted data keys.
Vault & key
Select the DuoKey vault and master key wrapping the data keys.
Review & deploy
Review the summary and get driver configuration snippets for Node.js, Python, Java, and Go.
A deterministic-encrypted field always produces the same ciphertext for the same plaintext, so the driver can query it for exact equality — at the cost of leaking which documents share a value. A randomized-encrypted field never repeats ciphertext and cannot be queried at all. If you need to query a field on more than exact equality (ranges, for example), CSFLE cannot do it — see MongoDB Queryable Encryption.
How a CSFLE write flows
Sequence
Encrypting one field, end to end
Steps 2-4 all happen inside the driver process; MongoDB itself is only ever handed ciphertext.
Health and self-test
| Check | What it reports | Live probe today |
|---|---|---|
| Health | MongoDB reachability, key vault accessibility | No — returns a fixed healthy status envelope |
| Self-test | MongoDB connection, key vault access, field encrypt/decrypt round-trip, KMS provider reachability | No — all four checks return a hardcoded pass |
Until the self-test drives a live MongoDB session, confirm field encryption is genuinely active by inspecting a raw document (via the shell, bypassing the encrypted client) and checking that the target fields are BSON binary ciphertext, not plaintext.