Files
clean-architecture-backend-…/docs/mongodb/advanced/encryption.md
T

5.5 KiB

Advanced — CSFLE and Queryable Encryption

Capabilities: MongoCapability.CSFLE, MongoCapability.QUERYABLE_ENCRYPTION Enablement: library API, no configuration property. The service's own adapter constructs the entry point with a MongoAdvancedCapabilityGuard built from MongoAdvancedCapabilityFlags that enables the capability; construction is refused otherwise. Status: Advanced.

Requirements

Topology Replica set or sharded cluster.
Server MongoDB 7.0 or 8.0 (see §4 for the 8.0 query-type limits).
Privilege MongoPrincipalRole.ENCRYPTION_ADMIN for the key vault; the application role never holds it.
Environment A real KMS and key vault. A local key provider does not exercise any of the failure modes that matter.

1. CSFLE

MongoCsfleProfile binds a collection (database + collection) to its MongoCsfleFieldPolicy list, a key vault MongoCredentialReference and the key vault namespace. MongoCsfleClientFactory builds the encrypted client settings from it: the $jsonSchema is generated from the field policies (a dotted path becomes nested properties) and keyed by the namespace database.collection, and the key vault client is built from the profile's own credential through MongoCredentialResolver.

An automatic-encryption schema names a data key by id, not by alias. The adopter resolves each MongoCsfleFieldPolicy.keyAlias() against the key vault (for example ClientEncryption.getKeyByAltName) and passes the alias → key id map to settingsFor; an alias with no id is refused. Deterministic fields are typed string in the schema.

MongoCsfleMode:

Mode Queryable Trade-off
RANDOMIZED no Same plaintext encrypts differently each time. The safe default.
DETERMINISTIC equality only Same plaintext always yields the same ciphertext, so equality works — and so does frequency analysis.
UNINDEXED no Stored encrypted, excluded from any index.

MongoCsfleFieldPolicy.forPii(field, queryable) defaults to RANDOMIZED when the field is not queried. Deterministic encryption requires a written equalityQueryJustification; the constructor refuses a blank one, naming frequency analysis. A low-cardinality deterministic field (a status, a country, a boolean) leaks its distribution to anyone who can read the collection, which is the party encryption was protecting against.

2. Queryable Encryption

MongoQueryableEncryptionProfile binds a collection to MongoEncryptedFieldDescriptor entries. MongoQueryableEncryptionQueryType has exactly two values:

  • EQUALITY
  • RANGE — must declare its domain (min, max). The constructor refuses a range field without one, because changing the domain later means re-encrypting the field.

MongoQueryableEncryptionCollectionManager owns the collection's lifecycle, because a QE collection is not just a collection: it carries metadata collections.

3. Metadata ownership

MongoEncryptionMetadataOwnership maps customers to enxcol_.customers.esc and enxcol_.customers.ecoc, and reports __safeContent__-prefixed indexes as MongoMetadataOwnership.ENCRYPTION_MANAGED.

These are never application-owned and never droppable by drift reconciliation. A drift tool that drops enxcol_.customers.ecoc corrupts the collection's queryability. This is the single most important integration point between encryption and ADR-MONGO-004.

4. Unsupported combinations

Refused at declaration, not discovered at runtime:

Combination Why
CSFLE and QE on the same collection Two incompatible encryption schemes over one namespace. Both profile constructors refuse it.
CSFLE on a time series collection requireNotTimeSeries(true) raises MongoOperationRejectedException.
QE prefix / suffix / substring Not available on the platform's 8.0 baseline. The factory methods throw UnsupportedOperationException rather than returning a profile that fails later.
Deterministic CSFLE without a justification IllegalArgumentException naming frequency analysis.
Range QE without a declared domain IllegalArgumentException naming re-encryption.

5. Failure recovery

Symptom Cause Action
MongoEncryptionException on read Wrong data key, or the key vault is unreachable Check KMS reachability and the key vault credential. Data is intact; the client cannot decrypt it.
MongoEncryptionException on write KMS permission revoked mid-operation Restore the grant. Writes fail closed — nothing was written in plaintext.
Queries return nothing on a deterministic field The field was re-keyed Equality matching is over ciphertext; a new key produces different ciphertext. Re-encrypt the field.
QE queries fail after a drift reconciliation A metadata collection was dropped Restore from backup. This is why ownership gates drops.

Key rotation. Rotating the customer master key re-wraps the data keys and does not require re-encrypting documents. Rotating a data key does require re-encrypting every document that used it. These are different operations with different costs, and confusing them is how a rotation becomes an outage.

6. Promotion evidence

Per ADR-MONGO-ADV-001, promotion requires the real KMS and key vault, plus negative cases that fail closed: wrong key, missing permission, rotation mid-operation. A local key provider certifies none of these — it never rejects anything.