Encryption Schemas

encrypt Keyword

The encrypt keyword defines an encryption rule for a single field in a BSON document. Encryption rules containing the encrypt keyword have the following structure:

"<field-name-to-encrypt>": {
  "encrypt": {
    "algorithm": "<encryption algorithm to use>",
    "bsonType": "<bson type of field>",
    "keyId": [UUID("<_id of your Data Encryption Key>" )]
  }
}

encryptMetadata Keyword

The encryptMetadata keyword defines encryption rules which child elements of the sibling properties tag inherit. Encryption rules containing encryptMetadata have the following structure:

"bsonType": "object",
"encryptMetadata": {
  "algorithm": "<encryption algorithm inherited by children of properties field>",
  "keyId": [UUID("<_id of your Data Encryption Key>" )]
},
"properties": { <object to inherit encryptMetadata values> }

patternProperties Keyword

You can use the patternProperties keyword in your encryption schema to define encryption rules for all fields with names that match a regular expression. This allows you to specify multiple fields for encryption based on a single regular expression, or to specify them by only using a part of the field name. The patternProperties keyword replaces properties in your encryption schema.

Specify encryption rules with patternProperties using the following structure:

"bsonType": "object",
"patternProperties": {
    "<regular expression to match>": {
    "encrypt": {
        "algorithm": "<encryption algorithm to use>",
        "bsonType": "<bson type of field>",
        "keyId": [UUID("<_id of your Data Encryption Key>" )]
    }
}

To see an example of how to use patternProperties see Encryption Schema - Encrypt with Pattern Properties

Specify the Namespace

At the root of your encryption schema, specify the namespace to which your encryption schema applies. Specify the following to encrypt and decrypt documents in the patients collection of the medicalRecords database:

{
  "medicalRecords.patients": {
    <the schema created in the following steps of this example>
  }
}

Specify the Data Encryption Key

In the Quick Start, you encrypt all fields of your document with a single Data Encryption Key (DEK). To configure all fields in your documents to use a single DEK for encryption and decryption, specify the _id of your DEK with the encryptMetadata keyword at the root of your encryption schema as follows:

{
  "medicalRecords.patients": {
    "bsonType": "object",
    "encryptMetadata": {
     "keyId": [UUID("<_id of your Data Encryption Key>" )]
   },
    "properties": {
      <the schema created in the following steps of this example>
    }
  }
}

Choose Encryption Rules

You decide to encrypt the following fields with the following encryption algorithms:

You choose to encrypt the ssn and insurance.policyNumber fields with deterministic encryption for the following reasons:

• You want to be able to query on these fields.

• The values in these fields have a high cardinality, so this data is not susceptible to a frequency analysis attack.

You choose to encrypt the bloodType field with random encryption for the following reasons:

• You do not plan to query on this field.

• The values in this field have low cardinality, making them susceptible to a frequency analysis attack if you encrypted them deterministically.

You must encrypt the medicalRecords field with random encryption as CSFLE does not support deterministic encryption of fields of type array.

Specify Encryption Rules

To encrypt the ssn field with deterministic encryption, specify the following in your encryption schema:

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

To encrypt the bloodType field with random encryption, specify the following in your encryption schema:

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

To encrypt the medicalRecords field with random encryption, specify the following in your encryption schema:

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

To encrypt the insurance.policyNumber field with deterministic encryption, specify the following in your encryption schema:

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

View the Complete Schema

The complete encryption schema for the Quick Start is as follows:

{
  "medicalRecords.patients": {
    "bsonType": "object",
    "encryptMetadata": {
     "keyId": [UUID("<_id of your Data Encryption Key>" )]
   },
    "properties": {
      "insurance": {
        "bsonType": "object",
        "properties": {
          "policyNumber": {
            "encrypt": {
              "bsonType": "int",
              "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
            }
          }
        }
      },
      "medicalRecords": {
        "encrypt": {
          "bsonType": "array",
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
        }
      },
      "bloodType": {
        "encrypt": {
          "bsonType": "string",
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
        }
      },
      "ssn": {
        "encrypt": {
          "bsonType": "int",
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
        }
      }
    }
  }
}