Automatic Client-Side Field Level Encryption

Overview

Official MongoDB 4.2+ compatible drivers and the MongoDB 4.2 or later mongo shell support automatically encrypting fields in read and write operations. For a complete list of official 4.2+ compatible drivers with support for client-side field level encryption, see Driver Compatibility Table.

Applications must create a database connection object (e.g. MongoClient) with the automatic encryption configuration settings. The configuration settings must include automatic encryption 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 constructing the read/write operation. See Automatic Encryption Rules for complete documentation on automatic encryption rules.

The official MongoDB 4.2+ compatible drivers and 4.2 or later mongo shell use the Enterprise-only mongocryptd process to parse the automatic encryption rules and apply the encryption rules when reading or writing documents:

• For write operations, the driver/shell encrypts field values prior to writing to the MongoDB database.

• For read operations, the driver/shell encrypts field values in the query prior to issuing the read operation.

• For read operations that returns encrypted fields, the driver/shell automatically decrypts the encrypted values only if the driver/shell was configured with access to the keys used to protect those values.

Enabling Automatic Client-Side Field Level Encryption

Each official MongoDB 4.2+ compatible driver introduces new functionality for supporting automatic encryption and data encryption key management. Defer to your preferred driver's documentation for language-specific instructions on implementing automatic client-side field level encryption.

The MongoDB 4.2 mongo shell adds an additional option to the Mongo() method for instantiating a database connection with automatic client-side field level encryption. For a complete example, see Connect to a MongoDB Cluster with Automatic Client-Side Encryption Enabled.

Automatic client-side field level encryption requires access to the mongocryptd process on the client host machine. See mongocryptd for complete documentation on installation. The official MongoDB 4.2+ compatible drivers have additional options for managing the mongocryptd process. Generally, the 4.2+ compatible drivers and 4.2 or later mongo shell can access the mongocryptd process if it is in the system PATH.

Applications must specify the following components when instantiating the database connection to enable automatic client-side field level encryption:

• A key vault of data encryption keys. The key vault can reside on either a remote MongoDB cluster or the MongoDB cluster storing client-side encrypted data.

• A supported Key Management Service (KMS) provider used to manage Customer Master Keys (CMK). MongoDB encrypts all data encryption keys using the specified CMK prior to storing them in the key vault, leaving only metadata unencrypted.

  4.2+ compatible drivers and the 4.2 or later mongo shell need access to the KMS to encrypt and decrypt protected fields or to create new data encryption keys.

• Per-field automatic encryption rules using JSON schema syntax.

Server-Side Field Level Encryption Enforcement

Starting in MongoDB 4.2, the server supports using schema validation to enforce encryption of specific fields in a collection. Clients performing automatic client-side field level encryption have specific behavior depending on the database connection configuration:

• 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. At minimum, the local rules must encrypt those fields that the remote schema marks as requiring encryption.

• 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.

For complete documentation on server-side client-side field level encryption enforcement, see Enforce Field Level Encryption Schema.