Client-Side Field Level Encryption

Supported Encryption Methods

MongoDB supports two methods of client-side field level encryption using the official MongoDB 4.2+ compatible drivers:

Explicit (manual) encryption of fields

Official 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.

For more information, see Explicit (Manual) Client-Side Field Level Encryption.

Automatic encryption of fields

Note

Enterprise Feature

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, mongosh, and the MongoDB 4.2 or later legacy mongo shell support automatically encrypting fields in read and write operations.

Applications must create a database connection object (e.g. MongoClient) with the automatic encryption configuration settings. The configuration settings must include automatic 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 the read/write operation. See Automatic Encryption Rules for complete documentation on automatic encryption rules.

For more information, see Automatic Client-Side Field Level Encryption.

MongoDB 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell automatically decrypt Binary subtype 6 objects created using client-side field level encryption. For more information on automatic decryption, see Automatic Field Decryption.

Encryption Components

The following diagram illustrates the relationships between the driver and each encryption component:

• libmongocrypt is the Apache-licensed open-source core cryptography library used by the official MongoDB 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell for powering client-side field level encryption. Some drivers may require specific integration steps to install or link the library. Defer to driver documentation for more complete information.

• The Automatic Encryption Shared Library supports Automatic Client-Side Field Level Encryption and is only available with MongoDB Enterprise. Automatic Encryption Shared Library does not perform cryptographic functions. The shared library is a preferred alternative to mongocryptd and does not require spawning a new process. mongocryptd is still supported.

• The Key Vault is a MongoDB collection that stores all data encryption keys used to encrypt values. Data encryption keys are themselves encrypted using a Customer Master Key (CMK) prior to storage in the collection. The key vault may reside on a different MongoDB cluster than the one storing the encrypted data.

• The Key Management Service (KMS) stores the Customer Master Key (CMK) used to encrypt data encryption keys. MongoDB supports the following KMS providers:

  • Amazon Web Services KMS

  • Azure Key Vault

  • Google Cloud Platform KMS

  • Locally Managed Key

• The MongoDB cluster which stores the encrypted data may also enforce client-side field level encryption. See Enforce Field Level Encryption Schema for more information.

Encryption Algorithms

MongoDB client-side field level encryption uses the encrypt-then-MAC approach combined with either a deterministic or random initialization vector to encrypt field values. MongoDB only supports the AEAD AES-256-CBC encryption algorithm with HMAC-SHA-512 MAC.

{
 "personal_information" : {
   "ssn" : "123-45-6789",
   "credit_score" : 750,
   "credit_cards" : [ "1234-5678-9012-3456", "9876-5432-1098-7654"]
 },
 "phone_numbers" : [ "(212) 555-0153" ]
}

Automatic Field Decryption

The BinData blob metadata includes the data encryption key _id and encryption algorithm used to encrypt the binary data. The 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell use this metadata to attempt automatic decryption of BinData subtype 6 objects. The automatic decryption process works as follows:

1. Check the BinData blob metadata for the data encryption key and encryption algorithm used to encrypt the value.

2. Check the key vault configured in the current database connection for the specified data encryption key. If the key vault does not contain the specified key, automatic decryption fails and the driver returns the BinData blob.

3. Check the data encryption key metadata for the Customer Master Key (CMK) used to encrypt the key material.

4. For the Amazon Web Services KMS, Azure Key Vault, or Google Cloud Platform KMS, send the data encryption key to the KMS provider for decryption. If the CMK does not exist or if the connection configuration does not grant access to the CMK, decryption fails and the driver returns the BinData blob.

   For the Locally Managed Key, retrieve the local key and decrypt the data encryption key. If the local key specified in the database configuration was not used to encrypt the data encryption key, decryption fails and the driver returns the BinData blob.

5. Decrypt the BinData value using the decrypted data encryption key and appropriate algorithm.

Applications with access to the MongoDB server that do not also have access to the required master key and data encryption keys cannot decrypt the BinData values.

For more information on configuring the database connection for client-side field level encryption, see the Mongo() constructor or defer to the documentation for your preferred driver's client construction method.

Enforce Field Level Encryption Schema

Starting with MongoDB 4.2, the server supports using schema validation to enforce encryption of specific fields in a collection. Use the automatic encryption rule keywords with the $jsonSchema validation object to indicate which fields require encryption. The server rejects any write operations to that collection where the specified fields are not Binary (BinData) subtype 6 objects.

For example, the following collMod command modifies the hr.employees collection to include a validator. The $jsonSchema validation object includes client-side field level encryption keywords to indicate that:

• The taxid field must be encrypted. Clients should use the specified data encryption key and the randomized encryption algorithm when encrypting the field.

• The taxid-short field must be encrypted. Clients should use the specified data encryption key and the deterministic encryption algorithm when encrypting the field.

db.getSiblingDB("hr").runCommand(
  {
    "collMod" : "employees",
    "validator" : {
      "$jsonSchema" : {
        "bsonType" : "object",
        "properties" : {
          "taxid" : {
            "encrypt" : {
              "keyId" : [UUID("e114f7ad-ad7a-4a68-81a7-ebcb9ea0953a")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
            }
          },
          "taxid-short" : {
            "encrypt" : {
              "keyId" : [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
)

Clients performing explicit (manual) field level encryption must encrypt at minimum the taxid and taxid-short fields using the same settings as the remote $jsonSchema prior to issuing the write operation.

Clients performing automatic client-side field level encryption have specific behavior depending on the database connection configuration:

• If the connection ClientSideFieldLevelEncryptionOptions schemaMap object contains a key for the specified collection, the client uses that object to perform automatic field level encryption and ignores the remote schema. The local rules must encrypt at minimum those the taxid and taxid-short fields.

• If the connection ClientSideFieldLevelEncryptionOptions schemaMap object 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.

Since the MongoDB server cannot decrypt nor introspect the contents of the encrypted field, it cannot validate that clients used the specified encryption options to encrypt a given field. This allows two clients to insert encrypted data using different keyIDs or encryption algorithms for a specific field. While some workloads may require independent field level encryption implementations, inconsistent implementation of encryption options for a field across clients may result in incorrect or unexpected behavior of queries against the encrypted field.

For example, client A encrypts the PII field using random encryption while client B encrypts the PII field using deterministic encryption. The randomized encryption algorithm always returns a different unique value while the deterministic algorithm always returns the same value. Queries expecting deterministically encrypted data for that field return inconsistent results, as the server cannot match any of the randomly encrypted fields.

Driver Compatibility Table

MongoDB 4.2 client-side field level encryption is only available with the following official 4.2+ compatible driver versions:

Please refer to the driver reference documentation for syntax and implementation examples.