Client-Side Field Level Encryption Guide¶

Scenario¶

In this scenario, we secure sensitive data on a Medical Care Management System which stores patients' personal information, insurance information, and medical records for a fictional company, MedcoMD. None of the patient data is public, and certain data such as their social security number (SSN, a US government-issued id number), insurance policy number, and vital sign measurements are particularly sensitive and subject to privacy compliance. It is important for the company and the patient that the data is kept private and secure.

MedcoMD needs this system to satisfy the following use cases:

• Doctors use the system to access Patients' medical records, insurance information, and add new vital sign measurements.
• Receptionists use the system to verify the Patients' identity, using a combination of their contact information and the last four digits of their Social Security Number (SSN).
• Receptionists can view a Patient's insurance policy provider, but not their policy number.
• Receptionists cannot access a Patient's medical records.

MedcoMD is also concerned with disclosure of sensitive data through any of the following methods:

• Accidental disclosure of data on the Receptionist's publicly-viewable screen.
• Direct access to the database by a superuser such as a database administrator.
• Capture of data over an insecure network.
• Access to the data by reading a server's memory.
• Access to the on-disk data by reading database or backup files.

What can MedcoMD do to balance the functionality and access restrictions of their Medical Care Management System?

Comparison of Security Features¶

The MedcoMD engineers review the Medical Care Management System specification and research the proper solution for limiting access to sensitive data.

The first MongoDB security feature they evaluated was Role-Based Access Control which allows administrators to grant and restrict collection-level permissions for users. With the appropriate role definition and assignment, this solution prevents accidental disclosure of data and access. However, it does not prevent capture of the data over an insecure network, direct access of data by a superuser, access to data by reading the server's memory, or access to on-disk data by reading the database or backup files.

The next MongoDB security features they evaluated were Encryption at Rest which encrypts the database files on disk and Transport Encryption using TLS/SSL which encrypts data over the network. When applied together, these two features prevent access to on-disk database files as well as capture of the data on the network, respectively. When combined with Role-Based Access Control, these three security features offer near-comprehensive security coverage of the sensitive data, but lack a mechanism to prevent the data from being read from the server's memory.

Finally, the MedcoMD engineers discovered a feature that independently satisfies all the security criteria. Client-side Field Level Encryption allows the engineers to specify the fields of a document that should be kept encrypted. Sensitive data is transparently encrypted/decrypted by the client and only communicated to and from the server in encrypted form. This mechanism keeps the specified data fields secure in encrypted form on both the server and the network. While all clients have access to the non-sensitive data fields, only appropriately-configured CSFLE clients are able to read and write the sensitive data fields.

The following diagram is a list of MongoDB security features offered and the potential security vulnerabilities that they address:

MedcoMD will provide Receptionists with a client that is not configured to access data encrypted with CSFLE. This will prevent them from viewing the sensitive fields and accidentally leaving them displayed on-screen in a public area. MedcoMD will provide Doctors with a client with CSFLE enabled which will allow them to access the sensitive data fields in the privacy of their own office.

Equipped with CSFLE, MedcoMD can keep their sensitive data secure and compliant to data privacy regulations with MongoDB.

Requirements¶

MongoDB Server 4.2 Enterprise

• For installation instructions, refer to the Enterprise Edition Installation Tutorials.

MongoDB Driver Compatible with CSFLE

• For a list of drivers that support CSFLE, refer to the driver compatibility table.

File System Permissions

• The client application or a privileged user needs permissions to start the mongocryptd process on the host.

Additional Dependencies

• Additional dependencies for specific language drivers are required to use CSFLE or run through examples in this guide. To see the list, select the appropriate driver tab below.

A. Create a Master Key¶

MongoDB Client-Side Field Level Encryption (CSFLE) uses an encryption strategy called envelope encryption in which keys used to encrypt/decrypt data (called data encryption keys) are encrypted with another key (called the master key). For more information on the features of envelope encryption and key management concepts, see AWS Key Management Service Concepts.

In this step, we create and store the master key, used by the MongoDB driver to encrypt data encryption keys, in the Local Key Provider which is the filesystem in our local development environment. We refer to this key as the "locally-managed master key" in this guide.

