Client-Side Field Level Encryption

New in version 4.2.

The official MongoDB 4.2-compatible drivers provide a client-side fieldlevel encryption framework. Applications can encrypt fields in documentsprior to transmitting data over the wire to the server. Onlyapplications with access to the correct encryption keys can decrypt andread the protected data. Deleting an encryption key renders all dataencrypted using that key as permanently unreadable.

For example, a MongoDB cluster enforcingauthentication usesTLS encryption to protect data in transit.The cluster also uses theMongoDB encrypted storage engine tosecure data on disk. Consider the following scenarios:

  • An employee has administrative access to the cluster and its hostmachines. The employee’s access level allows them to viewhigh-sensitivity data in a decrypted state as part of their normalduties.
  • A third-party provider hosts the MongoDB cluster. The providerhas a host-machine or database-level security breach whereunauthorized parties access the data in a decrypted state.
  • A third-party data analytics firm has access to data that includesprivate, personal, or confidential information. The third-partyfirm loads the decrypted data into an unsecured data storage volumewhich unauthorized parties can access.

With each scenario, a user with privileged access to either the MongoDBcluster or a host machine can bypass encryption and read data that isprivate, privileged, or confidential. Using client-side field levelencryption to protect data prior to being written to the servermitigates the risk of exposing that data in the event network or diskencryption is bypassed.

Consider the following document:

  1. {
  2.   "name" : "John Doe",
  3.   "address" : {
  4.     "street" : "1234 Main Street",
  5.     "city" : "MongoDBVille",
  6.     "zip" : 99999
  7.   },
  8.   "phone" : "949-555-1212",
  9.   "ssn" : "123-45-6789"
  10. }

With client-side field level encryption, the application canspecifically encrypt sensitive information like the ssnand phone. Encrypted fields are stored asbinary data withsubtype 6:

  1. {
  2.   "name" : "John Doe",
  3.   "address" : {
  4.     "street" : "1234 Main Street",
  5.     "city" : "MongoDBVille",
  6.     "zip" : 99999
  7.   },
  8.   "phone" : BinData(6,"U2FsdGVkX1+CGIDGUnGgtS46+c7R5u17SwPDEmzyCbA="),
  9.   "ssn" : BinData(6,"AaloEw285E3AnfjP+r8ph2YCvMI1+rWzpZK97tV6iz0jx")
  10. }

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

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

  • Explicit (manual) encryption of fields
  • MongoDB 4.2-compatible drivers support explicitly encryptingor decrypting fields with a specific data encryption key and encryptionalgorithm.

Applications must modify any code associated with constructing readand write operations to include encryption/decryption logic via thedriver encryption library. Applications are responsible for selectingthe appropriate data encryption key for encryption/decryption on aper-operation basis.

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

  • Automatic encryption of fields

Enterprise Feature

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

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

Applications must modify only the driver client object configurationcode to include automatic encryption settings. All read/writeoperations to a cluster via the encryption-configured client areautomatically encrypted and decrypted using the predefined automaticencryption rules. Code associated with constructing read and writeoperations does not require additional modification.

For more information, seeAutomatic Client-Side Field Level Encryption.

MongoDB 4.2-compatible drivers and the 4.2 mongo shellautomatically decrypt Binary subtype 6 objects created usingclient-side field level encryption. For more information on automaticdecryption, see Automatic Field Decryption.

Important

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

Encryption Components

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

Diagram of relationships between driver and encryption components

  • libmongocrypt is the Apache-licensed open-source core cryptographylibrary used by the official MongoDB 4.2-compatible drivers and themongo shell for powering client-side field levelencryption. Some drivers may require specific integration steps toinstall or link the library. Defer to driver documentation for morecomplete information.
  • mongocryptd supports Automatic Client-Side Field Level Encryptionand is only available with MongoDB Enterprise. mongocryptd doesnot perform cryptographic functions.
  • The key vault is a MongoDB collection that stores all data encryptionkeys used to encrypt values. Data encryption keys are themselvesencrypted using a Customer Master Key (CMK) prior to storage in thecollection. The key vault may reside on a different MongoDB clusterthan the one storing the encrypted data. SeeEncryption Key Vault for more information.
  • The Key Management System stores the Customer Master Key used toencrypt data encryption keys. See Supported Key Management Servicesfor more information.
  • The MongoDB cluster which stores the encrypted data may alsoenforce client-side field level encryption. SeeEnforce Field Level Encryption Schema for more information.

Encryption Algorithms

MongoDB client-side field level encryption uses the encrypt-then-MACapproach combined with either a deterministic or random initializationvector to encrypt field values. MongoDB only supports theAEADAES-256-CBC encryption algorithm with HMAC-SHA-512 MAC.

Deterministic Encryption

The deterministic encryption algorithm ensures a given input valuealways encrypts to the same output value each time the algorithm isexecuted. While deterministic encryption provides greater support forread operations, encrypted data with low cardinality is susceptible tofrequency analysis recovery.

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

Randomized Encryption

