Security >
Client-Side Field Level Encryption

Client-Side Field Level Encryption¶

On this page

Supported Encryption Methods
Encryption Components
Encryption Algorithms
Automatic Field Decryption
Enforce Field Level Encryption Schema
Driver Compatibility Table

New in version 4.2.

The official MongoDB 4.2-compatible drivers provide a client-side field level encryption framework. Applications can encrypt fields in documents prior to transmitting data over the wire to the server. Only applications with access to the correct encryption keys can decrypt and read the protected data. Deleting an encryption key renders all data encrypted using that key as permanently unreadable.

For example, a MongoDB cluster enforcing authentication uses TLS encryption to protect data in transit. The cluster also uses the MongoDB encrypted storage engine to secure data on disk. Consider the following scenarios:

An employee has administrative access to the cluster and its host machines. The employee’s access level allows them to view high-sensitivity data in a decrypted state as part of their normal duties.
A third-party provider hosts the MongoDB cluster. The provider has a host-machine or database-level security breach where unauthorized parties access the data in a decrypted state.
A third-party data analytics firm has access to data that includes private, personal, or confidential information. The third-party firm loads the decrypted data into an unsecured data storage volume which unauthorized parties can access.

With each scenario, a user with privileged access to either the MongoDB cluster or a host machine can bypass encryption and read data that is private, privileged, or confidential. Using client-side field level encryption to protect data prior to being written to the server mitigates the risk of exposing that data in the event network or disk encryption is bypassed.

Consider the following document:

copy

{
  "name" : "John Doe",
  "address" : {
    "street" : "1234 Main Street",
    "city" : "MongoDBVille",
    "zip" : 99999
  },
  "phone" : "949-555-1212",
  "ssn" : "123-45-6789"
}

With client-side field level encryption, the application can specifically encrypt sensitive information like the ssn and phone. Encrypted fields are stored as binary data with subtype 6:

copy

{
  "name" : "John Doe",
  "address" : {
    "street" : "1234 Main Street",
    "city" : "MongoDBVille",
    "zip" : 99999
  },
  "phone" : BinData(6,"U2FsdGVkX1+CGIDGUnGgtS46+c7R5u17SwPDEmzyCbA="),
  "ssn" : BinData(6,"AaloEw285E3AnfjP+r8ph2YCvMI1+rWzpZK97tV6iz0jx")
}

For a complete list of official 4.2-compatible drivers with support for client-side field level encryption, see Driver Compatibility Table.

For an end-to-end procedure for configuring field level encryption using select MongoDB 4.2-compatible drivers, see the Client Side Field Level Encryption Guide.

Supported Encryption Methods¶

MongoDB supports two methods of client-side field level encryption using the official MongoDB 4.2-compatible drivers:

Explicit (manual) encryption of fields

Official MongoDB 4.2-compatible drivers and the MongoDB 4.2 mongo shell support explicitly encrypting or decrypting fields with a specific data encryption key and encryption algorithm.

Applications must modify any code associated with constructing read and write operations to include encryption/decryption logic via the driver encryption library. Applications are responsible for selecting the appropriate data encryption key for encryption/decryption on a per-operation basis.

For more information, see Explicit (Manual) Client-Side Field Level Encryption.

Automatic encryption of fields

Enterprise Feature

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

Official MongoDB 4.2-compatible drivers and the MongoDB 4.2 mongo shell support automatically encrypting fields in read and write operations.

Applications must create a database connection object (e.g. MongoClient) with the automatic encryption configuration settings. The configuration settings must include automatic encryption rules using a strict subset of the JSON Schema Draft 4 standard syntax and encryption-specific schema keywords. Applications do not have to modify code associated with the read/write operation. See Automatic Encryption Rules for complete documentation on automatic encryption rules.

For more information, see Automatic Client-Side Field Level Encryption.

MongoDB 4.2-compatible drivers and the 4.2 mongo shell automatically decrypt Binary subtype 6 objects created using client-side field level encryption. For more information on automatic decryption, see Automatic Field Decryption.