The following diagram shows how the master key is created and stored:

The data encryption keys, generated and used by the MongoDB driver to encrypt and decrypt document fields, are stored in a key vault collection in the same MongoDB replica set as the encrypted data.

To begin development, MedcoMD engineers generate a master key and save it to a file with the fully runnable code below:

using System;
using System.IO;
class Program
{
    public void Main(string []args)
    {
        using (var randomNumberGenerator = System.Security.Cryptography.RandomNumberGenerator.Create())
        {
            var bytes = new byte[96];
            randomNumberGenerator.GetBytes(bytes);
            var localMasterKeyBase64 = Convert.ToBase64String(bytes);
            Console.WriteLine(localMasterKeyBase64);
            File.WriteAllText(__localMasterKeyPath, localMasterKeyBase64);
        }
    }
}

B. Create a Data Encryption Key¶

In this section, we generate a data encryption key. The MongoDB driver stores the key in a key vault collection where CSFLE-enabled clients can access the key for automatic encryption and decryption.

The following diagram shows how the data encryption keys are created and stored:

The client requires the following configuration values to generate a new data encryption key:

• The locally-managed master key.
• A MongoDB connection string that authenticates on a running server.
• The key vault namespace (database and collection).
• A unique index for the key vault collection on the keyAltNames field

Follow the steps below to generate a single data encryption key from the locally-managed master key.

string localMasterKeyBase64 = File.ReadAllText(__localMasterKeyPath);
var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64);

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
var localOptions = new Dictionary<string, object>
{
    { "key", localMasterKeyBytes }
};
kmsProviders.Add("local", localOptions);

var keyVaultClient = new MongoClient(_connectionString);
var clientEncryptionOptions = new ClientEncryptionOptions(
    keyVaultClient: keyVaultClient,
    keyVaultNamespace: _keyVaultNamespace,
    kmsProviders: kmsProviders);
var clientEncryption = new ClientEncryption(kmsProviders);
var dataKeyId = clientEncryption.CreateDataKey("local", new DataKeyOptions(), CancellationToken.None);
Console.WriteLine($"Local DataKeyId [UUID]: {dataKeyId}");
var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));
Console.WriteLine($"Local DataKeyId [base64]: {dataKeyIdBase64}");

DataKeyId [UUID]: de4d775a-4499-48bc-bb93-3f81c3c90704
DataKeyId [base64]: 3k13WkSZSLy7kwAAP4HDyQ==

var client = new MongoClient("mongodb://localhost:27017");
// dataKeyId is the UUID from the previous step that was printed
// to the console
var dataKeyId = "<paste your dataKeyId value here>"
var collection = client
    .GetDatabase(_keyVaultNamespace.DatabaseNamespace.DatabaseName)
    .GetCollection<BsonDocument>(
        _keyVaultNamespace.CollectionName,
        new MongoCollectionSettings
        {
            GuidRepresentation = GuidRepresentation.Standard
         });
var query = Builders<BsonDocument>.Filter.Eq("_id", new BsonBinaryData(dataKeyId, GuidRepresentation.Standard));
var keyDocument = collection
    .Find(query)
    .Single();
Console.WriteLine(keyDocument);

{
  "_id" : CSUUID("aae4f3b4-91b6-4cef-8867-3113a6dfb27b"),
  "keyMaterial" : new BinData(0, "rcfTQLRxF1mg98/Jr7iFwXWshvAVIQY6JCswrW+4bSqvLwa8bQrc65w7+3P3k+TqFS+1Ce6FW4Epf5o/eqDyT//I73IRc+yPUoZew7TB1pyIKmxL6ABPXJDkUhvGMiwwkRABzZcU9NNpFfH+HhIXjs324FuLzylIhAmJA/gvXcuz6QSD2vFpSVTRBpNu1sq0C9eZBSBaOxxotMZAcRuqMA=="),
  "creationDate" : ISODate("2020-11-08T17:58:36.372Z"),
  "updateDate" : ISODate("2020-11-08T17:58:36.372Z"),
  "status" : 0,
  "masterKey" : {
     "provider" : "local"
  }
}

C. Specify Encrypted Fields Using JSON Schema¶

