Before you can use Queryable Encryption, you must set up the following items in your development environment:
- Download the Automatic Encryption Shared Library (recommended) or mongocryptd properly configured/setup
- Install a MongoDB Driver Compatible with Queryable Encryption
- Atlas Cluster running MongoDB 6.2
- Install specific driver dependencies.
- Azure KMS + Azure KeyVault + Azure Key (which will be our "master key")
For this tutorial/demo, need to have mongocryptd or the shared_lib properly configured. This is a critical step
https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/shared-library https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/mongocryptd/
- Automatic Encryption: Enables you to perform encrypted read and write operations without you having to write code to specify how to encrypt fields.
- Explicit Encryption: Enables you to perform encrypted read and write operations through your MongoDB driver's encryption library. You must specify the logic for encryption with this library throughout your application.
Today we will be focusing on Automatic Encryption using MongoDB Atlas. But before, lets talk a little bit about Envelope Encryption - which is what Queryable Encryption uses under the hood.
An analogy that helped me understand this was - think of a "Lockbox".
We will have a Customer Master Key (CMK) - which in our analogy will be the combination to the lockbox itself. And with this CMK, we will protect the "keys inside".
The "keys inside" are going to be called the Data Encryption Keys (DEK). These are the keys that will be used to actually encrypt/decrypt the fields. And access to them will be protected by the CMK.
Automatic encryption essentially fetches the keys from the keyvault automatically and lets you get straight to encrypting/decrypting. To encrypt/decrypt your fields automatically, you must configure your MongoClient instance as follows:
- Specify your Key Vault collection
- Specify a kmsProviders object
Then, we can use the keyVault and DEKs to create an encrypted collection, and include details about what fields will be encrypted as well as what query_types will be supported for those fields.
Setup your encrypted client with your KMS configuration and autoencrypt settings, and you're good to go.
You can use these credentials to set up In-Use Encryption from Compass by setting up these Advanced Connection Settings
Update your CMK using Azure KMS. Get the new key version. Login to your mongoshell (mongosh). And call KeyVault.rewrapManyDataKey() with the new Key Version. This method Decrypts multiple Data Encryption Keys (DEK) and re-encrypts them with a new Customer Master Key (CMK).
https://www.mongodb.com/docs/manual/reference/method/KeyVault.rewrapManyDataKey/
Key Management Best Practices
https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final
https://csrc.nist.gov/publications/detail/sp/800-57-part-2/rev-1/final
https://csrc.nist.gov/publications/detail/sp/800-57-part-3/rev-1/final
https://github.com/mongodb-university/docs-in-use-encryption-examples
is where I got most of the source code. I just modified a few things
cd node
npm i
node make_data_key.js
which sets up the encrypted collection with the supported queries and kms confignode insert_encrypted_document.js
cd java
mvn clean compile
mvn compile exec:java -Dexec.mainClass="com.mongodb.qe.MakeDataKey" -Dexec.cleanupDaemonThreads=false
mvn compile exec:java -Dexec.mainClass="com.mongodb.qe.InsertEncryptedDocument" -Dexec.cleanupDaemonThreads=false