Docs Menu
Docs Home
/
MongoDB Manual
/
Security
/
Client-Side Field Level Encryption
/
Automatic Client-Side Field Level Encryption

Automatic Encryption Rules

On this page

  • encrypt Schema Keyword
  • encryptMetadata Schema Keyword
  • Examples

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.

Automatic client-side field level encryption requires user-specified rules which identify which fields must be encrypted and how to encrypt those fields. Applications must specify the automatic encryption rules using a strict subset of the JSON Schema Draft 4 standard syntax and the following encryption-specific keywords:

Consider a MongoDB database where the employees collection in the hr database contains documents which resemble the following:

{
  "fname" : "Jo",
  "lname" : "Doe",
  "taxid" : "123-45-6789",
  "taxid-short" : "6789"
}

The taxid and taxid-short fields contain personally identifiable information (PII) that must be protected from unauthorized viewing on both the client and the server. The following automatic encryption rules for the hr.employees collection mark the taxid and taxid-short fields for automatic client-side field level encryption. Official MongoDB 4.2+ compatible drivers and the 4.2 or later mongo shell configured with these rules automatically encrypt the taxid and taxid-short fields for write or read operations to the hr.employees collection.

{
  "hr.employees": {
    "bsonType": "object",
    "properties": {
      "taxid": {
        "encrypt": {
          "keyId": [UUID("11d58b8a-0c6c-4d69-a0bd-70c6d9befae9")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Random",
          "bsonType" : "string"
        }
      },
      "taxid-short": {
        "encrypt": {
          "keyId": [UUID("2ee77064-5cc5-45a6-92e1-7de6616134a8")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType": "string"
        }
      }
    }
  }
}

  • For the MongoDB 4.2+ shell, use the Mongo() constructor to create the database connection with the automatic encryption rules included as part of the client-side field level encryption configuration object. See Connect to a MongoDB Cluster with Automatic Client-Side Encryption Enabled for an example.

  • For the official MongoDB 4.2+ compatible drivers, use the driver-specific database connection constructor (e.g. MongoClient) to create the database connection with the automatic encryption rules included as part of the client-side field level encryption configuration object. Defer to the driver API reference for more complete documentation and tutorials.

Important

Automatic client-side field level encryption supports a strict subset of the JSON schema syntax only for defining encryption behavior. Do not specify document validation keywords in the automatic encryption rules. To define document validation rules, configure server-side schema validation.

encrypt Schema Keyword

"bsonType" : "object",
"properties" : {
  "<fieldName>" : {
    "encrypt" : {
      "algorithm" : "<string>",
      "bsonType" : "<string>" | [ "<string>" ],
      "keyId" : [ <UUID> ]
    }
  }
}
encrypt

Object

Indicates that <fieldName> must be encrypted. The encrypt object has the following requirements:

  • encrypt cannot have any sibling fields in the <fieldName> object. encrypt must be the only child of the <fieldName> object.

  • encrypt cannot be specified within any subschema of the items or additionalItems keywords. Specifically, automatic client-side field level encryption does not support encrypting individual elements of an array.

The encrypt object can contain only the following fields:

Including any other field to the encrypt object results in errors when issuing automatically encrypted read or write operations

If keyId or algorithm are omitted, the mongocryptd checks the full tree of parent fields and attempts to construct those options from the nearest encryptMetadata object that specifies the option. bsonType cannot be inherited and may be required depending on the value of algorithm.

If mongocryptd cannot construct the full encrypt object using the fields specified to the object and any required encryptMetadata-inherited keys, automatic encryption fails and returns an error.

encrypt.algorithm

String

Indicates which encryption algorithm to use when encrypting values of <fieldName>. Supports the following algorithms only:

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

For complete documentation on the encryption algorithms, see Encryption Algorithms.

If omitted, mongocryptd checks the full tree of parent fields for the nearest encryptMetadata.algorithm key and inherits that value. If no parent algorithm exists, automatic field level encryption fails and returns an error.

  • If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, the encrypt object requires the encrypt.bsonType field.

  • If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Random, the encrypt object may include the encrypt.bsonType field.

encrypt.bsonType

String | Array of Strings

The BSON type of the field being encrypted. Required if encrypt.algorithm is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic.

If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, bsonType must specify a single type. bsonType does not support any of the following BSON types with the deterministic encryption algorithm:

  • double

  • decimal128

  • bool

  • object

  • array

  • javascriptWithScope (Deprecated)

If encrypt.algorithm or its inherited value is AED_AES_256_CBC_HMAC_SHA_512-Random, bsonType is optional and may specify an array of supported bson types. For fields with bsonType of array or object, the client encrypts the entire array or object and not their individual elements.

encrypt.bsonType does not support the following types regardless of encrypt.algorithm or its inherited value:

  • minKey

  • maxKey

  • null

  • undefined

encrypt.keyId

Array of single UUID

The UUID of the data encryption key to use for encrypting field values. The UUID is a BSON binary data element of subtype 4.

Specify one string inside the array.

If omitted, mongocryptd checks the full tree of parent fields for the nearest encryptMetadata.keyId key and inherits that value. If no parent keyId exists, automatic field level encryption fails and returns an error.

The keyId or its inherited value must exist in the key vault specified as part of the auto encryption configuration options. If the specified data encryption key does not exist, automatic encryption fails.

Official MongoDB 4.2+ compatible drivers have language-specific requirements for specifying the UUID. Defer to the driver documentation for complete documentation on implementing client-side field level encryption.

encryptMetadata Schema Keyword

{
  "bsonType" : "object",
  "encryptMetadata" : {
    "algorithm" : "<string>",
    "keyId" : [ <UUID> ]
  },
  "properties" : {
    "encrypt" : {}
  }
}
encryptMetadata

Object

Defines encryption options which an encrypt object nested in the sibling properties may inherit. If an encrypt is missing an option required to support encryption, mongocryptd searches the entire tree of parent objects to locate an encryptMetadata object that specifies the missing option.

encryptMetadata must be specified in subschemas with bsonType: "object". encryptMetadata cannot be specified to any subschema of the items or additionalItems keywords. Specifically, automatic client-side field level encryption does not support encrypting individual elements of an array.

The encryptMetadata object can contain only the following fields. Including any other field to the encrypt object results in errors when issuing automatically encrypted read or write operations:

encryptMetadata.algorithm

String

The encryption algorithm to use to encrypt a given field. If an encrypt object is missing the algorithm field, mongocryptd searches the entire tree of parent objects to locate an encryptMetadata object that specifies encryptMetadata.algorithm.

Supports the following algorithms only:

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

For complete documentation on the encryption algorithms, see Encryption Algorithms.

If specifying AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, any encrypt object inheriting that value must specify encrypt.bsonType.

encryptMetadata.keyId

Array of single UUID

The UUID of a data encryption key. The UUID is a BSON binary data element of subtype 4.

Specify one string inside the array.

If an encrypt object is missing the keyId field, mongocryptd searches the entire tree of parent objects to locate an encryptMetadata object that specifies encryptMetadata.keyId.

The data encryption key must exist in the key vault specified as part of the auto encryption configuration options. The specified configuration options must also include appropriate access to the Key Management Service (KMS) and Customer Master Key (CMK) used to create the data key. Automatic encryption fails if the data encryption key does not exist or if the client cannot decrypt the key with the specified KMS and CMK.

Official MongoDB 4.2+ compatible drivers have language-specific requirements for specifying the UUID. Defer to the driver documentation for complete documentation on implementing client-side field level encryption.

Examples

Automatically Encrypt Multiple Fields

Consider a collection MedCo.patients where each document has the following structure:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

The following fields contains personally identifiable information (PII) that may be queried:

  • passportId

  • bloodType

  • insurance.policyNumber

  • insurance.provider

The deterministic encryption algorithm guarantees that the encrypted output of a value remains static. This allows queries for a specific value to return meaningful results at the cost of increased susceptibility to frequency analysis recovery. The deterministic encryption algorithm therefore meets both the encryption and queryability requirements of the data.

The following fields contain legally protected personally identifiable information (PII) that may never be queried:

  • medicalRecords

The randomized encryption algorithm guarantees that the encrypted output of a value is always unique. This prevents queries for a specific field value from returning meaningful results while supporting the highest possible protection of the field contents. The randomized encryption algorithm therefore meets both the encryption and queryability requirements of the data.

The following schema specifies automatic encryption rules which meet the above requirements for the MedCo.patients collection:

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("f3821212-e697-4d65-b740-4a6791697c6d")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

The above automatic encryption rules mark the passportId, bloodType, insurance.policyNumber, insurance.provider, and medicalRecords fields for encryption.

  • The passportId, bloodType, insurance.policyNumber, and provider fields require deterministic encryption using the specified key.

  • The medicalRecords field requires randomized encryption using the specified key.

While client-side field level encryption does not support encrypting individual array elements, randomized encryption supports encrypting the entire array field rather than individual elements in the field. The example automatic encryption rules specify randomized encryption for the medicalRecords field to encrypt the entire array. If the automatic encryption rules specified encrypt or encryptMetadata within medicalRecords.items or medicalRecords.additionalItems, automatic field level encryption fails and returns an errors.

The official MongoDB 4.2+ compatible drivers and the mongo shell require specifying the automatic encryption rules as part of creating the database connection object:

For all clients, the keyVault and kmsProviders specified to the client-side field level encryption parameter must grant access to both the data encryption keys specified in the automatic encryption rules and the Customer Master Key used to encrypt the data encryption keys.

Automatically Encrypt Multiple Fields With Inheritance

Consider a collection MedCo.patients where each document has the following structure:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

The following fields contain private data that may be queried:

  • passportId

  • bloodType

  • insurance.policyNumber

  • insurance.provider

The deterministic encryption algorithm guarantees that the encrypted output of a value remains static. This allows queries for a specific value to return meaningful results at the cost of increased susceptibility to frequency analysis recovery. The deterministic encryption algorithm therefore meets both the encryption and queryability requirements of the data.

The following fields contain private data that may never be queried:

  • medicalRecords

The randomized encryption algorithm guarantees that the encrypted output of a value is always unique. This prevents queries for a specific field value from returning meaningful results while supporting the highest possible protection of the field contents. The randomized encryption algorithm therefore meets both the encryption and queryability requirements of the data.

The following schema specifies automatic encryption rules which meet the encryption requirements for the MedCo.patients collection:

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "encryptMetadata" : {
      "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
      "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
    },
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

The above automatic encryption rules mark the passportId, bloodType, insurance.policyNumber, insurance.provider, and medicalRecords fields for encryption.

  • The passportId, bloodType, insurance.policyNumber, and provider fields inherit their encryption settings from the parent encryptMetadata field. Specifically, these fields inherit the algorithm and keyId values specifying deterministic encryption with the specified data encryption key.

  • The medicalRecords field requires randomized encryption using the specified key. The encrypt options override those specified in the parent encryptMetadata field.

While client-side field level encryption does not support encrypting individual array elements, randomized encryption supports encrypting the entire array field rather than individual elements in the field. The example automatic encryption rules specify randomized encryption for the medicalRecords field to encrypt the entire array. If the automatic encryption rules specified encrypt or encryptMetadata within medicalRecords.items or medicalRecords.additionalItems, automatic field level encryption fails and returns an errors.

The official MongoDB 4.2+ compatible drivers and the mongo shell require specifying the automatic encryption rules as part of creating the database connection object:

For all clients, the keyVault and kmsProviders specified to the client-side field level encryption parameter must grant access to both the data encryption keys specified in the automatic encryption rules and the Customer Master Key used to encrypt the data encryption keys.

Back

Automatic Client-Side Field Level Encryption

Next

Read/Write Support with Automatic Field Level Encryption