Quick Start
On this page
Overview
This guide shows you how to encrypt a document with automatic Client-Side Field Level Encryption (CSFLE) and a MongoDB driver.
After completing this guide, you should have the following knowledge and software:
Knowledge of the steps to configure a driver to encrypt fields in a document.
A working, but not production-ready, client application that utilizes automatic Client-Side Field Level Encryption.
Important
Do Not Use this Application In Production
Since this example application stores an encryption key on your application's filesystem, you risk unauthorized access to the key or loss of the key to decrypt your data.
To view a tutorial that demonstrates how to create a production-ready CSFLE-enabled application, see Tutorials.
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.
Select the programming language for which you want to see code examples for from the Select your language dropdown menu on the right side of the page.
Tip
See: Full Application
To view the complete runnable application code for this tutorial, go to the following link:
Procedure
Create a Customer Master Key
You must create a Customer Master Key (CMK) to perform CSFLE.
Create a 96-byte Customer Master Key and save it in your Local Key Provider,
which is your filesystem,
as the file master-key.txt:
openssl rand 96 > master-key.txt
Note
Use a Programming Language to Create a Customer Master Key
If you would rather use your preferred programming language to generate your CMK, you can view code snippets demonstrating how to generate a Customer Master Key in each of the supported languages of this guide on GitHub.
Warning
Do Not Use the Local Key Provider in Production
The Local Key Provider is an insecure method of storage and is not recommended for production. Instead, you should store your Customer Master Keys in a remote Key Management System (KMS).
To learn how to use a remote KMS in your CSFLE implementation, see the Tutorials guide.
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:
Create a Data Encryption Key
Read the Customer Master Key and Specify KMS Provider Settings
Retrieve the contents of the Customer Master Key file that you generated in the Create a Customer Master Key step of this guide.
Pass the CMK value to your KMS provider settings. The
client uses these settings to discover the CMK. As
you are using the Local Key Provider, set the provider name to
local.
Create a Data Encryption Key
Construct a client with your MongoDB connection string and Key Vault collection namespace, and create a Data Encryption Key:
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.
The output from the code above should resemble the following:
DataKeyId [base64]: 3k13WkSZSLy7kwAAP4HDyQ==
Tip
See: Complete Code
Configure the MongoClient
Specify the Key Vault Collection Namespace
Specify encryption.__keyVault as the Key Vault collection
namespace.
Specify the Local Customer Master Key
Specify the KMS provider and specify your key inline:
Create an Encryption Schema For Your Collection
Tip
Add Your Data Encryption Key Base64 ID
Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.
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 CSFLE page.
Create the MongoClient
Instantiate a MongoDB client object with the following automatic encryption settings:
Insert a Document with Encrypted Fields
Use your CSFLE-enabled
MongoClient instance to insert an encrypted document into the
medicalRecords.patients namespace using the following code
snippet:
When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:
{ "_id": { "$oid": "<_id of your document>" }, "name": "Jon Doe", "ssn": { "$binary": "<cipher-text>", "$type": "6" }, "bloodType": { "$binary": "<cipher-text>", "$type": "6" }, "medicalRecords": { "$binary": "<cipher-text>", "$type": "6" }, "insurance": { "provider": "MaestCare", "policyNumber": { "$binary": "<cipher-text>", "$type": "6" } } }
Tip
See: Complete Code
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 CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.
The output of the preceding code snippet should look like this:
Finding a document with regular (non-encrypted) client. { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6), bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6), 'key-id': 'demo-data-key', medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6), insurance: { policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6), provider: 'MaestCare' } } Finding a document with encrypted client, searching on an encrypted field { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: 241014209, bloodType: 'AB+', 'key-id': 'demo-data-key', medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ], insurance: { policyNumber: 123142, provider: 'MaestCare' } }
Tip
See: Complete Code
Learn More
To view a tutorial on production-ready CSFLE with a remote KMS, see Tutorials.
To learn how CSFLE works, see Fundamentals.
To learn more about the topics mentioned in this guide, see the following links: