Field Encryption and Queryability

Overview

In this guide, you can learn about the following Queryable Encryption topics:

• How to specify fields for encryption.

• How to specify whether an encrypted field is queryable when you create a collection.

• Query types and which ones you can use on encrypted fields.

• What to consider when deciding whether to enable queries on an encrypted field.

Specify Fields for Encryption

Queryable Encryption allows you to specify which fields you want to automatically encrypt in your MongoDB document.

To specify fields for encryption and querying, define a JSON schema that includes the following properties:

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

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         keyId: "<unique data encryption key>",
         bsonType: "int"
      },
      {
         path: "patientInfo.ssn",
         keyId: "<unique data encryption key>",
         bsonType: "string"
      },
      {
         path: "medications",
         keyId: "<unique data encryption key>",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         keyId: "<unique data encryption key>",
         bsonType: "object"
      },
   ]
}

Specify Queryable Encrypted Fields

Include the queries property on fields you want to make queryable in your JSON schema. This enables an authorized client to issue read and write queries using encrypted fields. You can omit the queries property unless you want to be able to query the field.

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         keyId: "<unique data encryption key>",
         bsonType: "int",
         queries: { queryType: "equality" }
      },
      {
         path: "patientInfo.ssn",
         keyId: "<unique data encryption key>",
         bsonType: "string",
         queries: { queryType: "equality" }
      },
      {
         path: "medications",
         keyId: "<unique data encryption key>",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         keyId: "<unique data encryption key>",
         bsonType: "object"
      },
   ]
}

Enable Queryable Encryption

You can enable Queryable Encryption on fields you specify in a JSON schema in the following ways:

• Pass the JSON schema, represented by the encryptedFieldsObject constant, to the client that the application uses to create the collection as shown in the following code snippet:

const client = new MongoClient(uri, {
   autoEncryption: {
      keyVaultNameSpace: "<your keyvault namespace>",
      kmsProviders: "<your kms provider>",
      extraOptions: {
         cryptSharedLibPath: "<path to FLE Shared Library>"
      },
      encryptedFieldsMap: {
         "<databaseName.collectionName>": { encryptedFieldsObject }
      }
   }
   ...
   await client.db("<database name>").createCollection("<collection name>");
}

For more information on autoEncryption configuration options, see the section on MongoClient Options for Queryable Encryption.

• Pass the encrypted fields object to your call to create a new collection as shown in the following code snippet:

await encryptedDB.createCollection("<collection name>", {
   encryptedFields: encryptedFieldsObject
});

Query Types

Queryable Encryption allows you to specify on which fields you want to enable querying by passing a query type to the queries option in your encrypted fields object.

Queryable Encryption currently supports none or equality query types. The new cryptography framework introduced as part of Queryable Encryption in MongoDB 6.0 is designed to accommodate additional expressive encrypted searches, such as range and string operators.

A query type of none indicates that the data will be encrypted but is not intended to be queryable. Queries cannot be run on encrypted data with a query type of none. Encrypted data will be returned if queries are run on:

• non-encrypted fields

• fields with a query type of equality in the same collection and decrypted at the client.

The equality query type allows you to query encrypted fields using the following expressions:

• $eq

• $ne

• $in

• $nin

• $and

• $or

• $not

• $nor

• $expr

Queryable Encryption using the equality query type doesn't support read or write operations on a field when the operation compares the encrypted field to any of the following BSON types:

• double

• decimal128

• object

• array

• javascriptWithScope (Deprecated)

Considerations when Enabling Querying

When you use Queryable Encryption, you can choose whether to make an encrypted field queryable. If you don't need to perform read operations, or write operations that require you to read an encrypted field, you may decide not to enable querying on that field. You can still retrieve the entire document by querying other fields that are queryable or not encrypted.

When you make encrypted fields queryable, Queryable Encryption creates an index for each encrypted field, which can make write operations on that field take longer. When a write operation updates an indexed field, MongoDB also updates the related index.

When you enable querying on an encrypted field, your collection requires more storage space. These collection names, which begin with enxcol_., contain important encryption metadata.