Explicit (Manual) 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.

Overview

MongoDB 4.2-compatible drivers and the 4.2 mongo shellsupport explicitly encrypting or decrypting fields with a specificdata encryption key and encryption algorithm.

Applications must modify any code associated with constructing read andwrite operations to include encryption/decryption logic via the driverencryption library. Applications are responsible for selecting theappropriate data encryption key for encryption/decryption on aper-operation basis.

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

MongoDB 4.2-compatible drivers have specific syntax for performingexplicit client-side field level encryption. Refer to thedocumentation for your preferreddriver for tutorials and reference documentation.

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

  1. clientEncryption = encryptedClient.getClientEncryption()
  2.  
  3. db.getSiblingDB("hr").getCollection("employees").insertOne({
  4.   "name" : "J. Doe",
  5.   "taxid" : clientEncryption.encrypt(
  6.       UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  7.       "123-45-6789",
  8.       "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
  9.    )
  10. })

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

  1. encrypt = encryptedClient.getClientEncryption()
  2.  
  3. db.getSiblingDB("hr").getCollection("employees").findOne({
  4.   "taxid" : clientEncryption.encrypt(
  5.      UUID("64e2d87d-f168-493c-bbdf-a394535a2cb9"),
  6.      "123-45-6789",
  7.      "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
  8.    )
  9. })

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

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

Each official MongoDB 4.2-compatible driver introduces new functionalityfor supporting client-side field level encryption and data encryptionkey management. Defer to your preferred driver’s documentation for language-specific instructions onimplementing explicit 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 Client-Side Encryption Enabled.

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. If the collection validation $jsonSchemarequires encryption for a field, clients performing explicit (manual)field level encryption mustencrypt encrypt that field.

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