Explicit (Manual) Client-Side Field Level Encryption

Overview

MongoDB 4.2+ compatible drivers and the 4.2 or later 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.

The 4.2 mongo shell provides the following methods for performing explicit encryption and decryption:

• getClientEncryption()

• ClientEncryption.encrypt()

• ClientEncryption.decrypt()

MongoDB 4.2+ compatible drivers have specific syntax for performing explicit client-side field level encryption. See Driver Compatibility Table for a complete list of 4.2+ compatible drivers with support for client-side field level encryption. Defer to the documentation for your preferred driver for specific instructions on performing client-side field level encryption.

The following operation issued from the mongo shell explicitly encrypts the taxid field as part of a write operation.

clientEncryption = encryptedClient.getClientEncryption()
db.getSiblingDB("hr").getCollection("employees").insertOne({
  "name" : "J. Doe",
  "taxid" : clientEncryption.encrypt(
      UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
      "123-45-6789",
      "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
   )
})

The following operation issued from the mongo shell explicitly encrypts the taxid field as part of a read operation:

encrypt = encryptedClient.getClientEncryption()
db.getSiblingDB("hr").getCollection("employees").findOne({
  "taxid" : clientEncryption.encrypt(
     UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
     "123-45-6789",
     "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
   )
})

These operations assumes that the database connection configuration specified a key vault and key management service with access to the specified data encryption key and its associated customer master key.

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 Explicit Client-Side Field Level Encryption

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

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

Applications must specify the following components when instantiating the database connection to enable explicit 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.

Server-Side Field Level Encryption Enforcement

The MongoDB 4.2 server supports using schema validation to enforce encryption of specific fields in a collection. If the collection validation $jsonSchema requires encryption for a field, clients performing explicit (manual) field level encryption must encrypt that field.

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