Important

MongoDB client-side field level encryption only supports encrypting single fields in a document. To encrypt an entire document, you must encrypt each individual field in the document.

Encryption Components¶

The following diagram illustrates the relationships between the driver and each encryption component:

libmongocrypt is the Apache-licensed open-source core cryptography library used by the official MongoDB 4.2-compatible drivers and the mongo shell for powering client-side field level encryption. Some drivers may require specific integration steps to install or link the library. Defer to driver documentation for more complete information.
mongocryptd supports Automatic Client-Side Field Level Encryption and is only available with MongoDB Enterprise. mongocryptd does not perform cryptographic functions.
The key vault is a MongoDB collection that stores all data encryption keys used to encrypt values. Data encryption keys are themselves encrypted using a Customer Master Key (CMK) prior to storage in the collection. The key vault may reside on a different MongoDB cluster than the one storing the encrypted data. See Encryption Key Vault for more information.
The Key Management System stores the Customer Master Key used to encrypt data encryption keys. See Supported Key Management Services for more information.
The MongoDB cluster which stores the encrypted data may also enforce client-side field level encryption. See Enforce Field Level Encryption Schema for more information.

Encryption Algorithms¶

MongoDB client-side field level encryption uses the encrypt-then-MAC approach combined with either a deterministic or random initialization vector to encrypt field values. MongoDB only supports the AEAD AES-256-CBC encryption algorithm with HMAC-SHA-512 MAC.

Deterministic Encryption¶

The deterministic encryption algorithm ensures a given input value always encrypts to the same output value each time the algorithm is executed. While deterministic encryption provides greater support for read operations, encrypted data with low cardinality is susceptible to frequency analysis recovery.

For sensitive fields that are not used in read operations, applications may use Randomized Encryption for improved protection from frequency analysis recovery.

Randomized Encryption¶

The randomized encryption algorithm ensures that a given input value always encrypts to a different output value each time the algorithm is executed. While randomized encryption provides the strongest guarantees of data confidentiality, it also prevents support for any read operations which must operate on the encrypted field to evaluate the query.

Randomized encryption also supports encrypting entire objects or arrays. For example, consider the following document:

copy

{
 "personal_information" : {
   "ssn" : "123-45-6789",
   "credit_score" : 750,
   "credit_cards" : [ "1234-5678-9012-3456", "9876-5432-1098-7654"]
 },
 "phone_numbers" : [ "(212) 555-0153" ]
}

Encrypting the personal_information and phone_numbers fields using the randomized encryption algorithm encrypts the entire object. While this protects all fields nested under those fields, it also prevents querying against those nested fields.

For sensitive fields that are used in read operations, applications must use Deterministic Encryption for improved read support on encrypted fields.

Automatic Field Decryption¶

The BinData blob metadata includes the data encryption key _id and encryption algorithm used to encrypt the binary data. The 4.2-compatible drivers and 4.2 mongo shell use this metadata to attempt automatic decryption BinData type 6 values. The automatic decryption process works as follows:

Check the BinData blob metadata for the data encryption key and encryption algorithm used to encrypt the value.
Check the key vault configured in the current database connection for the specified data encryption key. If the key vault does not contain the specified key, automatic decryption fails and the driver returns the BinData blob.
Check the data encryption key metadata for the Customer Master Key used to encrypt the key material.
For the Amazon Web Services KMS, send the data encryption key to the KMS service for decryption. If the CMK does not exist or if the connection configuration does not grant access to the CMK, decryption fails and the driver returns the BinData blob.

For the Locally Managed Key, retrieve the local key and decrypt the data encryption key. If the local key specified in the database configuration was not used to encrypt the data encryption key, decryption fails and the driver returns the BinData blob.
Decrypt the BinData value using the decrypted data encryption key and appropriate algorithm.

Applications with access to the MongoDB server that do not also have access to the required master key and data encryption keys cannot decrypt the BinData values.

