Automatic Encryption Rules

beta

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

Enterprise Feature

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

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

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

  1. {
  2.   "fname" : "Jo",
  3.   "lname" : "Doe",
  4.   "taxid" : "123-45-6789",
  5.   "taxid-short" : "6789"
  6. }

The taxid and taxid-short fields contain personally identifiableinformation (PII) that must be protected from unauthorized viewing onboth the client and the server. The following automatic encryptionrules for the hr.employees collection mark the taxid andtaxid-short fields for automatic client-side field level encryption.Official MongoDB 4.2-compatible drivers and the 4.2 mongo shellconfigured with these rules automatically encrypt the taxidand taxid-short fields for write or read operations to thehr.employees collection.

  1. {
  2.   "hr.employees": {
  3.     "bsonType": "object",
  4.     "properties": {
  5.       "taxid": {
  6.         "encrypt": {
  7.           "keyId": [UUID("11d58b8a-0c6c-4d69-a0bd-70c6d9befae9")],
  8.           "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Random",
  9.           "bsonType" : "string"
  10.         }
  11.       },
  12.       "taxid-short": {
  13.         "encrypt": {
  14.           "keyId": [UUID("2ee77064-5cc5-45a6-92e1-7de6616134a8")],
  15.           "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic",
  16.           "bsonType": "string"
  17.         }
  18.       }
  19.     }
  20.   }
  21. }
  • For the MongoDB 4.2 shell, use the Mongo constructorto create the database connection with the automatic encryption rulesincluded as part of the client-side field level encryptionconfiguration object.See Connect to a MongoDB Cluster with Automatic Client-Side Encryption Enabledfor an example.
  • For the official MongoDB 4.2-compatible drivers, use thedriver-specific database connection constructor (e.g. MongoClient)to create the database connection with the automatic encryption rulesincluded as part of the client-side field level encryptionconfiguration object. Defer to the driver API reference for more complete documentation andtutorials.

Important

Automatic client-side field level encryption supports a strict subsetof the JSON schema syntax only for defining encryption behavior. Donot specify document validation keywords in the automaticencryption rules. To define document validation rules, configureserver-side schema validation.

encrypt Schema Keyword

  1. "bsonType" : "object",
  2. "properties" : {
  3.   "<fieldName>" : {
  4.     "encrypt" : {
  5.       "algorithm" : "<string>",
  6.       "bsonType" : "<string>" | [ "<string>" ],
  7.       "keyId" : [ <UUID> ]
  8.     }
  9.   }
  10. }
  • encrypt
  • Object

Indicates that <fieldName> must be encrypted. The encryptobject 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 theitems or additionalItems keywords. Specifically,automatic client-side field level encryption does not supportencrypting individual elements of an array.The encrypt object can contain only thefollowing fields:

  • algorithm

  • bsonType
  • keyIdIncluding any other field to the encrypt objectresults in errors when issuing automatically encrypted read or writeoperations

If keyId oralgorithm are omitted, themongocryptd checks the full tree of parent fields and attemptsto construct those options from the nearestencryptMetadata object that specifies theoption. bsonType cannot be inheritedand may be required depending on the value ofalgorithm.

If mongocryptd cannot construct the full encrypt object usingthe fields specified to the object and any requiredencryptMetadata-inherited keys, automatic encryption fails andreturns an error.

  • encrypt.algorithm
  • String

Indicates which encryption algorithm to use when encryptingvalues of <fieldName>. Supports the following algorithmsonly:

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random
  • AEAD_AES_256_CBC_HMAC_SHA_512-DeterministicFor complete documentation on the encryption algorithms, seeEncryption Algorithms.

If omitted, mongocryptd checks the full tree of parent fieldsfor the nearest encryptMetadata.algorithm keyand inherits that value. If no parentalgorithm exists, automaticfield level encryption fails and returns an error.

  • If encrypt.algorithm or its inherited value isAEADAES_256_CBC_HMAC_SHA_512-Deterministic,the encrypt object _requires theencrypt.bsonType field.
  • If encrypt.algorithm or its inherited value isAEADAES_256_CBC_HMAC_SHA_512-Random,the encrypt object _may include theencrypt.bsonType field.
  • encrypt.bsonType
  • String | Array of Strings

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

If encrypt.algorithm or its inherited value isAEADAES_256_CBC_HMAC_SHA_512-Deterministic, bsonType_must specify a single type. bsonType does notsupport any of the following bson types with the deterministicencryption algorithm:

  • double
  • decimal128
  • bool
  • object
  • array
  • javascriptWithScopeIf encrypt.algorithm or its inherited value isAEDAES_256_CBC_HMAC_SHA_512-Random, bsonType isoptional and may specify an array of supported bson types. Forfields with bsonType of array or object, the clientencrypts the _entire array or object and not their individualelements.

