Docs Menu
Docs Home
/
MongoDB Manual
/
Security
/
Encryption
/
In-Use Encryption
/
Queryable Encryption
/
Tutorials

Use Automatic Queryable Encryption with AWS

On this page

  • Overview
  • Before You Get Started
  • Set Up the KMS
  • Create the Customer Master Key
  • Create an AWS IAM User
  • Create the Application
  • Create a Unique Index on your Key Vault collection
  • Create your Data Encryption Keys and Encrypted Collection
  • Configure your MongoClient for Encrypted Reads and Writes
  • Insert a Document with Encrypted Fields
  • Retrieve Your Encrypted Document
  • Learn More

Overview

This guide shows you how to build a Queryable Encryption enabled application using Amazon Web Services (AWS) KMS.

After you complete the steps in this guide, you should have:

  • A Customer Master Key hosted on an AWS KMS instance.

  • A working client application that inserts encrypted documents using your Customer Master Key.

Before You Get Started

To complete and run the code in this guide, you need to set up your development environment as shown in the Installation Requirements page.

Tip

See: Full Application

To see the complete code for the application you make in this guide, select the tab corresponding to your programming language and follow the provided link:

Set Up the KMS

1

Create the Customer Master Key

1

Log in to your AWS Management Console.

2

Navigate to the AWS KMS Console.

3

Create your Customer Master Key

Create a new symmetric key by following the official AWS documentation on Creating symmetric KMS keys. The key you create is your Customer Master Key. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration of your CMK.

In the Usage Permissions step of the key generation process, apply the following default key policy that enables Identity and Access Management (IAM) policies to grant access to your Customer Master Key:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Enable IAM User Permissions",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<ARN of your AWS account principal>"
      },
      "Action": "kms:*",
      "Resource": "*"
    }
  ]
}

Important

Record the Amazon Resource Name (ARN) and Region of your Customer Master Key. You will use these in later steps of this guide.

Tip

Learn More

To learn more about your Customer Master Keys, see Keys and Key Vaults.

To learn more about key policies, see Key Policies in AWS KMS in the official AWS documentation.

2

Create an AWS IAM User

1

Navigate to the AWS IAM Console.

2

Create an IAM User

Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. You will use this IAM user as a service account for your Queryable Encryption enabled application. Your application authenticates with AWS KMS using the IAM user to encrypt and decrypt your Data Encryption Keys (DEKs) with your Customer Master Key (CMK).

Important

Record your Credentials

Ensure you record the following IAM credentials in the final step of creating your IAM user:

  • access key ID

  • secret access key

You have one opportunity to record these credentials. If you do not record these credentials during this step, you must create another IAM user.

3

Grant Permissions

Grant your IAM user kms:Encrypt and kms:Decrypt permissions for your remote master key.

Important

The new client IAM user should not have administrative permissions for the master key. To keep your data secure, follow the principle of least privilege.

The following inline policy allows an IAM user to encrypt and decrypt with the Customer Master Key with the least privileges possible:

Note

Remote Master Key ARN

The following policy requires the ARN of the key you generate in the Create the Master Key step of this guide.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt", "kms:Encrypt"],
      "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
    }
  ]
}

To apply the preceding policy to your IAM user, follow the Adding IAM identity permissions guide in the AWS documentation.

Important

Authenticate with IAM Roles in Production

When deploying your Queryable Encryption enabled application to a production environment, authenticate your application through an IAM role instead of an IAM user.

To authenticate with an IAM role, specify your temporary IAM role credentials in your KMS provider object as follows:

{
    "accessKeyId":"<temporary access key ID>",
    "secretAccessKey":"<temporary secret access key>",
    "sessionToken":"<temporary session token>"
}

You can get your temporary IAM role credentials through the following mechanisms:

Your application must include logic to get new temporary credentials and recreate your Queryable Encryption enabled MongoClient instance when each set of temporary credentials expires.

To learn more about IAM roles, see the following pages in the official AWS documentation:

To learn how to get temporary credentials and assume a role in each of the languages supported in this guide, see the following AssumeRole runnable examples in the AWS documentation:

Create the Application

1

Create a Unique Index on your Key Vault collection

Create a unique index on the keyAltNames field in your encryption.__keyVault collection.

