Navigation
  • Security >
  • Client-Side Field Level Encryption

Client-Side Field Level Encryption

New in version 4.2.

The official MongoDB 4.2-compatible drivers provide a client-side field level encryption framework. Applications can encrypt fields in documents prior to transmitting data over the wire to the server. Only applications with access to the correct encryption keys can decrypt and read the protected data. Deleting an encryption key renders all data encrypted using that key as permanently unreadable.

For example, a MongoDB cluster enforcing authentication uses TLS encryption to protect data in transit. The cluster also uses the MongoDB encrypted storage engine to secure data on disk. Consider the following scenarios:

  • An employee has administrative access to the cluster and its host machines. The employee’s access level allows them to view high-sensitivity data in a decrypted state as part of their normal duties.
  • A third-party provider hosts the MongoDB cluster. The provider has a host-machine or database-level security breach where unauthorized parties access the data in a decrypted state.
  • A third-party data analytics firm has access to data that includes private, personal, or confidential information. The third-party firm loads the decrypted data into an unsecured data storage volume which unauthorized parties can access.

With each scenario, a user with privileged access to either the MongoDB cluster or a host machine can bypass encryption and read data that is private, privileged, or confidential. Using client-side field level encryption to protect data prior to being written to the server mitigates the risk of exposing that data in the event network or disk encryption is bypassed.

Consider the following document:

{
  "name" : "John Doe",
  "address" : {
    "street" : "1234 Main Street",
    "city" : "MongoDBVille",
    "zip" : 99999
  },
  "phone" : "949-555-1212",
  "ssn" : "123-45-6789"
}

With client-side field level encryption, the application can specifically encrypt sensitive information like the ssn and phone. Encrypted fields are stored as binary data with subtype 6:

{
  "name" : "John Doe",
  "address" : {
    "street" : "1234 Main Street",
    "city" : "MongoDBVille",
    "zip" : 99999
  },
  "phone" : BinData(6,"U2FsdGVkX1+CGIDGUnGgtS46+c7R5u17SwPDEmzyCbA="),
  "ssn" : BinData(6,"AaloEw285E3AnfjP+r8ph2YCvMI1+rWzpZK97tV6iz0jx")
}

See the Client Side Field Level Encryption Guide for an end-to-end procedure for configuring field level encryption using select MongoDB 4.2-compatible drivers.

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

Explicit (manual) encryption of fields

MongoDB 4.2-compatible drivers support explicitly encrypting or decrypting fields with a specific data 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 key for encryption/decryption on a per-operation basis.

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

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

Automatic encryption of fields

Enterprise Feature

The automatic feature of field level encryption is only available in MongoDB 4.2 Enterprise and MongoDB Atlas 4.2 clusters.

MongoDB 4.2 Enterprise extends 4.2-compatible driver encryption support to include automatic field level encryption using JSON schema syntax.

Applications must modify only the driver client object configuration code to include automatic encryption settings. All read/write operations to a cluster via the encryption-configured client are automatically encrypted and decrypted using the predefined automatic encryption rules. Code associated with constructing read and write operations does not require additional modification.

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

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

Important

MongoDB client-side field level encryption only supports encrypting single fields in a document. To encrypt an entire document, you must encrypt each individual field in the document.

Encryption Components

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

Diagram of relationships between driver and encryption components
  • libmongocrypt is the Apache-licensed open-source core cryptography library used by the official MongoDB 4.2-compatible drivers and the 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.
  • mongocryptd supports Automatic Client-Side Field Level Encryption and is only available with MongoDB Enterprise. mongocryptd does not perform cryptographic functions.
  • 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. See Encryption Key Vault for more information.
  • The Key Management System stores the Customer Master Key used to encrypt data encryption keys. See Supported Key Management Services for more information.
  • 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.

Deterministic Encryption

The deterministic encryption algorithm ensures a given input value always encrypts to the same output value each time the algorithm is executed. While deterministic encryption provides greater support for read operations, encrypted data with low cardinality is susceptible to frequency analysis recovery.

For sensitive fields that are not used in read operations, applications may use Random Encryption for improved protection from frequency analysis recovery.

Random Encryption

The random encryption algorithm ensures that a given input value always encrypts to a different output value each time the algorithm is executed. While random encryption provides the strongest guarantees of data confidentiality, it also prevents support for any read operations which must operate on the encrypted field to evaluate the query.

Random encryption also supports encrypting entire objects or arrays. For example, consider the following document:

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

Encrypting the personal_information and phone_numbers fields using the random encryption algorithm encrypts the entire object. While this protects all fields nested under those fields, it also prevents querying against those nested fields.

For sensitive fields that are used in read operations, applications must use Deterministic Encryption for improved read support on encrypted fields.

Automatic Field Decryption

The BinData blob metadata includes the data key _id and encryption algorithm used to encrypt the binary data. The 4.2-compatible drivers and 4.2 mongo shell use this metadata to attempt automatic decryption BinData type 6 values. The automatic decryption process works as follows:

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

  2. Check the key vault configured in the current database connection for the specified data 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 key metadata for the Customer Master Key used to encrypt the key material.

  4. For the Amazon Web Services KMS, send the data key to the KMS service 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 key. If the local key specified in the database configuration was not used to encrypt the data key, decryption fails and the driver returns the BinData blob.

  5. Decrypt the BinData value using the decrypted data 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

The MongoDB 4.2 server supports using schema validation to enforce encryption of specific fields in a collection. Use the automatic client-side field level encryption JSON schema syntax 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 key and the Random encryption algorithm when encrypting the field.
  • The taxid-short field must be encrypted. Clients should use the specified data 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:

Automatic client-side field level encryption is available with MongoDB 4.2 Enterprise only.
  • 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 random 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 with automatic field encryption is available in the following driver versions:

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