/ /

/ /

Create an Encryption Schema

About this Task

To make encrypted fields queryable, create an encryption schema. This schema defines which fields are queryable, and which query types are permitted. For more information, see Encrypted Fields and Enabled Queries.

Important

Queryable Encryption supports equality and range queries. You can configure a field for only one query type.

Before you Begin

When you make encrypted fields queryable, consider performance and security. For details on how each configuration option affects these, see Configure Encrypted Fields for Optimal Search and Storage.

Field Reference

You can configure encryption for each field in the fields array of your encryptedFieldsObject. The following table describes the available subfields:

Field	Type	Description
`path`	String	Required. The dot-notation path to the field to encrypt, such as `"patientInfo.ssn"`. You can specify any field except the `_id` field.
`bsonType`	String	Required. The BSON type of the field to encrypt. For a complete list of supported types, see Supported and Unsupported BSON Types.
`keyId`	UUID	Optional. The UUID of the DEK to use for encrypting this field. The UUID is a BSON binary data element of subtype `4`. Key IDs must be unique. Specifying a `keyId` that is already in use returns an error. If omitted, you can use the `createEncryptedCollection()` helper method to create keys automatically.
`queries`	Object	Optional. Enables querying on this encrypted field. If omitted, the field is encrypted but not queryable. To learn more about query options, see Configure Encrypted Fields for Optimal Search and Storage.

Steps

Create a JSON encryption schema document.

Include an encryptedFieldsObject with a nested fields array:

const encryptedFieldsObject = {
   fields: []
}

Specify fields to encrypt.

Add the path and bsonType strings to a document within the fields array:

const encryptedFieldsObject = {
   fields: [
      {
         path: "myDocumentField",
         bsonType: "int"
      }
   ]
}

Important

You can specify any field for encryption except the _id field.

If you are using explicit encryption, add a keyId field with the DEK ID:
```
{
   path: "myDocumentField",
   bsonType: "int",
   keyId: "<unique data encryption key>"
}
```
Tip
With Automatic Encryption, MongoDB creates encryption keys for each field. You configure AutoEncryptionSettings on the client, then use the createEncryptedCollection helper method to create your collections.

Enable equality queries on desired fields.

This enables querying with the $eq, $ne, $in, and $nin operators.

Add the queries object and set queryType to "equality":

{
   path: "myDocumentField",
   bsonType: "int",
   queries: { queryType: "equality" }
}

Enable range queries on desired fields.

This enables querying with the $lt, $lte, $gt, and $gte operators.

For details on how the following options affect security and performance, see Configure Encrypted Fields for Optimal Search and Storage.

Add the queries object and set queryType to "range":
```
{
   path: "myDocumentRangeField",
   bsonType: "int",
   queries: { queryType: "range" }
}
```

Set the following fields:

Field	Type	Description
min and max	Same as field `bsonType`	Required if `bsonType` is `decimal` or `double`. Optional but highly recommended if it is `int`, `long`, or `date`. Defaults to the minimum and maximum values of the `bsonType`. When possible, specifying bounds on a query improves performance. If querying values outside of these inclusive bounds, MongoDB returns an error.

{
   path: "myDocumentRangeField",
   bsonType: "int",
   queries: { queryType: "range",
              min: 0,
              max: 1200
   }
}

Example

This example shows how to create an encryption schema for hospital data.

Consider the following document that contains personally identifiable information (PII), credit card information, and sensitive medical information:

{
   "firstName": "Jon",
   "lastName": "Snow",
   "patientId": 12345187,
   "address": "123 Cherry Ave",
   "medications": [
      "Adderall",
      "Lipitor"
   ],
   "patientInfo": {
      "ssn": "921-12-1234",
      "billing": {
            "type": "visa",
            "number": "1234-1234-1234-1234"
      }
   }
}

To ensure the PII and sensitive medical information stays secure, this encryption schema adds the relevant fields:

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int"
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string"
      },
      {
         path: "medications",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         bsonType: "object"
      }
   ]
}

Adding the queries property makes the patientId and patientInfo.ssn fields queryable. This example enables equality queries:

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int",
         queries: { queryType: "equality" }
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string",
         queries: { queryType: "equality" }
      },
      {
         path: "medications",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         bsonType: "object"
      },
   ]
}

Back

Fields & Queries

Encrypt Collections at Creation

About this Task

Important

Before you Begin

Field Reference

Steps

Create a JSON encryption schema document.

Specify fields to encrypt.

Important

Tip

Enable equality queries on desired fields.

Enable range queries on desired fields.

Example