Automatic Client-Side Field Level Encryption

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 the LIBMONGOCRYPT_PATH environment variable accordingly.

Install the automatic encryption shared library (Ruby driver 2.19+)

If you use the Ruby driver version 2.19 and above, the automatic encryption shared library should be installed by following the instructions on the Automatic Encryption Shared Library for Queryable Encryption page in the Server manual.

The steps required are as follows:

1. Navigate to the MongoDB Download Center

2. From the Version dropdown, select x.y.z (current) (the latest current version).

3. In the Platform dropdown, select your platform.

4. In the Package dropdown, select crypt_shared.

5. Click Download.

Once extracted, ensure the full path to the library is configured within your mongoid.yml as follows:

development:
  clients:
    default:
      options:
        auto_encryption_options:
          extra_options:
            crypt_shared_lib_path: '/path/to/mongo_crypt_v1.so'

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.

Add ffi to your Gemfile

The MongoDB Ruby driver uses the ffi gem to call functions from libmongocrypt. As this gem is not a dependency of the driver, it will need to be manually added to your Gemfile:

gem 'ffi'

Known Limitations

• MongoDB CSFLE has some limitations that are described on the CSFLE Limitations page in the Server manual. 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.

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.

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:

development:
  clients:
    key_vault:
      uri: mongodb+srv://user:pass@anothercluster.mongodb.net/blog_development?retryWrites=true&w=majority
    default:
      uri: mongodb+srv://user:pass@yourcluster.mongodb.net/blog_development?retryWrites=true&w=majority
      options:
        auto_encryption_options:
          key_vault_client: :key_vault # Client to connect to key vault
          # ...

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:

# Create a key vault client
key_vault_client = Mongo::Client.new('mongodb+srv://user:pass@yourcluster.mongodb.net')
# Or, if you declared the key value client in mongoid.yml, use it
key_vault_client = Mongoid.client(:key_vault)
# Create the encryption object
encryption = Mongo::ClientEncryption.new(
  key_vault_client,
  key_vault_namespace: 'encryption.__keyVault',
  kms_providers: {
    aws: {
      "accessKeyId": "<IAM User Access Key ID>",
      "secretAccessKey": "<IAM User Secret Access Key>"
    }
  }
)
encryption.rewrap_many_data_key(
  {}, # We want to rewrap all keys
  {
    provider: 'aws',
    master_key: {
      region: 'us-east-2',
      key: 'arn:aws:kms:us-east-2:...'
    }
  }
)

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:

# We assume that there are two documents in the database, one created without
# encryption enabled, and one with encryption.
# We can still read both.
Patient.all.to_a
# =>
# [#<Patient _id: 644937ac46ebfd02468e58c8, category: "ER", passport_id: "DE-1257", blood_type: "AB+", ssn: 123456>,
# #<Patient _id: 644937c946ebfd029309b912, category: "ER", passport_id: "AT-1545", blood_type: "AB+", ssn: 987654>]
# But when we query, we can see only the latter one.
Patient.where(blood_type: 'AB+').to_a
# => [#<Patient _id: 644937c946ebfd029309b912, category: "ER", passport_id: "AT-1545", blood_type: "AB+", ssn: 987654>]

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 native null).

• This operation requires application downtime.