The randomized encryption algorithm ensures that a given input valuealways encrypts to a different output value each time the algorithm isexecuted. While randomized encryption provides the strongest guaranteesof data confidentiality, it also prevents support for any readoperations which must operate on the encrypted field to evaluate thequery.

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

  1. {
  2.  "personal_information" : {
  3.    "ssn" : "123-45-6789",
  4.    "credit_score" : 750,
  5.    "credit_cards" : [ "1234-5678-9012-3456", "9876-5432-1098-7654"]
  6.  },
  7.  "phone_numbers" : [ "(212) 555-0153" ]
  8. }

Encrypting the personalinformation and phone_numbers fieldsusing the randomized encryption algorithm encrypts the _entire object.While this protects all fields nested under those fields, it alsoprevents querying against those nested fields.

For sensitive fields that are used in read operations, applicationsmust use Deterministic Encryption for improved readsupport on encrypted fields.

Automatic Field Decryption

The BinData blob metadata includes the dataencryption key _id and encryption algorithm used to encrypt thebinary data. The 4.2-compatible drivers and 4.2 mongoshell use this metadata to attempt automatic decryption BinData type6 values. The automatic decryption process works as follows:

  • Check the BinData blob metadata for thedata encryption key and encryption algorithm used to encrypt thevalue.

  • Check the key vault configured in the current database connection forthe specified data encryption key. If the key vault does not containthe specified key, automatic decryption fails and the driver returnsthe BinData blob.

  • Check the data encryption key metadata for the Customer Master Keyused to encrypt the key material.

  • For the Amazon Web Services KMS, send the data encryption key to theKMS service for decryption. If the CMK does not exist or if theconnection 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 thedata encryption key. If the local key specified in the databaseconfiguration was not used to encrypt the data encryption key,decryption fails and the driver returns the BinData blob.

  • Decrypt the BinData value using the decrypteddata encryption key and appropriate algorithm.

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

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

Enforce Field Level Encryption Schema

The MongoDB 4.2 server supports using schema validation to enforce encryption of specific fields in acollection. Use the automatic client-side field level encryptionJSON schema syntax with the$jsonSchema validation object to indicate which fields requireencryption. The server rejects any write operations to that collectionwhere the specified fields are not Binary (BinData)subtype 6 objects.

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

  • The taxid field must be encrypted. Clients should use thespecified data encryption key and the randomized encryption algorithm whenencrypting the field.
  • The taxid-short field must be encrypted. Clients should usethe specified data encryption key and the deterministic encryption algorithm whenencrypting the field.
  1. db.getSiblingDB("hr").runCommand(
  2.   {
  3.     "collMod" : "employees",
  4.     "validator" : {
  5.       "$jsonSchema" : {
  6.         "bsonType" : "object",
  7.         "properties" : {
  8.           "taxid" : {
  9.             "encrypt" : {
  10.               "keyId" : [UUID("e114f7ad-ad7a-4a68-81a7-ebcb9ea0953a")],
  11.               "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
  12.             }
  13.           },
  14.           "taxid-short" : {
  15.             "encrypt" : {
  16.               "keyId" : [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
  17.               "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
  18.               "bsonType" : "string"
  19.             }
  20.           }
  21.         }
  22.       }
  23.     }
  24.   }
  25. )

Clients performing explicit (manual) field level encryption mustencryptat minimum thetaxid and taxid-short fields using the same settings as theremote $jsonSchemaprior to issuing the write operation.

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

Automatic client-side field level encryption is available withMongoDB 4.2 Enterprise only.

  • If the connection ClientSideFieldLevelEncryptionOptionsschemaMap object contains a key for the specified collection, theclient uses that object to perform automatic field level encryptionand ignores the remote schema. The local rules must encrypt atminimum those the taxid and taxid-short fields.

  • If the connection ClientSideFieldLevelEncryptionOptionsschemaMap object does not contain a key for the specifiedcollection, the client downloads the server-side remote schema for thecollection and uses it to perform automatic field level encryption.

This configuration requires the client to trust the server has a validschema with respect to automatic field level encryption. The clientonly uses the remote schema to perform automatic field levelencryption and does not enforce any other validation rules specifiedin the schema.

Since the MongoDB server cannot decrypt nor introspect the contents ofthe encrypted field, it cannot validate that clients used thespecified encryption options to encrypt a given field. This allows twoclients to insert encrypted data using different keyIDs or encryptionalgorithms for a specific field. While some workloads may requireindependent field level encryption implementations, inconsistentimplementation of encryption options for a field across clients mayresult in incorrect or unexpected behavior of queries against theencrypted field.

For example, client A encrypts the PII field using randomencryption while client B encrypts the PII field usingdeterministic encryption. The randomized encryption algorithm alwaysreturns a different unique value while the deterministic algorithmalways returns the same value. Queries expecting deterministicallyencrypted data for that field return inconsistent results, as the servercannot match any of the randomly encrypted fields.

Driver Compatibility Table

MongoDB 4.2 client-side field level encryption withautomatic field encryption is available in the following driverversions:

Please refer to the driver documentation for syntax and implementationexamples.