For more information on configuring the database connection for client-side field level encryption, see the Mongo() constructor or defer to the documentation for your preferred driver’s client construction method.

Enforce Field Level Encryption Schema¶

The MongoDB 4.2 server supports using schema validation to enforce encryption of specific fields in a collection. Use the automatic encryption rule keywords with the $jsonSchema validation object to indicate which fields require encryption. The server rejects any write operations to that collection where the specified fields are not Binary (BinData) subtype 6 objects.

For example, the following collMod command modifies the hr.employees collection to include a validator. The $jsonSchema validation object includes client-side field level encryption keywords to indicate that:

The taxid field must be encrypted. Clients should use the specified data encryption key and the randomized encryption algorithm when encrypting the field.
The taxid-short field must be encrypted. Clients should use the specified data encryption key and the deterministic encryption algorithm when encrypting the field.

copy

db.getSiblingDB("hr").runCommand(
  {
    "collMod" : "employees",
    "validator" : {
      "$jsonSchema" : {
        "bsonType" : "object",
        "properties" : {
          "taxid" : {
            "encrypt" : {
              "keyId" : [UUID("e114f7ad-ad7a-4a68-81a7-ebcb9ea0953a")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
            }
          },
          "taxid-short" : {
            "encrypt" : {
              "keyId" : [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
)

Clients performing explicit (manual) field level encryption must encrypt at minimum the taxid and taxid-short fields using the same settings as the remote $jsonSchema prior to issuing the write operation.

Clients performing automatic client-side field level encryption have specific behavior depending on the database connection configuration:

Automatic client-side field level encryption is available with MongoDB 4.2 Enterprise only.

If the connection ClientSideFieldLevelEncryptionOptions schemaMap object contains a key for the specified collection, the client uses that object to perform automatic field level encryption and ignores the remote schema. The local rules must encrypt at minimum those the taxid and taxid-short fields.
If the connection ClientSideFieldLevelEncryptionOptions schemaMap object does not contain a key for the specified collection, the client downloads the server-side remote schema for the collection and uses it to perform automatic field level encryption.

This configuration requires the client to trust the server has a valid schema with respect to automatic field level encryption. The client only uses the remote schema to perform automatic field level encryption and does not enforce any other validation rules specified in the schema.

Since the MongoDB server cannot decrypt nor introspect the contents of the encrypted field, it cannot validate that clients used the specified encryption options to encrypt a given field. This allows two clients to insert encrypted data using different keyIDs or encryption algorithms for a specific field. While some workloads may require independent field level encryption implementations, inconsistent implementation of encryption options for a field across clients may result in incorrect or unexpected behavior of queries against the encrypted field.

For example, client A encrypts the PII field using random encryption while client B encrypts the PII field using deterministic encryption. The randomized encryption algorithm always returns a different unique value while the deterministic algorithm always returns the same value. Queries expecting deterministically encrypted data for that field return inconsistent results, as the server cannot match any of the randomly encrypted fields.

Driver Compatibility Table¶

MongoDB 4.2 client-side field level encryption is only available with the following official 4.2-compatible driver versions:

Driver	Supported Versions	Quickstarts / Tutorials
Node	`3.4.0+`	Node.js Quickstart Client-Side Field Level Encryption Guide
Java	`3.12.0+`	Java Driver Quickstart Java Async Driver Quickstart Client-Side Field Level Encryption Guide
Java Reactive Streams	`1.13.0+`	Java RS Documentation
Python (PyMongo)	`3.10.0+`	Python Driver Quickstart Client-Side Field Level Encryption Guide
C#/.NET	`2.10.0+`	.NET Driver Quickstart
Go	`1.2+`	Go Driver Quickstart
Scala	`2.8.0+`	Scala Documentation
PHP	`1.6.0+`	PHP Driver Quickstart
Ruby	`2.12.1+`	Ruby Driver Quickstart

Please refer to the driver reference documentation for syntax and implementation examples.

← Rotate Encryption Keys Automatic Client-Side Field Level Encryption →