Navigation
This is an upcoming (i.e. in progress) version of the manual.
  • Security >
  • Client-Side Field Level Encryption

Client-Side Field Level Encryption

On this page

BETA

Client-Side Field Level Encryption is available as a Beta. More detailed information, including tutorials and references, will become available with future 4.2 Release Candidates.

MongoDB TLS encryption protects data during transmission between clients and the server. The MongoDB Enterprise Encrypted Storage Engine and/or operating system-level encryption protects data at rest on the storage volume. However, a user with privileged access to either the MongoDB server or the host machine may be able to bypass the encryption and read data that is private, privileged, or confidential.

Consider the following scenarios:

  • An employee has administrative access to the host machine and server. 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 server. The provider has a server 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, 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 encryption or other security barriers are bypassed.

New in version 4.2.

The MongoDB 4.2-series drivers provide a client-side field level encryption framework. The MongoDB 4.2 server can detect encrypted fields for the purpose of enforcing encryption via Schema Validation, but cannot decrypt the data. MongoDB client-side field level encryption uses a Customer Master Key (CMK) managed via a Key Management Service (KMS) to support data encryption and decryption.

  • MongoDB 4.2 Community supports explicit encryption of fields using a built-in encryption framework.
  • MongoDB 4.2 Enterprise also supports automatic field encryption using client-side JSON Schema and encryption-specific keywords.

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:

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

A user with access to the MongoDB server that does not have access to the required keys cannot decrypt any encrypted field.

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

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).
  • Optional A MongoDB cluster storing a JSON Schema with encryption validation rules.
  • A MongoDB cluster storing the key vault of data keys. Your key vault cluster can differ from the cluster in which you store client-encrypted data.
  • The mongocryptd daemon for supporting automatic encryption. Included in MongoDB Enterprise only.
  • The libmongocrypt library that manages encryption, decryption, and communication between the KMS and mongocryptd. Included with MongoDB 4.2 drivers.

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

Diagram of relationships between driver and encryption components