Field Encryption

Status: Unavailable: NexoFieldEncryption is schema-only in the pinned Operator.

:::caution No supported deployment contract

This capability is documented for catalog completeness, but the selected release does not publish a supported end-to-end deployment contract.

:::

This page belongs to the immutable 0.2.0 Private Preview documentation.

At a glance

Property	Value
Pipeline phase	Request + response
Category	Compliance
Canonical minimum tier	Enterprise
Legacy dashboard tier label	Enterprise
Legacy rendered name	Field Encryption
Legacy rendered summary	Encrypt configured document fields at the proxy in transit to MongoDB using envelope encryption, so plaintext never reaches the database.
Canonical entitlement	Yes
Supported deployment contract	No
Release status	Unavailable: NexoFieldEncryption is schema-only in the pinned Operator.

Release accuracy

• 0.2.0 Private Preview: Unavailable: NexoFieldEncryption is schema-only in the pinned Operator.

The detailed material below preserves every section rendered by the legacy dashboard. Where it conflicts with the release status above, the release status is authoritative. Legacy field names and examples are not a substitute for the selected bundle's CRD and runtime contract. Unsafe legacy wording is retained in metadata for traceability but is corrected in the rendered guidance.

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 Legacy, unverified performance claims

These numbers are preserved for documentation parity with the legacy dashboard. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Legacy claim
P50	~0.15ms
P95	~0.4ms
P99	~0.8ms

Legacy 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

The table preserves the legacy dashboard field reference. “Not specified” means the legacy source did not declare required semantics.

Field	Legacy UI type	Legacy 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

The legacy page did not render an additional anchored settings reference.

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 0.2.0 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

Release availability

• 0.2.0 Private Preview: Unavailable: NexoFieldEncryption is schema-only in the pinned Operator.

See the component catalog for the complete comparison matrix.