Navigation
  • Security >
  • Client-Side Field Level Encryption

Client-Side Field Level Encryption

beta

Client-Side Field Level Encryption is available as a beta. The contents of this page may change during the beta period.

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")
}

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:

Automatic encryption of fields

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.

MongoDB 4.2-compatible drivers and the 4.2 mongo shell automatically decrypt Binary subtype 6 BinData 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.

Automatic Field Level Encryption

Enterprise Feature

Available in MongoDB Enterprise only.

Official MongoDB 4.2-compatible drivers support automatic client-side field level encryption. Applications configured for automatic client-side field level encryption identify specific fields in documents for encryption. 4.2 drivers use the automatic encryption rules specified to the client for identifying encrypted fields and their associated encryption keys.

For write operations, 4.2 drivers encrypt field values prior to writing to the MongoDB database. For read operations, 4.2 drivers encrypt field values in the query prior to issuing the read operation. 4.2 drivers can automatically decrypt encrypted values returned in a document only if the client has access to the keys used to protect those values.

Applications must specify the following components when instantiating the client to enable automatic client-side field level encryption:

  • A MongoDB cluster storing the key vault of data keys.

  • The key vault namespace (<database>.<collection>) used to store encrypted data keys.

  • A supported Key Management Service (KMS) provider used to manage Customer Master Keys (CMK). MongoDB encrypts all data keys using the specified CMK prior to storing them in the key vault, leaving only metadata unencrypted.

    Drivers need access to the KMS to encrypt and decrypt protected fields or to create new data keys.

  • Per-field encryption rules using JSON schema syntax.

The 4.2-compatible drivers use the Enterprise-only mongocryptd process to parse the JSON schema and apply the encryption rules when reading or writing documents. Automatic encryption requires the mongocryptd process.

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

Automatic Field Decryption

MongoDB 4.2-compatible drivers and the 4.2 mongo shell automatically decrypt BinData subtype 6 fields created using client-side field level encryption.

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 automatically decrypt BinData type 6 fields. The automatic decryption process works as follows:

  1. Retrieve the data key used to encrypt the value from the BinData blob metadata.
  2. Check the key vault configured in the current database connection for the specified data key. MongoDB encrypts data keys with a Customer Master Key prior to storing them in the key vault.
  3. Retrieve the unique identifier of the CMK from the data key metadata.
  4. Use the Key Management Service (KMS). configured in the current database connection to decrypt the data key using the CMK.
  5. Decrypt the BinData value using the decrypted data key.

Applications with access to the MongoDB server that do not also have access to the required keys cannot decrypt the BinData.

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.

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

Encryption Components

MongoDB client-side field level encryption uses the following components:

  • A third-party Key Management Service (KMS) for storing and retrieving a Customer Master Key (CMK).
  • A key vault of data keys.
  • The libmongocrypt library that manages encryption, decryption, and communication between the KMS and mongocryptd. Included with MongoDB 4.2 drivers.
  • The mongocryptd daemon for supporting automatic encryption. Included in MongoDB Enterprise only.
  • Optional Server-side JSON Schema that specifies encryption validation rules.

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

Diagram of relationships between driver and encryption components

Supported Key Management Services

Client-side field level encryption requires a Key Management Service (KMS) for accessing a Customer Master Key (CMK). MongoDB automatically encrypts data keys using the specified CMK during data key creation.

Deleting the CMK renders all data keys encrypted with that CMK as permanently unreadable, which in turn renders all values encrypted with those data keys as permanently unreadable.

Client-side field level encryption supports the following KMS providers:

Amazon Web Services KMS

MongoDB client-side encryption supports using the Amazon Web Services Key Management Service for encrypting and decrypting data keys. Specifically, MongoDB securely transmits the data key to AWS KMS for encrypting or decrypting using the specified Customer Master Key (CMK). The CMK never leaves the AWS KMS.

The mongo shell supports two methods for configuring access to an AWS KMS:

Configuring access to an AWS KMS requires at minimum an AWS access key and its corresponding secret key. The IAM user associated to the access key must have at least one policy with the following actions:

Implement Seperation of Least Privilege for KMS Access

Consider configuring IAM user roles such that MongoDB has only the access to the actions and resources required to function.

For example, the following policy JSON scopes the required actions to a single CMK:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:Encrypt"
            ],
            "Resource": "arn:aws:kms:region:account:key/12a345b6-cd7e-8f9g-0h1i-jk23l45mn6o7"
        }
    ]
}

For complete documentation on data key management using AWS KMS, see Manage Client-Side Encryption Data Keys.

Locally Managed Key

The mongo shell supports specifying a locally managed key as a KMS using the Mongo() constructor. The local key must be a 96-byte long string.

For complete documentation on data key management using the local keyfile, see Manage Client-Side Encryption Data Keys.

Key Vault

The key vault is a collection that stores data keys for use with client-side field level encryption. Data keys are encrypted using a Customer Master Key (CMK) managed through a supported Key Management System (KMS).

The mongo shell provides helper methods for data key management:

Retrieving Data Keys
Creating or Modifying Data Keys

Removing Data Keys

Important

Removing a data key renders all fields encrypted using that data key as permanently unreadable.

Applications with read access to the key vault collection can retrieve data keys by querying the collection. However, only applications with access to the CMK used to encrypt a data key can use that key for encryption or decryption.

By default MongoDB stores the key vault collection on the connected cluster. MongoDB also supports specifying a remote cluster as the key vault. Applications must have access to both the remote key vault cluster and the connection cluster to perform client-side field level encryption operations.

Data keys have the following structure:

{
  "_id" : UUID("<string>"),
  "keyMaterial" : BinData(0,"<encrypted binary data string>"),
      "creationDate" : ISODate("2019-08-20T15:45:02.575Z"),
      "updateDate" : ISODate("2019-08-20T15:45:02.575Z"),
      "status" : <int>,
      "version" : NumberLong(0),
      "masterKey" : {
        "provider" : "<string>",
        "key" : "<string>",
        "region" : "<string>",
        "endpoint" : "<string>"
      },
      "keyAltNames" : [
    "<string>"
  ]
}

For complete documentation on data key management, see Manage Client-Side Encryption Data Keys.

mongocryptd

MongoDB Enterprise Only

mongocryptd is a driver-spawned client-side process that parses and validates the JSON schema encryption rules. mongocryptd is a required component in automatic field encryption and is included as a component in the MongoDB Enterprise Server package.

4.2 drivers automatically spawn the mongocryptd process if available on the host system. Applications can control the spawning behavior as part of the automatic encryption options. Defer to the driver documentation for the specific options and syntax for controlling mongocryptd spawning.

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.