encrypt.bsonType does not support the following typesregardless of encrypt.algorithm or its inheritedvalue:

  • minKey
  • maxKey
  • null
  • undefined
  • encrypt.keyId
  • Array of UUID

The UUID of the data encryption key to use for encrypting fieldvalues. Specify one string inside the array. The UUID is a BSONbinary data element of subtype4.

If omitted, mongocryptd checks the full tree of parentfields for the nearestencryptMetadata.keyId key and inheritsthat value. If no parentkeyId 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 encryptionconfiguration options.If the specified data encryption key does not exist, automaticencryption fails.

Official MongoDB 4.2-compatible drivers have language-specificrequirements for specifying the UUID. Defer to thedriver documentationfor complete documentation on implementing client-side fieldlevel encryption.

encryptMetadata Schema Keyword

  1. {
  2.   "bsonType" : "object",
  3.   "encryptMetadata" : {
  4.     "algorithm" : "<string>",
  5.     "keyId" : [ <UUID> ]
  6.   },
  7.   "properties" : {
  8.     "encrypt" : {}
  9.   }
  10. }
  • encryptMetadata
  • Object

Defines encryption options which an encryptobject nested in the sibling properties may inherit. If anencrypt is missing an option required to supportencryption, mongocryptd searches the entire tree of parent objectsto locate an encryptMetadata object thatspecifies the missing option.

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

The encryptMetadata object can contain only thefollowing fields. Including any other field to the encrypt objectresults in errors when issuing automatically encrypted read or writeoperations:

  • encryptMetadata.algorithm
  • String

The encryption algorithm to use to encrypt a given field. If anencrypt object is missing thealgorithm field, mongocryptdsearches the entire tree of parent objects to locate anencryptMetadata object that specifiesencryptMetadata.algorithm.

Supports the following algorithms only:

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random
  • AEAD_AES_256_CBC_HMAC_SHA_512-DeterministicFor complete documentation on the encryption algorithms, seeEncryption Algorithms.

If specifying AEADAES_256_CBC_HMAC_SHA_512-Deterministic,any encrypt object inheriting that value _must specifyencrypt.bsonType.

  • encryptMetadata.keyId
  • Array of single UUID

The UUID of a data encryption key. If anencrypt object is missing thekeyId field, mongocryptdsearches the entire tree of parent objects to locatean encryptMetadata object thatspecifies encryptMetadata.keyId.

The UUID is a BSON binary dataelement of subtype 4.

The data encryption key must exist in the key vault specified aspart of the auto encryption configuration options. The specified configurationoptions must also include appropriate access to the Key ManagementService (KMS) and Customer Master Key (CMK) used to create the datakey. Automatic encryption fails if the data encryption key does notexist or if the client cannot decrypt the key with the specified KMSand CMK.

Official MongoDB 4.2-compatible drivers have language-specificrequirements for specifying the UUID. Defer to thedriver documentationfor complete documentation on implementing client-side fieldlevel encryption.

Examples

Automatically Encrypt Multiple Fields

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

  1. {
  2.   "fname" : "<String>",
  3.   "lname" : "<String>",
  4.   "passportId" : "<String>",
  5.   "bloodType" : "<String>",
  6.   "medicalRecords" : [
  7.     {<object>}
  8.   ],
  9.   "insurance" : {
  10.     "policyNumber" : "<string>",
  11.     "provider" : "<string>"
  12.   }
  13. }

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

  • passportId
  • bloodType
  • insurance.policyNumber
  • insurance.provider

The deterministicencryption algorithm guarantees that the encrypted output of a valueremains static. This allows queries for a specific value to returnmeaningful results at the cost of increased susceptibility to frequencyanalysis recovery. The deterministic encryption algorithm thereforemeets both the encryption and queryability requirements of the data.

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

  • medicalRecords

