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.

Data Encryption Key¶

The MedcoMD engineers created a single data key to use when encrypting all fields in the data model. To configure this, they specify the encryptMetadata key at the root level of the JSON Schema. As a result, all encrypted fields defined in the properties field of the schema will inherit this encryption key unless specifically overwritten.

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

MedcoMD engineers create JSON objects for each field and append them to the properties map.

SSN¶

The ssn field represents the patient's social security number. This field is sensitive and should be encrypted. MedcoMD engineers decide upon deterministic encryption based on the following properties:

• Queryable
• High cardinality

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

Blood Type¶

The bloodType field represents the patient's blood type. This field is sensitive and should be encrypted. MedcoMD engineers decide upon random encryption based on the following properties:

• No plans to query
• Low cardinality

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

Medical Records¶

The medicalRecords field is an array that contains a set of medical record documents. Each medical record document represents a separate visit and specifies information about the patient at that time, such as their blood pressure, weight, and heart rate. This field is sensitive and should be encrypted. MedcoMD engineers decide upon random encryption based on the following properties:

• Array fields must use random encryption with CSFLE to enable auto-encryption

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

Insurance Policy Number¶

The insurance.policyNumber field is embedded inside the insurance field and represents the patient's policy number. This policy number is a distinct and sensitive field. MedcoMD engineers decide upon deterministic encryption based on the following properties:

• Queryable
• High cardinality

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

Recap¶

MedcoMD engineers created a JSON Schema that satisfies their requirements of making sensitive data queryable and secure. View the full JSON Schema for the Medical Care Management System.

About the Mongocryptd Application¶

The MongoDB client communicates with a separate encryption application called mongocryptd which automates the client-side field level encryption. This application is installed with MongoDB Enterprise Server (version 4.2 and later).

When we create a CSFLE-enabled MongoDB client, the mongocryptd process is automatically started by default, and handles the following responsibilities:

• Validates the encryption instructions defined in the JSON Schema and flags the referenced fields for encryption in read and write operations.
• Prevents unsupported operations from being executed on encrypted fields.

When the mongocryptd process is started with the client driver, you can provide configurable parameters including:

auto_encryption_opts = AutoEncryptionOpts(mongocryptd_spawn_args=['--port=30000'])

auto_encryption_opts = AutoEncryptionOpts(mongocryptd_spawn_args=['--idleShutdownTimeoutSecs=75'])

For additional information on mongocryptd, refer to the mongocryptd manual page.

The MedcoMD engineers use the following procedure to configure and instantiate the MongoDB client:

key_vault_namespace = "encryption.__keyVault"

kms_providers = {
  "local": {
    "key": local_master_key
  }
}

patient_schema = {
  "medicalRecords.patients": json_schema
}

extra_options = {
   'mongocryptd_spawn_path': '/usr/local/bin/mongocryptd'
}

 extra_options['mongocryptd_bypass_spawn'] = True

fle_opts = AutoEncryptionOpts(
   kms_providers,
   key_vault_namespace,
   schema_map=patient_schema,
   **extra_options
)
client = MongoClient(connection_string, auto_encryption_opts=fle_opts)

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:

def insert_patient(collection, name, ssn, blood_type, medical_records, policy_number, provider):
  insurance = {
    'policyNumber': policy_number,
    'provider': provider
  }
  doc = {
      'name': name,
      'ssn': ssn,
      'bloodType': blood_type,
      'medicalRecords': medical_records,
      'insurance': insurance
  }
  collection.insert_one(doc)

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=="
    }
}

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
    }
}

Query for Documents on a Randomly Encrypted Field¶

MedcoMD engineers determined that the fields they randomly encrypted would not be used to find patients records. Had this been required, for example, if the patient's ssn was randomly encrypted, MedcoMD engineers could have included another plain-text field called last4ssn that contains the last 4 digits of the ssn field. They could then query on this field as a proxy for the ssn.

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