Automatic Client-Side 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.

Overview

Official MongoDB 4.2-compatible drivers and the MongoDB 4.2mongo shell support automatic client-side field levelencryption. Applications configured for automatic client-side fieldlevel encryption identify specific fields in documents for encryption.4.2 drivers use the automatic encryption rules specified to the clientfor identifying encrypted fields and their associated encryption keys.

Automatic client-side field level encryption requires specifyingper-field encryption rules using a strict subset ofJSON Schema Draft 4 standard syntaxand encryption-specific schema keywords. SeeAutomatic Encryption Rules for complete documentation.

The official MongoDB 4.2-compatible drivers and 4.2 mongoshell use the Enterprise-only mongocryptdprocess to parse the automatic encryption rules and apply the encryptionrules 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 thequery prior to issuing the read operation.
  • For read operations that returns encrypted fields, the driver/shellautomatically decrypts the encrypted valuesonly if the driver/shell was configured with access to the keys usedto protect those values.

Enabling Automatic Client-Side Field Level Encryption

Each official MongoDB 4.2-compatible driver introduces new functionalityfor supporting automatic encryption and data encryption key management.Defer to your preferred driver’s documentation for language-specific instructions onimplementing automatic client-side field level encryption.

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

Automatic client-side field level encryption requires access to themongocryptd process on the client host machine. Seemongocryptd for complete documentation on installation. Theofficial MongoDB 4.2-compatible drivers have additional options formanaging the mongocryptd process. Generally, the 4.2-compatibledrivers and 4.2 mongo shell can access themongocryptd process if it is in the system PATH.

Applications must specify the following components when instantiatingthe database connection to enable automatic client-side field levelencryption:

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

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

4.2-compatible drivers and the 4.2 mongo shell needaccess to the KMS to encrypt and decrypt protected fields or tocreate new data encryption keys.

Server-Side Field Level Encryption Enforcement

The MongoDB 4.2 server supports using schema validation to enforce encryption of specific fields in acollection. Clients performing automatic client-side field levelencryption have specific behaviordepending on the database connection configuration:

  • If the connection ClientSideFieldLevelEncryptionOptionsschemaMap object contains a key for the specified collection, theclient uses that object to perform automatic field level encryptionand ignores the remote schema. The local rules must encrypt atminimum those the taxid and taxid-short fields.

  • If the connection ClientSideFieldLevelEncryptionOptionsschemaMap object does not contain a key for the specifiedcollection, the client downloads the server-side remote schema for thecollection and uses it to perform automatic field level encryption.

This configuration requires the client to trust the server has a validschema with respect to automatic field level encryption. The clientonly uses the remote schema to perform automatic field levelencryption and does not enforce any other validation rules specifiedin the schema.

For complete documentation on server-side client-side field levelencryption enforcement, seeEnforce Field Level Encryption Schema.