The randomized encryptionalgorithm guarantees that the encrypted output of a value is alwaysunique. This prevents queries for a specific field value from returningmeaningful results while supporting the highest possible protection ofthe field contents. The randomized encryption algorithm therefore meetsboth the encryption and queryability requirements of the data.

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

  1. {
  2.   "MedCo.patients" : {
  3.     "bsonType" : "object",
  4.     "properties" : {
  5.       "passportId" : {
  6.         "encrypt" : {
  7.           "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
  8.           "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
  9.           "bsonType" : "string"
  10.         }
  11.       },
  12.       "bloodType" : {
  13.         "encrypt" : {
  14.           "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
  15.           "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
  16.           "bsonType" : "string"
  17.         }
  18.       },
  19.       "medicalRecords" : {
  20.         "encrypt" : {
  21.           "keyId" : [UUID("f3821212-e697-4d65-b740-4a6791697c6d")],
  22.           "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
  23.           "bsonType" : "string"
  24.         }
  25.       },
  26.       "insurance" : {
  27.         "bsonType" : "object",
  28.         "properties" : {
  29.           "policyNumber" : {
  30.             "encrypt" : {
  31.               "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
  32.               "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
  33.               "bsonType" : "string"
  34.             }
  35.           },
  36.           "provider" : {
  37.             "encrypt" : {
  38.               "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
  39.               "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
  40.               "bsonType" : "string"
  41.             }
  42.           }
  43.         }
  44.       }
  45.     }
  46.   }
  47. }

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

  • The passportId, bloodType, insurance.policyNumber, andprovider fields require deterministic encryption using thespecified key.
  • The medicalRecords field requires randomized encryption using thespecified key.

While client-side field level encryption does not support encryptingindividual array elements, randomized encryption supports encrypting theentire array field rather than individual elements in the field. Theexample automatic encryption rules specify randomized encryption for themedicalRecords field to encrypt the entire array. If the automaticencryption rules specified encrypt orencryptMetadata within medicalRecords.items ormedicalRecords.additionalItems, automatic field level encryptionfails and returns an errors.

The official MongoDB 4.2-compatible drivers and themongo shell require specifying the automaticencryption rules as part of creating the database connection object:

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

Automatically Encrypt Multiple Fields With Inheritance

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

  1. {
  2.   "fname" : "<String>",
  3.   "lname" : "<String>",
  4.   "passportId" : "<String>",
  5.   "bloodType" : "<String>",
  6.   "medicalRecords" : [
  7.     {<object>}
  8.   ],
  9.   "insurance" : {
  10.     "policyNumber" : "<string>",
  11.     "provider" : "<string>"
  12.   }
  13. }

The following fields contain private data that may be queried:

  • passportId
  • bloodType
  • insurance.policyNumber
  • insurance.provider

The deterministicencryption algorithm guarantees that the encrypted output of a valueremains static. This allows queries for a specific value to returnmeaningful results at the cost of increased susceptibility to frequencyanalysis recovery. The deterministic encryption algorithm thereforemeets both the encryption and queryability requirements of the data.

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

  • medicalRecords

The randomized encryptionalgorithm guarantees that the encrypted output of a value is alwaysunique. This prevents queries for a specific field value from returningmeaningful results while supporting the highest possible protection ofthe field contents. The randomized encryption algorithm therefore meetsboth the encryption and queryability requirements of the data.

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

  1. {
  2.   "MedCo.patients" : {
  3.     "bsonType" : "object",
  4.     "encryptMetadata" : {
  5.       "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
  6.       "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
  7.     },
  8.     "properties" : {
  9.       "passportId" : {
  10.         "encrypt" : {
  11.           "bsonType" : "string"
  12.         }
  13.       },
  14.       "bloodType" : {
  15.         "encrypt" : {
  16.           "bsonType" : "string"
  17.         }
  18.       },
  19.       "medicalRecords" : {
  20.         "encrypt" : {
  21.           "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
  22.           "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
  23.           "bsonType" : "string"
  24.         }
  25.       },
  26.       "insurance" : {
  27.         "bsonType" : "object",
  28.         "properties" : {
  29.           "policyNumber" : {
  30.             "encrypt" : {
  31.               "bsonType" : "string"
  32.             }
  33.           },
  34.           "provider" : {
  35.             "encrypt" : {
  36.               "bsonType" : "string"
  37.             }
  38.           }
  39.         }
  40.       }
  41.     }
  42.   }
  43. }

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

  • The passportId, bloodType, insurance.policyNumber, andprovider fields inherit their encryption settings from the parentencryptMetadata field. Specifically, these fields inheritthe algorithm andkeyId values specifyingdeterministic encryption with the specified data encryption key.
  • The medicalRecords field requires randomized encryption using thespecified key. The encrypt options override those specifiedin the parent encryptMetadata field.

While client-side field level encryption does not support encryptingindividual array elements, randomized encryption supports encrypting theentire array field rather than individual elements in the field. Theexample automatic encryption rules specify randomized encryption for themedicalRecords field to encrypt the entire array. If the automaticencryption rules specified encrypt orencryptMetadata within medicalRecords.items ormedicalRecords.additionalItems, automatic field level encryptionfails and returns an errors.

The official MongoDB 4.2-compatible drivers and themongo shell require specifying the automaticencryption rules as part of creating the database connection object:

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