Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Encryption Schemas

On this page

  • Overview
  • Encryption Schemas
  • encrypt Keyword
  • encryptMetadata Keyword
  • patternProperties Keyword
  • Example
  • Specify the Namespace
  • Specify the Data Encryption Key
  • Choose Encryption Rules
  • Specify Encryption Rules
  • View the Complete Schema
  • Learn More

On this page, you can learn how to create an encryption schema for automatic Client-Side Field Level Encryption (CSFLE) as well as see an example detailing how to create the encryption schema used in the CSFLE Quick Start.

An encryption schema is a JSON object which uses a strict subset of JSON Schema Draft 4 standard syntax along with the keywords encrypt and encryptMetadata to define the encryption rules that specify how your CSFLE-enabled client should encrypt your documents.

Encryption rules are JSON key-value pairs that define how your client application encrypts your fields. You must specify or inherit the following information in an encryption rule:

  • The algorithm used to encrypt your field

  • Which Data Encryption Key (DEK) your client uses to encrypt your field

  • The BSON type of your field

Encryption rules must contain either the encrypt or encryptMetadata keyword.

To learn more about the encryption algorithms you can define in your encryption schema, see Fields and Encryption Types.

To learn more about Data Encryption Keys, see Keys and Key Vaults.

The encrypt keyword defines an encryption rule for a single field in a BSON document. Encryption rules containing the encrypt keyword have the following structure:

"<field-name-to-encrypt>": {
"encrypt": {
"algorithm": "<encryption algorithm to use>",
"bsonType": "<bson type of field>",
"keyId": [UUID("<_id of your Data Encryption Key>" )]
}
}

The encryptMetadata keyword defines encryption rules which child elements of the sibling properties tag inherit. Encryption rules containing encryptMetadata have the following structure:

"bsonType": "object",
"encryptMetadata": {
"algorithm": "<encryption algorithm inherited by children of properties field>",
"keyId": [UUID("<_id of your Data Encryption Key>" )]
},
"properties": { <object to inherit encryptMetadata values> }

You can use the patternProperties keyword in your encryption schema to define encryption rules for all fields with names that match a regular expression. This allows you to specify multiple fields for encryption based on a single regular expression, or to specify them by only using a part of the field name. The patternProperties keyword replaces properties in your encryption schema.

Specify encryption rules with patternProperties using the following structure:

"bsonType": "object",
"patternProperties": {
"<regular expression to match>": {
"encrypt": {
"algorithm": "<encryption algorithm to use>",
"bsonType": "<bson type of field>",
"keyId": [UUID("<_id of your Data Encryption Key>" )]
}
}

To see an example of how to use patternProperties see Encryption Schema - Encrypt with Pattern Properties

This example explains how to generate the encryption schema used in the Create an Encryption Schema For Your Documents step of the CSFLE Quick Start.

In the Quick Start, you insert documents with the following structure into the patients collection of the medicalRecords database:

{
"_id": { "$oid": "<_id of your document>" },
"name": "<name of patient>",
"ssn": <integer>,
"bloodType": "<blood type>",
"medicalRecords": [
{ "weight": <integer>, "bloodPressure": "<blood pressure>" }
],
"insurance": {
"provider": "<provider name>",
"policyNumber": <integer>
}
}

At the root of your encryption schema, specify the namespace to which your encryption schema applies. Specify the following to encrypt and decrypt documents in the patients collection of the medicalRecords database:

{
"medicalRecords.patients": {
<the schema created in the following steps of this example>
}
}

In the Quick Start, you encrypt all fields of your document with a single Data Encryption Key (DEK). To configure all fields in your documents to use a single DEK for encryption and decryption, specify the _id of your DEK with the encryptMetadata keyword at the root of your encryption schema as follows:

{
"medicalRecords.patients": {
"bsonType": "object",
"encryptMetadata": {
"keyId": [UUID("<_id of your Data Encryption Key>" )]
},
"properties": {
<the schema created in the following steps of this example>
}
}
}

You decide to encrypt the following fields with the following encryption algorithms:

Field Name
Encryption Algorithm
BSON Type
ssn
Deterministic
Int
bloodType
Random
String
medicalRecords
Random
Array
insurance.policyNumber
Deterministic
Int

You choose to encrypt the ssn and insurance.policyNumber fields with deterministic encryption for the following reasons:

  • You want to be able to query on these fields.

  • The values in these fields have a high cardinality, so this data is not susceptible to a frequency analysis attack.

You choose to encrypt the bloodType field with random encryption for the following reasons:

  • You do not plan to query on this field.

  • The values in this field have low cardinality, making them susceptible to a frequency analysis attack if you encrypted them deterministically.

You must encrypt the medicalRecords field with random encryption as CSFLE does not support deterministic encryption of fields of type array.

Tip

To learn more about supported and unsupported automatic encryption operations, see Supported Operations for Automatic Encryption.

To encrypt the ssn field with deterministic encryption, specify the following in your encryption schema:

"ssn": {
"encrypt": {
"bsonType": "int",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
}
}

To encrypt the bloodType field with random encryption, specify the following in your encryption schema:

"bloodType": {
"encrypt": {
"bsonType": "string",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
}
}

To encrypt the medicalRecords field with random encryption, specify the following in your encryption schema:

"medicalRecords": {
"encrypt": {
"bsonType": "array",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
}
}

To encrypt the insurance.policyNumber field with deterministic encryption, specify the following in your encryption schema:

"insurance": {
"bsonType": "object",
"properties": {
"policyNumber": {
"encrypt": {
"bsonType": "int",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
}
}
}
}

The complete encryption schema for the Quick Start is as follows:

{
"medicalRecords.patients": {
"bsonType": "object",
"encryptMetadata": {
"keyId": [UUID("<_id of your Data Encryption Key>" )]
},
"properties": {
"insurance": {
"bsonType": "object",
"properties": {
"policyNumber": {
"encrypt": {
"bsonType": "int",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
}
}
}
},
"medicalRecords": {
"encrypt": {
"bsonType": "array",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
}
},
"bloodType": {
"encrypt": {
"bsonType": "string",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
}
},
"ssn": {
"encrypt": {
"bsonType": "int",
"algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
}
}
}
}
}

To learn more about encryption schemas, see CSFLE Encryption Schemas

To learn more about automatic encryption, see Automatic Encryption.

To view the Quick Start, see Quick Start.

←  Explicit EncryptionKeys and Key Vaults →