Summary

Improve API to enable Explicit Encryption:

• Deprecate confusing bypass options in AutoEncryptionOpts.
• Support QE explicit encryption and decryption on the same MongoClient.

Motivation

Motivated by discussions with brett.gray@mongodb.com and my own gripes with the explicit encryption API:

• bypassAutoEncryption and bypassQueryAnalysis are unintuitive. They describe an implementation detail rather than the user intent ("I want to use explicit encryption").
• QE explicit encryption requires AutoEncryptionOpts despite no auto encryption occurring.
• Enabling QE explicit encryption also enables auto decryption. Doing explicit decryption requires a separate MongoClient.

Draft API

Idea: a separately named ExplicitEncryptionOpts:

// New!
class ExplicitEncryptionOpts {
    // Includes options of AutoEncryptionOpts except bypassAutoEncryption, bypassQueryAnalysis, and extraOptions.
}

// New!
AutoDecryption: Optional<Boolean> // Set on MongoClient. Implicitly true if AutoEncryptionOpts or ExplicitEncryptionOpts are set.

class AutoEncryptionOpts {
    bypassAutoEncryption: Optional<Boolean>; // Deprecated. Use AutoDecryption=true.
    bypassQueryAnalysis: Optional<Boolean>;  // Deprecated. Use ExplicitEncryptionOpts. 
}

I think prototyping is needed for a serious proposal.

History

bypassAutoEncryption was added to support explicit encryption for CSFLE and automatic decryption. It bypasses libmongocrypt command processing entirely.

bypassQueryAnalysis was added to support explicit encryption for QE:

• QE uses libmongocrypt to add a required encryptionInformation field, which is omitted if the command does not have QE payloads.
• QE uses libmongocrypt to process cleanup and compact commands.

Why is bypassQueryAnalysis needed? describes motivation for the bypassQueryAnalysis option:

A rejected alternative to adding bypassQueryAnalysis is to change the behavior of bypassAutoEncryption [...] bypassAutoEncryption bypasses all of libmongocrypt for commands. Changing the behavior of bypassAutoEncryption could harm performance

Who is the affected end user?

Users of CSFLE / QE using explicit encryption. Explicit encryption is the only option when not using mongocryptd/crypt_shared. mongocryptd/crypt_shared require using Atlas or having an enterprise license.

Discussion during the DBX off-site in 2025 suggested an opinion that explicit encryption is not commonly used. Instead it serves as an escape hatch and a way to audit CSFLE / QE without enterprise or Atlas. However, explicit encryption may be a first-touch experience for users. It is taught in the QE course M054.

How does this affect the end user?

Confused.

How likely is it that this problem or use case will occur?

I expect likely for anyone using explicit encryption.

If the problem does occur, what are the consequences and how severe are they?

The usability difficulties might deter users from trying QE/CSFLE.

Is this issue urgent?

No.

Is this ticket required by a downstream team?

No?

Is this ticket only for tests?

No.

Acceptance Criteria

TBD. I expect this project (if acceptable) would need further research and a scope document. These API ideas have not been prototyped or reviewed.