Select the tab corresponding to your preferred MongoDB driver:

2

Create your Data Encryption Keys and Encrypted Collection

1

Add your AWS KMS Credentials

Add the service account credentials to your Queryable Encryption enabled client code.

Select the tab corresponding to your preferred MongoDB driver:

Tip

You created and recorded your Access Key ID and Secret Access Key in the Create an IAM User step of this guide.

Tip

Learn More

To learn more about the KMS provider object for AWS, see Amazon Web Services KMS.

2

Add Your Key Information

Update the following code to specify your Customer Master Key:

Tip

You recorded your Customer Master Key's ARN and Region in the Create a Customer Master Key step of this guide.

3

Create your Data Encryption Keys

Construct a client with your MongoDB connection string and Key Vault collection namespace, and create the Data Encryption Keys:

Note

Key Vault Collection Namespace Permissions

The Key Vault collection in this guide is the __keyVault collection in the encryption database. Ensure that the database user your application uses to connect to MongoDB has ReadWrite permissions on the encryption.__keyVault namespace.

4

Create Your Encrypted Collection

Use a Queryable Encryption enabled MongoClient instance to specify what fields you must encrypt and create your encrypted collection:

The output from the code in this section should resemble the following:

Created encrypted collection!

Tip

Learn More

To view a diagram showing how your client application creates your Data Encryption Key when using an AWS KMS, see Architecture.

To learn more about the options for creating a Data Encryption Key encrypted with a Customer Master Key hosted in AWS KMS, see dataKeyOpts Object.

Tip

See: Complete Code

3

Configure your MongoClient for Encrypted Reads and Writes

1

Specify the Key Vault Collection Namespace

Specify encryption.__keyVault as the Key Vault collection namespace.

2

Specify your AWS Credentials

Specify the aws KMS provider and your IAM user credentials:

Tip

You created and recorded your Access Key ID and Secret Access Key in the Create an IAM User step of this guide.

3

Create an Encrypted Fields Map For Your Collection

4

Specify the Location of the Automatic Encryption Shared Library

Note

Automatic Encryption Options

The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.

To learn more about the Automatic Encryption Shared Library, see the Automatic Encryption Shared Library for Queryable Encryption page.

5

Create the MongoClient

Instantiate a MongoDB client object with the following automatic encryption settings:

4

Insert a Document with Encrypted Fields

Use your Queryable Encryption enabled MongoClient instance to insert an encrypted document into the medicalRecords.patients namespace using the following code snippet:

When you insert a document, your Queryable Encryption enabled client encrypts the fields of your document such that it resembles the following:

{
  "_id": { "$oid": "<_id value>" },
  "firstName": "Jon",
  "lastName": "Doe",
  "patientId": {
    "$binary": {
      "base64": "<ciphertext>",
      "subType": "06"
    }
  },
  "address": "157 Electric Ave.",
  "patientRecord": {
    "ssn": {
      "$binary": {
        "base64": "<ciphertext>",
        "subType": "06"
      }
    },
    "billing": {
      "$binary": {
        "base64": "<ciphertext>",
        "subType": "06"
      }
    }
  },
  "medications": {
    "$binary": {
      "base64": "<ciphertext>",
      "subType": "06"
    }
  },
  "__safeContent__": [
    {
      "$binary": {
        "base64": "<ciphertext>",
        "subType": "00"
      }
    },
    {
      "$binary": {
        "base64": "<ciphertext>",
        "subType": "00"
      }
    }
  ]
}

Warning

Do not Modify the __safeContent__ Field

The __safeContent__ field is essential to Queryable Encryption. Do not modify the contents of this field.

Tip

See: Complete Code

5

Retrieve Your Encrypted Document

Retrieve the encrypted document you inserted in the Insert a Document with Encrypted Fields step of this guide.

To show the functionality of Queryable Encryption, the following code snippet queries for your document with a client configured for automatic Queryable Encryption as well as a client that is not configured for automatic Queryable Encryption.

The output of the preceding code snippet should look like this:

Finding a document with regular (non-encrypted) client.
{
  _id: new ObjectId("628eabeb37590e84ea742665"),
  firstName: 'Jon',
  lastName: 'Doe',
  patientId: new Binary(Buffer.from("0798810acc0f4f46c9a76883cee80fca12102e9ddcbcdae46a821fa108a8155a850f2d0919475b6531ada68973d436a199b537a05a98a708c36d2bfec4979d59cbe66878865ce19e392d3e4789d309bdacc336e32efcc851806ae0a41b355288c10d01e39147e1c40d919c41913a0c9d2d3fad0d0d1d2873c4fc82c6c22f27b517df5f3131b331b96ed16a7c5cf89e09082a2d898c2dcd73da91d08760ba74a70077b2d0fdbbe1eea75655a19fcc397812325ad40b102cbd16b8d36b22e11e3f93404f24a8ff68cfdec3c22b0e787cb30078a5227b2a", "hex"), 6),
  address: '157 Electric Ave.',
  patientRecord: {
    ssn: new Binary(Buffer.from("07e8b69630c32f4a00a542af768f8abcf50223edd812ff20b0ecb046ee1a9f5a0eef8d85d99cd26076411129942752516ee605c55aadce73f3d44d81ea6ddbbb8134b108a9deb40d8cab9cb4f08ef210ab0c9d2ea4347f9d235b861baf29751e60abcf059eb5c120305bd5ac05a4e07ac8ccfa6d37283f4cdbfeb7a8accb65b71857d486b5cf55e354d6a95e287d9e2dd65f3f9d9c4c9d0bdb1f26c4bd549d7be77db81796be293e08b2223bac67b212423c4e06568578b5bd7a3c33cedc1b291bcda0b27e005144d344563711a489f24b8e9b65bbb721d3a0e9d9b227a0cec0cbad", "hex"), 6),
    billing: new Binary(Buffer.from("06808ae69d4caa49cf90bb688f386f097f03f870a7b8fcebb1980c9ee5488b1f0f68558fc2163adcd92d00ea5f349f56ed34e7b391f54c48ed2760b4bde73022fc818dc7486a4e046b92ce9c82e00333c7779d9d6bb476713a20632b593b7de54812662cfc4d174d05451d3f4195514e12edba", "hex"), 6)
  },
  medications: new Binary(Buffer.from("06665ec15d38254dc4aa16da856789d33404f27bfea53e0d2fa4deaff166989ab33f469644d89c29112d33b41dbe54ec2d89c43f3de52cdc5d454e8694046216f533614fa7b42b7c5406d6518f7ed8f9e3ce52fda6c8b2146d0f8cc51e21a3467183697e1735a9f60c18e173c1916101", "hex"), 6),
  __safeContent__: [
    new Binary(Buffer.from("3044b134ad0f7c8a90dab1e05bb8b296a8ede540796bd7403ab47693cdba1b26", "hex"), 0),
    new Binary(Buffer.from("a22ddf9a5657cdd56bef72febbba44371899e6486962a1c07d682082c4e65712", "hex"), 0)
  ]
}
Finding a document with encrypted client, searching on an encrypted field
{
  _id: new ObjectId("628eaca1dcf9b63e2f43162d"),
  firstName: 'Jon',
  lastName: 'Doe',
  patientId: 12345678,
  address: '157 Electric Ave.',
  patientRecord: {
    ssn: '987-65-4320',
    billing: { type: 'Visa', number: '4111111111111111' }
  },
  medications: [ 'Atorvastatin', 'Levothyroxine' ],
  __safeContent__: [
    new Binary(Buffer.from("fbdc6cfe3b4659693650bfc60baced27dcb42b793efe09da0ded54d60a9d5a1f", "hex"), 0),
    new Binary(Buffer.from("0f92ff92bf904a858ef6fd5b1e508187f523e791f51d8b64596461b38ebb1791", "hex"), 0)
  ]
}

Tip

See: Complete Code

Learn More

To learn how Queryable Encryption works, see Fundamentals.

To learn more about the topics mentioned in this guide, see the following links:

  • Learn more about Queryable Encryption components on the Reference page.

  • Learn how Customer Master Keys and Data Encryption Keys work on the Keys and Key Vaults page.

  • See how KMS Providers manage your Queryable Encryption keys on the KMS Providers page.

← Tutorials
Use Automatic Queryable Encryption with Azure →

On this page