/ /

Queryable Encryption Quick Start

Language

This tutorial shows you how to build an application that implements the MongoDB Queryable Encryption feature to automatically encrypt and decrypt document fields.

The tutorial includes the following sections:

Set Up Your Project: Install the driver and encryption dependencies, configure your environment variables, and create your project files with the required application variables.
Configure Encryption: Create a Customer Master Key (CMK), configure your KMS provider and automatic encryption settings, and create an encryption-enabled client and collection.
Perform Encrypted Operations: Insert a document with encrypted fields, query on an encrypted field, and run the application to view the decrypted results.

Select your driver language in the drop-down menu to learn how to create an application that automatically encrypts and decrypts document fields.

Important

Do Not Use this Sample Application In Production

Because the instructions in this tutorial include storing an encryption key in an insecure environment, you should not use an unmodified version of this application in production. Using this application in production risks unauthorized access to the encryption key or loss of the key needed to decrypt your data. The purpose of this tutorial is to demonstrate how to use Queryable Encryption without needing to set up a Key Management System.

You can use a Key Management System to securely store your encryption key in a production environment. A KMS is a remote service that securely stores and manages your encryption keys. To learn how to set up a Queryable Encryption enabled application that uses a KMS, see the Queryable Encryption Tutorials.

Before You Begin

Before you begin this tutorial, complete the following prerequisite steps:

Download the Automatic Encryption Shared Library from the MongoDB Download Center. Navigate to the MongoDB Enterprise Server Download section and select the following options:
- In the Version dropdown, select the version marked as "current".
- In the Platform dropdown, select your platform.
- In the Package dropdown, select crypt_shared.
Extract the archive and save the path to the shared library file for future use.

Note
Query Analysis Component
The Automatic Encryption Shared Library is a preferred alternative to mongocryptd and does not require spawning a new process to perform automatic encryption. This tutorial uses the Automatic Encryption Shared Library.
Configure a MongoDB Atlas cluster or a local replica set deployment, and save your connection string for future use. To learn more, see the Get Started tutorial.

Note
MongoDB Community Edition doesn't support Queryable Encryption with Automatic Encryption.
Ensure your database user has dbAdmin permissions on the following namespaces:
- encryption.__keyVault
- medicalRecords database

Full Application Code

Procedure

In this tutorial, you created an application that automatically encrypts and decrypts the ssn and billing fields in your patients collection. Because your application uses an encrypted client, the query returns the decrypted field values. A client that is not configured with your encryption keys would see the encrypted values for those fields instead.

Learn More

To view a tutorial on production-ready Queryable Encryption with a remote KMS, see Queryable Encryption Tutorials.

To learn how Queryable Encryption works, see Queryable Encryption 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 Encryption Keys and Key Vaults page.
See how KMS Providers manage your Queryable Encryption keys on the KMS Providers page.

Back

Features

Fundamentals