MongoDB drivers use an extended version of the JSON Schema standard to configure automatic client-side encryption and decryption of specific fields of the documents in a collection.

The MongoDB CSFLE extended JSON Schema standard requires the following information:

• The encryption algorithm to use when encrypting each field (Deterministic Encryption or Random Encryption)
• One or more data encryption keys encrypted with the CSFLE master key
• The BSON Type of each field (only required for deterministically encrypted fields)

The MedcoMD engineers receive specific requirements for the fields of data and their encryption strategies. The following table illustrates the data model of the Medical Care Management System.

{
    "bsonType" : "object",
    "encryptMetadata" : {
        "keyId" : // copy and paste your keyId generated here
    },
    "properties": {
        // copy and paste your field schemas here
    }
}

"ssn": {
    "encrypt": {
        "bsonType": "int",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
    }
}

"bloodType": {
    "encrypt": {
        "bsonType": "string",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
    }
}

"medicalRecords": {
    "encrypt": {
        "bsonType": "array",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
    }
}

"insurance": {
    "bsonType": "object",
    "properties": {
        "policyNumber": {
            "encrypt": {
                "bsonType": "int",
                "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
            }
        }
    }
}

D. Create the MongoDB Client¶

The MedcoMD engineers now have the JSON Schema and encryption keys necessary to create a CSFLE-enabled MongoDB client.

They build the client to communicate with a MongoDB cluster and perform actions such as securely reading and writing documents with encrypted fields.

var extraOptions = new Dictionary<string, object>()
{
    { "mongocryptdSpawnArgs", new [] { "--port=30000" } },
};
autoEncryptionOptions.With(extraOptions: extraOptions);

var extraOptions = new Dictionary<string, object>()
{
    { "idleShutdownTimeoutSecs", 60 },
};
autoEncryptionOptions.With(extraOptions: extraOptions);

var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
var localMasterKeyBase64 = File.ReadAllText(__localMasterKeyPath);
var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64);
var localOptions = new Dictionary<string, object>
{
    { "key", localMasterKeyBytes }
};
kmsProviders.Add("local", localOptions);

// JsonSchemaCreator is a utility class found in the C# companion
// project to this guide
var schema = JsonSchemaCreator.CreateJsonSchema(keyIdBase64);

var extraOptions = new Dictionary<string, object>()
{
    { "mongocryptdSpawnPath", $@"{MongoBinariesPath}\mongocryptd.exe" },
};

var clientSettings = MongoClientSettings.FromConnectionString(_connectionString);
var autoEncryptionOptions = new AutoEncryptionOptions(
    keyVaultNamespace: keyVaultNamespace,
    kmsProviders: kmsProviders,
    schemaMap: schemaMap,
    extraOptions: extraOptions);
clientSettings.AutoEncryptionOptions = autoEncryptionOptions;
var client = new MongoClient(clientSettings);

E. Perform Encrypted Read/Write Operations¶

The MedcoMD engineers now have a CSFLE-enabled client and can test that the client can perform queries that meet the requirements. Doctors should be able to read and write to all fields, and receptionists should only be allowed to read and write to non-sensitive fields.

Insert a Document with Encrypted Fields¶

The following diagram shows the steps taken by the client application and driver to perform a write of field-level encrypted data:

MedcoMD engineers write a function to create a new patient record with the following code snippet:

C#GoJava (Sync)Node.jsPython

var sampleSsnValue = 145014000;
var sampleNameValue = "John Doe";
BsonDocument sampleDocFields =
    new BsonDocument
    {
        { "name", sampleNameValue },
        { "ssn", sampleSsnValue },
        { "bloodType", "AB-" },
        {
            "medicalRecords",
            new BsonArray(new []
            {
                new BsonDocument("weight", 180),
                new BsonDocument("bloodPressure", "120/80")
            })
        },
        {
            "insurance",
            new BsonDocument
            {
                { "policyNumber", 123142 },
                { "provider", "MaestCare" }
            }
        }
    };
   // Construct an auto-encrypting client
   var autoEncryptingClient = CreateAutoEncryptingClient(
       kmsKeyLocation,
       _keyVaultNamespace,
       schema);
   var collection = autoEncryptingClient
       .GetDatabase(_medicalRecordsNamespace.DatabaseNamespace.DatabaseName)
       .GetCollection<BsonDocument>(_medicalRecordsNamespace.CollectionName);
   // Insert a document into the collection
   collection.UpdateOne(ssnQuery, new BsonDocument("$set", __sampleDocFields), new UpdateOptions() { IsUpsert = true });
   Console.WriteLine("Successfully upserted the sample document!");
   Console.WriteLine($"Encrypted client query by the SSN (deterministically-encrypted) field:\n {result}\n");

