Field Encryption

Encrypt configured document fields before writes and decrypt them on reads using envelope encryption.

Always confirm availability in the release bundle selected for deployment.

At a glance

Property	Value
Pipeline phase	Request + response
Category	Compliance
Canonical minimum tier	Enterprise
Canonical entitlement	Yes
Supported deployment contract	Yes
Release status	Enterprise implementation; deploy only through a bundle that explicitly publishes support.

Release accuracy

• Current documentation: Enterprise implementation; deploy only through a bundle that explicitly publishes support.

Where any detail below conflicts with the release status above, the release status is authoritative. Field names and examples describe the current dashboard and CRD surface; always confirm behavior against the selected release bundle before relying on it operationally.

Release-aware feature flow. The diagram is explanatory; the release status on this page is authoritative.

Diagram resources: Open the SVG full screen · Download the editable Excalidraw source

Performance impact

:::warning Unverified performance figures

These figures are illustrative only. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Reported figure
P50	~0.15ms
P95	~0.4ms
P99	~0.8ms

Note: Per encrypted field per document; AES-GCM is hardware-accelerated. Randomized mode is marginally cheaper than deterministic (no HKDF derivation).

Overview

Field Encryption is the builtin:field-encryption proxy runtime step. It transparently encrypts configured document fields on the request path (inserts, updates, replacements) and decrypts them on the response path (find results, findAndModify values), so applications keep working with plaintext while MongoDB only ever stores ciphertext.

Encryption uses envelope encryption: a key-encryption key (KEK) — mounted into the step from an external secret, never stored in the control-plane — wraps per-value data-encryption keys (DEKs). Each encrypted value is stored as a self-describing BSON Binary (subtype 0x06) protected with AES-256-GCM, so the response path can decrypt without any request-path state.

When to use

• Protecting regulated PII/PHI/PCI fields (SSN, card numbers, health data) with encryption-at-rest independent of MongoDB CSFLE drivers
• Meeting compliance requirements that mandate application-transparent field encryption
• Encrypting fields while still allowing equality lookups (deterministic mode) on selected fields

How it works

1. Request phase: Walks configured field paths in the command (documents, update operators, replacement docs) and replaces each value with an AES-256-GCM envelope. In deterministic mode it also rewrites equality predicates ({field: v}, $eq, $in, $match) so lookups match stored ciphertext.
2. Response phase: Detects envelopes in firstBatch/nextBatch/findAndModify values and decrypts them back to plaintext for the client.
3. Failure policy: fail_closed (default) rejects the operation on any crypto error so plaintext is never forwarded; fail_open logs and passes through (unsafe).

Configuration

“Not specified” means required semantics were not declared for that field.

Field	Type	Default	Required	Description
enabled	boolean	true	No	Soft toggle without removing the step
fields	json	—	Yes	Dot-notation field paths to encrypt
mode	select	randomized	No	randomized (max security) or deterministic (queryable equality)
kmsKeyId	string	—	No	Opaque key identifier embedded in the envelope for audit/rotation
rotationVersion	number	1	No	Bump on key rotation (deterministic equality does not span rotations)
failurePolicy	select	fail_closed	No	fail_closed (default) or fail_open

Settings reference

No additional settings reference is documented for this component.

Examples

Encrypt SSN (randomized) and email (queryable)

apiVersion: nexo.io/v1alpha1
kind: NexoFieldEncryption
metadata:
  name: pii-encryption
spec:
  enabled: true
  mode: deterministic   # allows equality lookups on encrypted fields
  kmsKeyId: nexo-fle-key-2026
  rotationVersion: 1
  failurePolicy: fail_closed
  fields:
    - profile.ssn
    - email

Best practices

• Use randomized mode by default; only use deterministic for fields you must query by equality — it leaks equality
• Keep failurePolicy: fail_closed in production so a key/crypto failure never writes plaintext
• Provision the KEK via an external secret store (e.g. Azure Key Vault CSI) into the nexo-fle-kek secret; never commit key material
• Plan rotation: bumping rotationVersion re-derives deterministic keys, so equality matches do not span the rotation boundary — re-encrypt existing data if you need cross-rotation lookups

Limitations

• Deterministic mode enables server-side equality only; range, regex, and text queries on encrypted fields are not supported
• Phase 1 uses a static KEK from a mounted secret; cloud KMS API providers (Azure Key Vault / AWS KMS) and role-based bypass are Phase 2
• Encrypting a field used as a shard key or in an index prefix will break routing/index semantics — encrypt only non-key fields

Security and operational guidance

• The current implementation loads the KEK from NEXO_FLE_KEK; kmsKeyId is an opaque label and does not invoke or validate a cloud KMS
• Mount the KEK through the approved Secret or CSI workflow instead of pipeline configuration
• Use fail closed for crypto errors
• Document rotation and backup recovery
• Deterministic encryption leaks equality and does not transparently span rotation boundaries

Related steps

• pii-masking
• query-guard
• audit-log

Release availability

• Current documentation: Enterprise implementation; deploy only through a bundle that explicitly publishes support.

See the component catalog for the complete comparison matrix.