Read/Write Support with Automatic Field Level Encryption

On this page本页内容

Enterprise Feature

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

New in version 4.2.版本4.2中的新功能。

This page documents the specific commands, query operators, update operators, aggregation stages, and aggregation expressions supported by 4.2-compatible drivers configured for automatic client-side field level encryption.

MongoDB stores client-side field level encrypted fields as a BinData blob. Read and write operations issued against the encrypted BinData value may have unexpected or incorrect behavior as compared to issuing that same operation against the decrypted value. Certain operations have strict BSON type support where issuing them against a BinData value returns an error.

Supported Read and Write Commands

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

For any supported command, 4.2-compatible drivers return an error if the command uses an unsupported operator, aggregation stage, or aggregation expression:

The following commands do not require automatic encryption. Official MongoDB 4.2-compatible drivers configured for automatic client-side field level encryption pass these commands directly to the mongod:

Issuing any other command through a 4.2-compatible driver configured for automatic client-side field level encryption returns an error.

[1]While automatic client-side field level encryption does not encrypt the getMore command, the response to the command may contain encrypted field values. Applications configured with the correct client-side field level encryption options automatically decrypt those values. Applications without the correct encryption options only see the encrypted values.

Supported Query Operators

Official 4.2-compatible drivers configured for automatic client-side field level encryption allow the following query operators when issued against deterministically encrypted fields:

Queries that compare an encrypted field to null or a regular expression always throw an error even if using a supported query operator. Queries issuing these operators against a randomly encrypted field throw an error.

The $exists operator has normal behavior when issued against both deterministically and randomly encrypted fields.

Queries specifying any other query operator against an encrypted field return an error.

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

Supported Update Operators

Official 4.2-compatible drivers configured for automatic client-side field level encryption allow the following update operators when issued against deterministically encrypted fields:

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

Updates specifying any other update operator against an encrypted field return an error.

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

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

Unsupported Insert Operations

Official MongoDB 4.2-compatible drivers configured for automatic client-side field level encryption do not support insert commands with the following behavior:

Supported Aggregation Stages

Official MongoDB 4.2-compatible drivers configured for automatic client-side field level encryption support the following aggregation pipeline stages:

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

For each supported pipeline stage, MongoDB tracks fields that must be encrypted as they pass through the supported pipelines and marks them for encryption.

Each supported stage must specify only supported query operators and aggregation expressions.

$group Behavior

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

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

$lookup and $graphLookup Behavior

Automatic client-side field level encryption supports the $lookup and $graphLookup only if the from collection matches the collection on which the aggregation runs against (i.e. self-lookup operations).

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

Supported Aggregation Expressions

Official 4.2-compatible drivers configured for automatic client-side field level encryption allow aggregation stages using the following expressions against deterministically encrypted fields:

All other aggregation expressions return an error if issued against encrypted fields.

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

ExpressionsRejected BehaviorExample示例

$cond

$switch

 The expression specifies a field whose encryption properties cannot be known until runtime and a subsequent aggregation stage 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 an encrypted field and operates on that new field in the same expression. 
{
  $eq : [
    {"newField" : "$encryptedField"},
    {"newField" : "value"
  ]
}

$eq

$ne

 The expression references the prefix of an encrypted field within 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 encrypted field 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 for automatic client-side field level encryption do not support any read or write operation that requires encrypting the following value types:

Encryption does not adequately hide the type information for these values.

Automatic field level encryption also does not support read or write operations on a deterministically field where the operation compares the encrypted field to the following value types: