Field Encryption and Queryability

Overview

Learn about the following Queryable Encryption topics:

• Considerations when enabling queries on an encrypted field.

• How to specify fields for encryption.

• How to configure an encrypted field so that it is queryable.

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

• How to optimize query performance on encrypted fields.

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 CRUD operations that require you to query an encrypted field, you may not need 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 create an encrypted collection, MongoDB creates two metadata collections, increasing the storage space requirements.

Specify Fields for Encryption

With Queryable Encryption, you specify which fields you want to automatically encrypt in your MongoDB document using a JSON encryption schema. The encryption schema defines which fields are encrypted and which queries are available for those fields.

To specify fields for encryption and querying, create an encryption schema that includes the following properties:

{
   "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"
      }
   }
}

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"
      }
   ]
}

Configure Fields for Querying

Include the queries property on fields to make them queryable. This enables an authorized client to issue read and write queries against those fields. Omitting the queries property prevents clients from querying a field.

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"
      },
   ]
}

Contention

Concurrent write operations, such as inserting the same field/value pair into multiple documents in close succession, can cause contention: conflicts that delay operations.

With Queryable Encryption, MongoDB tracks the occurrences of each field/value pair in an encrypted collection using an internal counter. The contention factor partitions this counter, similar to an array. This minimizes issues with incrementing the counter when using insert, update, or findAndModify to add or modify an encrypted field with the same field/value pair in close succession. contention = 0 creates an array with one element at index 0. contention = 4 creates an array with 5 elements at indexes 0-4. MongoDB increments a random array element during insert.

When unset, contention defaults to 8, which provides high performance for most workloads. Higher contention improves the performance of insert and update operations on low cardinality fields, but decreases find performance.

Client and Server Schemas

MongoDB supports using schema validation to enforce encryption of specific fields in a collection. Clients using automatic Queryable Encryption have specific behavior depending on the database connection configuration:

• If the connection encryptedFieldsMap object contains a key for the specified collection, the client uses that object to perform automatic Queryable Encryption, rather than using the remote schema. At a minimum, the local rules must encrypt those fields that the remote schema marks as requiring encryption.

• If the connection encryptedFieldsMap object does not contain a key for the specified collection, the client downloads the server-side remote schema for the collection and uses it to perform automatic Queryable Encryption.

  Important

  Behavior Considerations

  When a client does not have an encryption schema for the specified collection, the following occurs:

  • The client trusts that the server has a valid schema with respect to automatic Queryable Encryption.

  • The client uses the remote schema to perform automatic Queryable Encryption only. The client does not enforce any other validation rules specified in the schema.

To learn more about automatic Queryable Encryption, see the following resources:

• Queryable Encryption Introduction

• Quick Start

Enable Queryable Encryption

Enable Queryable Encryption before creating a collection. Enabling Queryable Encryption after creating a collection does not encrypt fields on documents already in that collection. You can enable Queryable Encryption on fields in one of two ways:

• Pass the encryption schema, represented by the encryptedFieldsObject constant, to the client that the application uses to create the collection:

const client = new MongoClient(uri, {
   autoEncryption: {
      keyVaultNameSpace: "<your keyvault namespace>",
      kmsProviders: "<your kms provider>",
      extraOptions: {
         cryptSharedLibPath: "<path to Automatic Encryption 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 createCollection() to create a new collection:

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