Automatic Client-Side Field Level Encryption¶
On this page
The automatic feature of field level encryption is only available in MongoDB Enterprise 4.2 or later, and MongoDB Atlas 4.2 or later clusters.
Official MongoDB 4.2+ compatible drivers,
the MongoDB 4.2 or later legacy
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 the MongoDB 4.2 or later legacy
mongo shell use the
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.
mongosh adds an additional option
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
mongocryptd process. Generally, the 4.2+ compatible
mongosh can access the
mongocryptd process if it is in the system
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.
- 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
schemaMapobject 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
schemaMapobject 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.