- Tutorials >
- Automatic Client-Side Field Level Encryption
Automatic Client-Side Field Level Encryption¶
On this page
Since version 4.2 MongoDB supports Client-Side Field Level Encryption (CSFLE). This is a feature that enables you to encrypt data in your application before you send it over the network to MongoDB. With CSFLE enabled, no MongoDB product has access to your data in an unencrypted form.
You can set up CSFLE using the following mechanisms:
- 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.
Starting with version 9.0, Mongoid supports CSFLE’s Automatic Encryption feature. This tutorial walks you through the process of setting up and using CSFLE in Mongoid.
Note
This tutorial does not cover all CSLFE features. You can find more information about MongoDB CSFLE in the server documentation.
Note
If you want to use explicit FLE, please follow the Ruby driver documentation.
Installation¶
You can find the detailed description of how to install the necessary dependencies in the driver documentation.
Note the version of the Ruby driver being used in your application and select the appropriate steps below.
Install libmongocrypt
¶
This can be done one of two ways.
- Add the libmongocrypt-helper gem to
your
Gemfile
or - Download the
libmongocrypt
release archive, extract the version that matches your operating system, and set theLIBMONGOCRYPT_PATH
environment variable accordingly.
Install the mongocryptd
(Ruby driver 2.18 or older)¶
If you are using an older version of the Ruby driver mongocryptd
will
need to be installed manually. mongocryptd
comes pre-packaged with
enterprise builds of the MongoDB server (versions 4.2 and newer).
For installation instructions, see the MongoDB manual.
Create a Customer Master Key¶
A Customer Master Key (CMK) is used to encrypt Data Encryption Keys. The easiest way is to use a locally stored 96-bytes key. You can generate such a key using the following Ruby code:
Later in this tutorial we assume that the Customer Master Key is
available from the CUSTOMER_MASTER_KEY
environment variable.
Warning
Using a local master key is insecure. It is recommended that you use a remote Key Management Service to create and store your master key. To do so, follow steps of the “Set up a Remote Master Key” in the MongoDB Client-Side Encryption documentation.
For more information about creating a master key, see the Create a Customer Master Key section of the MongoDB manual.
Configure Clients¶
Automatic CSFLE requires some additional configuration for the MongoDB client.
Assuming that your application has just one default
client, you need to
add the following to your mongoid.yml
:
Create a Data Encryption Key¶
A Data Encryption Key (DEK) is the key you use to encrypt the fields in your MongoDB documents. You store your Data Encryption Key in your Key Vault collection encrypted with your CMK.
To create a DEK in Mongoid you can use the
db:mongoid:encryption:create_data_key
Rake
task:
You can create multiple DEKs, if necessary.
You can also provide an alternate name for the DEK. This allows you to reference the DEK by name when configuring encryption for your fields. It also allows you to dynamically assign a DEK to a field at runtime.
Configure Encryption Schema¶
Now we can tell Mongoid what should be encrypted:
Note
If you are developing a Rails application, it is recommended to set
preload_models
to true
in mongoid.yml
. This will ensure that
Mongoid loads all models before the application starts, and the encryption
schema is configured before any data is read or written.
Known Limitations¶
- MongoDB CSFLE has some limitations that are described in the server documentation. These limitations also apply to Mongoid.
- Mongoid does not support encryption of
embeds_many
relations. - If you use
:key_name_field
option, the field must be encrypted using non-deterministic algorithm. To encrypt your field deterministically, you must specify:key_id
option instead.
Working with Data¶
Automatic CSFLE usage is transparent in many situations.
Note
In code examples below we assume that there is a variable unencrypted_client
that is a MongoClient
connected to the same database but without encryption.
We use this client to demonstrate what is actually persisted in the database.
Documents can be created as usual, fields will be encrypted and decrypted according to the configuration:
Fields encrypted using a deterministic algorithm can be queried. Only exact match queries are supported. For more details please consult the server documentation.
Encryption Key Management¶
Customer Master Keys¶
Your Customer Master Key is the key you use to encrypt your Data Encryption Keys. MongoDB automatically encrypts Data Encryption Keys using the specified CMK during Data Encryption Key creation.
The CMK is the most sensitive key in CSFLE. If your CMK is compromised, all of your encrypted data can be decrypted.
Important
Ensure you store your Customer Master Key (CMK) on a remote KMS.
To learn more about why you should use a remote KMS, see Reasons to Use a Remote KMS.
To view a list of all supported KMS providers, see the KMS Providers page.
- MongoDB CSFLE supports the following Key Management System (KMS) providers:
- Amazon Web Services KMS
- Azure Key Vault
- Google Cloud Platform KMS
- Any KMIP Compliant Key Management System
- Local Key Provider (for testing only)
Data Encryption Keys¶
Data Encryption Keys can be created using the
db:mongoid:encryption:create_data_key
Rake
task. By default they are
stored on the same cluster as the database.
However, it might be a good idea to store the keys separately. This can be
done by specifying a key vault client in mongoid.yml
:
Encryption Keys Rotation¶
You can rotate encryption keys using the rewrap_many_data_key
method
of the Ruby driver. This method automatically decrypts multiple data encryption
keys and re-encrypts them using a specified CMK. It then updates
the rotated keys in the key vault collection. This method allows you to rotate
encryption keys based on two optional arguments:
- A filter used to specify which keys to rotate. If no data key matches the given filter, no keys will be rotated. Omit the filter to rotate all keys in your key vault collection.
- An object that represents a new CMK. Omit this object to rotate the data keys using their current CMKs.
Here is an example of rotating keys using AWS KMS:
Adding Automatic Encryption To Existing Project¶
MongoDB automatic CSFLE supports encryption in place. You can enable encryption for your existing database, and will still able to read unencrypted data. All data written to the database will be encrypted. However, as soon as the encryption is enabled, all query operations will use encrypted data:
If you want to encrypt the existing database, it can be achieved by reading and writing back all data, even without any changes. If you decide to do so, please keep the following in mind:
- Validate the integrity of existing data for consistent fidelity. CSFLE is
type sensitive - for example you cannot store integers in a field that is
declared as
String
. - For strings, make sure that empty values are always empty strings or just
not set, but not
nil
(CSFLE doesn’t support nativenull
). - This operation requires application downtime.