When a CSFLE-enabled client inserts a new patient record into the Medical Care Management System, it automatically encrypts the fields specified in the JSON Schema. This operation creates a document similar to the following:

{
    "_id": "5d7a7bbe6d58fd263b6d7315",
    "name": "Jon Doe",
    "ssn": "Ac+ZbPM+sk7gl7CJCcIzlRAQUJ+uo/0WhqX+KbTNdhqCszHucqXNiwqEUjkGlh7gK8pm2JhIs/P3//nkVP0dWu8pSs6TJnpfUwRjPfnI0TURzQ==",
    "bloodType": "As+ZbPM+sk7gl7CJCcIzlRACESwHCTCtK/lQV9kF6/LRoL3mh59gzBVA42vGBVfLIycYWpfAy7ZCi2eRGEgMX5CrGl259Wfu6Zf/ELBVqQDnyQ==",
    "medicalRecords": "As+ZbPM+sk7gl7CJCcIzlRAEFt249toVYOlvlC/79cAtQ5jvE/ukF1ZLxRZn1g0zBBtPnf6L0AFTKMVdNJnjMGPMTszYU58qRE9uMvCU05DVHYl8DJnbtGXXFRLJ7ElQOc=",
    "insurance": {
        "provider": "MaestCare",
        "policyNumber": "Ac+ZbPM+sk7gl7CJCcIzlRAQm7kFhN1hy3l7Wt3BSpBMbvVSuiaDsf3UPF9bvJLTEcC+Ka+3kZI4SVZinj4tyc5uDYeyh6+7phpKrQo4CHWyg=="
    }
}

Note

Clients that do not have CSFLE configured will insert unencrypted data. We recommend using server-side schema validation to enforce encrypted writes for fields that should be encrypted.

Query for Documents on a Deterministically Encrypted Field¶

The following diagram shows the steps taken by the client application and driver to query and decrypt field-level encrypted data:

You can run queries on documents with encrypted fields using standard MongoDB driver methods. When a doctor performs a query in the Medical Care Management System to search for a patient by their SSN, the driver decrypts the patient's data before returning it:

{
    "_id": "5d6ecdce70401f03b27448fc",
    "name": "Jon Doe",
    "ssn": 241014209,
    "bloodType": "AB+",
    "medicalRecords": [
        {
            "weight": 180,
            "bloodPressure": "120/80"
        }
    ],
    "insurance": {
        "provider": "MaestCare",
        "policyNumber": 123142
    }
}

Note

For queries using a client that is not configured to use CSFLE, such as when receptionists in the Medical Care Management System search for a patient with their ssn, a null value is returned. A client without CSFLE configured cannot query on a sensitive field.

{
    "_id": "5d6ecdce70401f03b27448fc",
    "name": "Jon Doe",
    "ssn": 241014209,
    "last4ssn": 4209,
    "bloodType": "AB+",
    "medicalRecords": [
        {
            "weight": 180,
            "bloodPressure": "120/80"
        }
    ],
    "insurance": {
        "provider": "MaestCare",
        "policyNumber": 123142
    }
}

Download Example Project¶

To view and download a runnable example of CSFLE, select your driver below:

Move to Production¶

In this guide, we stored the master key in your local filesystem. Since your data encryption keys would be readable by anyone that gains direct access to your master key, we strongly recommend that you use a more secure storage location such as a Key Management System (KMS).

For more information on securing your master key, see our step-by-step guide to integrating with Amazon KMS.

Further Reading¶

For more information on client-side field level encryption in MongoDB, check out the reference docs in the server manual:

• Client-Side Field Level Encryption
• Automatic Encryption JSON Schema Syntax
• Manage Client-Side Encryption Data Keys