Read/Write Support with Automatic Field Level Encryption

Read/Write Support with Automatic Field Level Encryption

beta

Client-Side Field Level Encryption is available as a beta. The contentsof this page may change during the beta period.

Enterprise Feature

The automatic feature of field level encryption is only availablein MongoDB 4.2 Enterprise and MongoDB Atlas 4.2 clusters.

New in version 4.2.

This page documents the specific commands, query operators, updateoperators, aggregation stages, and aggregation expressions supported by4.2-compatible drivers configured for automatic client-side field levelencryption.

MongoDB stores client-side field level encrypted fields as aBinData blob. Read and write operations issuedagainst the encrypted BinData value may have unexpected or incorrectbehavior as compared to issuing that same operation against thedecrypted value. Certain operations have strict BSON type supportwhere issuing them against a BinData value returns an error.

Official 4.2-compatible drivers using automatic client-side fieldlevel encryption parse read/write operations for operators orexpressions that do not support BinData values or that haveabnormal behavior when issued against BinData values.
Applications using explicit (manual) client-sidefield level encryption may use this page as guidance for issuingread/write operations against encrypted fields.

Supported Read and Write Commands

Official MongoDB 4.2-compatible drivers supportautomatic client-side field level encryption with the following commands:

For any supported command, 4.2-compatible drivers return an errorif the command uses an unsupported operator, aggregation stage, oraggregation expression:

The following commands do not require automatic encryption. OfficialMongoDB 4.2-compatible drivers configured for automatic client-sidefield level encryption pass these commands directly to themongod:

Issuing any other command through a4.2-compatible driver configured for automatic client-side field levelencryption returns an error.

[1] While automatic client-side field level encryption does not encryptthe getMore command, the response to the command maycontain encrypted field values. Applications configured with thecorrect client-side field level encryption optionsautomatically decrypt those values.Applications without the correct encryption options only see theencrypted values.

Supported Query Operators

Official 4.2-compatible drivers configured for automatic client-sidefield level encryption allow the following query operators when issuedagainst deterministicallyencrypted fields:

Queries that compare an encrypted field to null or a regularexpression always throw an error even if using a supported queryoperator. Queries issuing these operators against a randomly encrypted field throw an error.

The $exists operator has normal behavior when issuedagainst both deterministically andrandomly encrypted fields.

Queries specifying any other query operator against an encrypted fieldreturn an error.

The following query operators throw an error even if not issuedagainst an encrypted field:

Supported Update Operators

Official 4.2-compatible drivers configured for automatic client-sidefield level encryption allow the following update operators whenissued against deterministically encrypted fields:

For update operations using the $rename operator on encryptedfields, ensure that the automatic JSON schema specifies the sameencryption metadata for the source and target field names.

Updates specifying any other update operator against an encrypted fieldreturn an error.

Update operations with the following behavior throw an erroreven if using a supported operator:

The update operation produces an array inside of an encrypted path.
The update operation uses aggregation expression syntax.

For update operations specifying a query filter on deterministically encrypted fields, the queryfilter must use only supported operators on those fields.

Unsupported Insert Operations

Official MongoDB 4.2-compatible drivers configured for automaticclient-side field level encryptiondo not support insert commands with the following behavior:

Inserting a document with Timestamp(0,0) associated to anencrypted field. The (0,0) value indicates that themongod should generate the Timestamp. Since themongod cannot generated encrypted fields, theresulting timestamp would be unencrypted.
Inserting a document without an encrypted id _if the configuredautomatic schema specifies an encrypted _id field. Sincethe mongod autogenerates an unencryptedObjectId, omitting _id from documents resultsin documents that do not conform to the automatic encryption rules.
Inserting a document with an array associated to adeterministicallyencrypted field. Automatic client-side field level encryption does notsupport deterministically encrypting arrays.

Supported Aggregation Stages

Official MongoDB 4.2-compatible drivers configured forautomatic client-side field level encryption support the followingaggregation pipeline stages:

$limit
$match
$group (see$group Behaviorfor usagerequirements.)
$sample
$skip
$sort
$project
$addFields
$geoNear
$collStats
$indexStats
$bucket
$bucketAuto
$unwind
$sortByCount
$count
$replaceRoot
$redact
$lookup and $graphLookup (See$lookup and $graphLookup Behaviorfor usage requirements)

Aggregation pipelines operating on collections configured for automaticencryption that specify any other stage return an error.

For each supported pipeline stage, MongoDB tracks fields thatmust be encrypted as they pass through the supported pipelines andmarks them for encryption.

Each supported stage must specify only supportedquery operators andaggregation expressions.

$group Behavior

$group has the following behaviors specific to client-sidefield level encryption:

Supports grouping on deterministically encrypted fields.
Does not support arithmetic accumulators on encrypted fields.
Supports $addToSet and $push accumulators onencrypted fields. Does not support matching on the resulting array.

$lookup and $graphLookup Behavior

Automatic client-side field level encryption supports the$lookup and $graphLookuponly if thefrom collection matches the collection on which the aggregationruns against (i.e. self-lookup operations).

$lookup and $graphLookup stages thatreference a different from collection return an error.

Supported Aggregation Expressions

Official 4.2-compatible drivers configured for automatic client-sidefield level encryption allow aggregation stages using the followingexpressions against deterministically encrypted fields:

All other aggregation expressions return an error if issued againstencrypted fields.

Aggregation stages with the following behavior throw an erroreven if using a supported aggregation expression:

Expressions	Rejected Behavior	Example
`$cond$switch`	The expression specifies a field whose encryption propertiescannot be known until runtime and a subsequent aggregationstage includes an expression referencing that field.	$addFields : { "valueWithUnknownEncryption" : { $cond : { if : { "$encryptedField" : "value" }, then : "$encryptedField", else: "unencryptedValue" } }},{ $match : { "valueWithUnknownEncryption" : "someNewValue" }}
`$eq$ne`	The expression creates a new field that references anencrypted field and operates on that new field in the sameexpression.	{ $eq : [ {"newField" : "$encryptedField"}, {"newField" : "value" ]}
`$eq$ne`	The expression references the prefix of an encrypted fieldwithin the comparison expression.	{ $eq : [ "$prefixOfEncryptedField" , "value"] }
`$eq$ne`	The result of the expression is compared an encrypted field.	{ $eq : [ "$encryptedField" , { $ne : [ "field", "value" ] } ]}
`$let`	The expression binds a variable to an encryptedfield or attempts to rebind `$$CURRENT`.	{ $let: { "vars" : { "newVariable" : "$encryptedField" } }}
`$in`	The first argument to the expression is an encrypted field,and-The second argument to the expression is not an array literal-OR--The second argument to the expression is an encrypted field.	{ $in : [ "$encryptedField" , "$otherEncryptedField" ]}

Unsupported Field Types

Official MongoDB 4.2-compatible drivers configured forautomatic client-side field level encryption do not support any read or writeoperation that requires encrypting the following value types:

MaxKey
MinKey
null
undefined

Encryption does not adequately hide the type information for thesevalues.

Automatic field level encryption also does not support read or writeoperations on a deterministically field where the operationcompares the encrypted field to the following value types:

double
decimal128
bool
object
array
javascriptWithScope