Docs Home → Develop Applications → MongoDB Manual
Explicit (Manual) Client-Side Field Level Encryption
On this page
Overview
MongoDB 4.2+ compatible drivers, mongosh
, and the MongoDB
4.2 or later legacy 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.
mongosh
provides the following methods for
performing explicit encryption and decryption:
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 mongosh
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 mongosh
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.
mongosh
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,
mongosh
, and the MongoDB 4.2 or later legacymongo
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.