Use Automatic Client-Side Field Level Encryption with AWS

Create the Customer Master Key

1. Log in to your AWS Management Console.
2. Navigate to the AWS KMS Console.

3. Create your Customer Master Key

   Create a new symmetric key by following the official AWS documentation on Creating symmetric KMS keys. The key you create is your Customer Master Key. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration of your CMK.

   In the Usage Permissions step of the key generation process, apply the following default key policy that enables Identity and Access Management (IAM) policies to grant access to your Customer Master Key:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Enable IAM User Permissions",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<ARN of your AWS account principal>"
         },
         "Action": "kms:*",
         "Resource": "*"
       }
     ]
   }

   Important

   Record the Amazon Resource Name (ARN) and Region of your Customer Master Key. You will use these in later steps of this guide.

   Tip

   Learn More

   To learn more about your Customer Master Keys, see Encryption Keys and Key Vaults.

   To learn more about key policies, see Key Policies in AWS KMS in the official AWS documentation.

Create an AWS IAM User

1. Navigate to the AWS IAM Console.

2. Create an IAM User

   Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. You will use this IAM user as a service account for your CSFLE-enabled application. Your application authenticates with AWS KMS using the IAM user to encrypt and decrypt your Data Encryption Keys (DEKs) with your Customer Master Key (CMK).

   Important

   Record your Credentials

   Ensure you record the following IAM credentials in the final step of creating your IAM user:

   • access key ID
   • secret access key

   You have one opportunity to record these credentials. If you do not record these credentials during this step, you must create another IAM user.

3. Grant Permissions

   Grant your IAM user kms:Encrypt and kms:Decrypt permissions for your remote master key.

   Important

   The new client IAM user should not have administrative permissions for the master key. To keep your data secure, follow the principle of least privilege.

   The following inline policy allows an IAM user to encrypt and decrypt with the Customer Master Key with the least privileges possible:

   Note

   Remote Master Key ARN

   The following policy requires the ARN of the key you generate in the Create the Master Key step of this guide.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["kms:Decrypt", "kms:Encrypt"],
         "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
       }
     ]
   }

   To apply the preceding policy to your IAM user, follow the Adding IAM identity permissions guide in the AWS documentation.

   Important

   Authenticate with IAM Roles in Production

   When deploying your CSFLE-enabled application to a production environment, authenticate your application by using an IAM role instead of an IAM user.

   To learn more about IAM roles, see the following pages in the official AWS documentation:

   • IAM roles
   • When to create an IAM role (instead of a user)

Create a Unique Index on your Key Vault collection

Create a unique index on the keyAltNames field in your encryption.__keyVault namespace.

String connectionString = "<Your MongoDB URI>";
String keyVaultDb = "encryption";
String keyVaultColl = "__keyVault";
String keyVaultNamespace = keyVaultDb + "." + keyVaultColl;
MongoClient keyVaultClient = MongoClients.create(connectionString);

// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.
keyVaultClient.getDatabase(keyVaultDb).getCollection(keyVaultColl).drop();
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
keyVaultClient.getDatabase("medicalRecords").getCollection("patients").drop();


MongoCollection keyVaultCollection = keyVaultClient.getDatabase(keyVaultDb).getCollection(keyVaultColl);
IndexOptions indexOpts = new IndexOptions().partialFilterExpression(new BsonDocument("keyAltNames", new BsonDocument("$exists", new BsonBoolean(true) ))).unique(true);
keyVaultCollection.createIndex(new BsonDocument("keyAltNames", new BsonInt32(1)), indexOpts);
keyVaultClient.close();

Create a New Data Encryption Key

1. Add your AWS KMS Credentials

   Add the service account credentials to your CSFLE-enabled client code.

   Map<String, Map<String, Object>> kmsProviderDetails = new HashMap<String, Map<String, Object>>();
   String kmsProvider = "aws";
   Map<String, Object> providerDetails = new HashMap<>();
   providerDetails.put("accessKeyId", new BsonString("<IAM User Access Key ID>"));
   providerDetails.put("secretAccessKey", new BsonString("<IAM User Secret Access Key>"));
   kmsProviderDetails.put(kmsProvider, providerDetails);

   You can also provide a custom name for your KMS provider by passing in a string that includes the name of the KMS provider, followed by a colon and the custom name. Providing a unique name for a KMS provider allows you to specify multiple KMS providers of the same type.

   For example, you can name your AWS KMS provider "my_aws_provider" in your KMS credentials variable as shown in the following code:

   Map<String, Object> kmsProviderDetails = new HashMap<>();
   kmsProviderDetails.put("accessKeyId", getEnv("AWS_ACCESS_KEY_ID")); // Your AWS access key ID
   kmsProviderDetails.put("secretAccessKey", getEnv("AWS_SECRET_ACCESS_KEY")); // Your AWS secret access key
   
   Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>();
   kmsProviderCredentials.put("aws:my_aws_provider", kmsProviderDetails);

   Tip

   To learn how to provide your AWS credentials without directly specifying them as shown in the preceding code example, see the Java MONGODB-AWS documentation.

2. Add Your Key Information

   Update the following code to specify your Customer Master Key:

   Tip

   You recorded your Customer Master Key's ARN and Region in the Create a Customer Master Key step of this guide.

   masterKeyProperties.put("provider", new BsonString(kmsProvider));
   masterKeyProperties.put("key", new BsonString("<Master Key ARN>"));
   masterKeyProperties.put("region", new BsonString("<Master Key AWS Region>"));

3. Generate your Data Encryption Key

   Generate your Data Encryption Key using the variables declared in step one of this tutorial.

   ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder()
           .keyVaultMongoClientSettings(MongoClientSettings.builder()
                   .applyConnectionString(new ConnectionString(connectionString))
                   .build())
           .keyVaultNamespace(keyVaultNamespace)
           .kmsProviders(kmsProviderDetails)
           .build();
   
   MongoClient regularClient = MongoClients.create(connectionString);
   
   ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
   BsonBinary dataKeyId = clientEncryption.createDataKey(kmsProvider, new DataKeyOptions().masterKey(masterKeyProperties));
   String base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());
   System.out.println("DataKeyId [base64]: " + base64DataKeyId);
   clientEncryption.close();

Configure the MongoClient

To view the complete code for this file, see our Github repository.

1. Specify the Key Vault Collection Namespace

   Specify encryption.__keyVault as the Key Vault collection namespace.

   String keyVaultNamespace = "encryption.__keyVault";

2. Specify your AWS Credentials

   Specify the aws KMS provider and your IAM user credentials:

   Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
   String kmsProvider = "aws";
   Map<String, Object> providerDetails = new HashMap<>();
   providerDetails.put("accessKeyId", "<IAM User Access Key ID>");
   providerDetails.put("secretAccessKey", "<IAM User Secret Access Key>");
   kmsProviders.put(kmsProvider, providerDetails);

   Important

   Reminder: Authenticate with IAM Roles in Production

   To use an IAM role instead of an IAM user to authenticate your application, specify an empty object for your credentials in your KMS provider object. This instructs the driver to automatically retrieve the credentials from the environment:

   kmsProviderCredentials.put("aws", new HashMap<>());

   You cannot automatically retrieve credentials if you are using a named KMS provider.

3. Create an Encryption Schema For Your Collection

   Tip

   Add Your Data Encryption Key Base64 ID

   Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.

   String dekId = "<paste-base-64-encoded-data-encryption-key-id>>";
   Document jsonSchema = new Document().append("bsonType", "object").append("encryptMetadata",
           new Document().append("keyId", new ArrayList<>((Arrays.asList(new Document().append("$binary", new Document()
                   .append("base64", dekId)
                   .append("subType", "04")))))))
           .append("properties", new Document()
                   .append("ssn", new Document().append("encrypt", new Document()
                           .append("bsonType", "int")
                           .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic")))
                   .append("bloodType", new Document().append("encrypt", new Document()
                           .append("bsonType", "string")
                           .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random")))
                   .append("medicalRecords", new Document().append("encrypt", new Document()
                           .append("bsonType", "array")
                           .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random")))
                   .append("insurance", new Document()
                           .append("bsonType", "object")
                           .append("properties",
                                   new Document().append("policyNumber", new Document().append("encrypt", new Document()
                                           .append("bsonType", "int")
                                           .append("algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"))))));
   HashMap<String, BsonDocument> schemaMap = new HashMap<String, BsonDocument>();
   schemaMap.put("medicalRecords.patients", BsonDocument.parse(jsonSchema.toJson()));

4. Specify the Location of the Automatic Encryption Shared Library

   Map<String, Object> extraOptions = new HashMap<String, Object>();
   extraOptions.put("cryptSharedLibPath", "<Full path to your Automatic Encryption Shared Library>"));

   Note

   Automatic Encryption Options

   The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.

   To learn more about the Automatic Encryption Shared Library, see the Install and Configure a CSFLE Query Analysis Component page.

5. Create the MongoClient

   Instantiate a MongoDB client object with the following automatic encryption settings that use the variables declared in the previous steps:

   MongoClientSettings clientSettings = MongoClientSettings.builder()
       .applyConnectionString(new ConnectionString(connectionString))
       .autoEncryptionSettings(AutoEncryptionSettings.builder()
           .keyVaultNamespace(keyVaultNamespace)
           .kmsProviders(kmsProviders)
           .schemaMap(schemaMap)
           .extraOptions(extraOptions)
           .build())
       .build();
   
   MongoClient mongoClientSecure = MongoClients.create(clientSettings);

Insert a Document with Encrypted Fields

Use your CSFLE-enabled MongoClient instance to insert a document with encrypted fields into the medicalRecords.patients namespace using the following code snippet:

ArrayList<Document> medicalRecords = new ArrayList<>();
medicalRecords.add(new Document().append("weight", "180"));
medicalRecords.add(new Document().append("bloodPressure", "120/80"));

Document insurance = new Document()
.append("policyNumber", 123142)
.append("provider",  "MaestCare");

Document patient = new Document()
    .append("name", "Jon Doe")
    .append("ssn", 241014209)
    .append("bloodType", "AB+")
    .append("medicalRecords", medicalRecords)
    .append("insurance", insurance);
mongoClientSecure.getDatabase(recordsDb).getCollection(recordsColl).insertOne(patient);

When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:

{
  "_id": { "$oid": "<_id of your document>" },
  "name": "Jon Doe",
  "ssn": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "bloodType": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "medicalRecords": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "insurance": {
    "provider": "MaestCare",
    "policyNumber": {
      "$binary": "<cipher-text>",
      "$type": "6"
    }
  }
}

Retrieve Your Document with Encrypted Fields

Retrieve the document with encrypted fields you inserted in the Insert a Document with Encrypted Fields step of this guide.

To show the functionality of CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.

System.out.println("Finding a document with regular (non-encrypted) client.");
Document docRegular = mongoClientRegular.getDatabase(recordsDb).getCollection(recordsColl).find(eq("name", "Jon Doe")).first();
System.out.println(docRegular.toJson());

System.out.println("Finding a document with encrypted client");
Document docSecure = mongoClientSecure.getDatabase(recordsDb).getCollection(recordsColl).find(eq("name", "Jon Doe")).first();
System.out.println(docSecure.toJson());

The output of the preceding code snippet should look like this:

Finding a document with regular (non-encrypted) client.

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6),
  bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6),
  'key-id': 'demo-data-key',
  medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6),
  insurance: {
    policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6),
    provider: 'MaestCare'
  }
}

Finding a document with encrypted client

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: 241014209,
  bloodType: 'AB+',
  'key-id': 'demo-data-key',
  medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ],
  insurance: { policyNumber: 123142, provider: 'MaestCare' }
}

Create the Customer Master Key

1. Log in to your AWS Management Console.
2. Navigate to the AWS KMS Console.

3. Create your Customer Master Key

   Create a new symmetric key by following the official AWS documentation on Creating symmetric KMS keys. The key you create is your Customer Master Key. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration of your CMK.

   In the Usage Permissions step of the key generation process, apply the following default key policy that enables Identity and Access Management (IAM) policies to grant access to your Customer Master Key:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Enable IAM User Permissions",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<ARN of your AWS account principal>"
         },
         "Action": "kms:*",
         "Resource": "*"
       }
     ]
   }

   Important

   Record the Amazon Resource Name (ARN) and Region of your Customer Master Key. You will use these in later steps of this guide.

   Tip

   Learn More

   To learn more about your Customer Master Keys, see Encryption Keys and Key Vaults.

   To learn more about key policies, see Key Policies in AWS KMS in the official AWS documentation.

Create an AWS IAM User

1. Navigate to the AWS IAM Console.

2. Create an IAM User

   Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. You will use this IAM user as a service account for your CSFLE-enabled application. Your application authenticates with AWS KMS using the IAM user to encrypt and decrypt your Data Encryption Keys (DEKs) with your Customer Master Key (CMK).

   Important

   Record your Credentials

   Ensure you record the following IAM credentials in the final step of creating your IAM user:

   • access key ID
   • secret access key

   You have one opportunity to record these credentials. If you do not record these credentials during this step, you must create another IAM user.

3. Grant Permissions

   Grant your IAM user kms:Encrypt and kms:Decrypt permissions for your remote master key.

   Important

   The new client IAM user should not have administrative permissions for the master key. To keep your data secure, follow the principle of least privilege.

   The following inline policy allows an IAM user to encrypt and decrypt with the Customer Master Key with the least privileges possible:

   Note

   Remote Master Key ARN

   The following policy requires the ARN of the key you generate in the Create the Master Key step of this guide.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["kms:Decrypt", "kms:Encrypt"],
         "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
       }
     ]
   }

   To apply the preceding policy to your IAM user, follow the Adding IAM identity permissions guide in the AWS documentation.

   Important

   Authenticate with IAM Roles in Production

   When deploying your CSFLE-enabled application to a production environment, authenticate your application by using an IAM role instead of an IAM user.

   To learn more about IAM roles, see the following pages in the official AWS documentation:

   • IAM roles
   • When to create an IAM role (instead of a user)

Create a Unique Index on your Key Vault collection

Create a unique index on the keyAltNames field in your encryption.__keyVault namespace.

const uri = "<Your Connection String>";
const keyVaultDatabase = "encryption";
const keyVaultCollection = "__keyVault";
const keyVaultNamespace = `${keyVaultDatabase}.${keyVaultCollection}`;
const keyVaultClient = new MongoClient(uri);
await keyVaultClient.connect();
const keyVaultDB = keyVaultClient.db(keyVaultDatabase);
// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.
await keyVaultDB.dropDatabase();
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
await keyVaultClient.db("medicalRecords").dropDatabase();
const keyVaultColl = keyVaultDB.collection(keyVaultCollection);
await keyVaultColl.createIndex(
  { keyAltNames: 1 },
  {
    unique: true,
    partialFilterExpression: { keyAltNames: { $exists: true } },
  }
);

Create a New Data Encryption Key

1. Add your AWS KMS Credentials

   Add the service account credentials to your CSFLE-enabled client code.

   const provider = "aws";
   const kmsProviderCredentials = {
     aws: {
       accessKeyId: "<Your AWS Access Key ID>",
       secretAccessKey: "<Your AWS Secret Access Key>",
     },
   };

   You can also provide a custom name for your KMS provider by passing in a string that includes the name of the KMS provider, followed by a colon and the custom name. Providing a unique name for a KMS provider allows you to specify multiple KMS providers of the same type.

   For example, you can name your AWS KMS provider "my_aws_provider" in your KMS credentials variable as shown in the following code:

   kmsProviderCredentials = {
     "aws:my_aws_provider": {
       accessKeyId: process.env["AWS_ACCESS_KEY_ID"], // Your AWS access key ID
       secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"], // Your AWS secret access key
     },
   };

2. Add Your Key Information

   Update the following code to specify your Customer Master Key:

   Tip

   You recorded your Customer Master Key's ARN and Region in the Create a Customer Master Key step of this guide.

   const mongodb = require("mongodb");
   const { MongoClient, Binary, ClientEncryption } = mongodb;
   
   // start-kmsproviders
   const provider = "aws";
   const kmsProviderCredentials = {
     aws: {
       accessKeyId: "<Your AWS Access Key ID>",
       secretAccessKey: "<Your AWS Secret Access Key>",
     },
   };
   // end-kmsproviders
   
   // start-datakeyopts
   const masterKey = {
     key: "<Your AWS Key ARN>",
     region: "<Your AWS Key Region>",
   };

3. Generate your Data Encryption Key

   const client = new MongoClient(uri);
   await client.connect();
   
   const encryption = new ClientEncryption(client, {
     keyVaultNamespace,
     kmsProviderCredentials,
   });
   const key = await encryption.createDataKey(provider, {
     masterKey: masterKey,
   });
   console.log("DataKeyId [base64]: ", key.toString("base64"));
   await keyVaultClient.close();
   await client.close();

   Note

   Import ClientEncryption

   When using the Node.js driver v6.0 and later, you must import ClientEncryption from mongodb.

   For earlier driver versions, import ClientEncryption from mongodb-client-encryption.

Configure the MongoClient

To view the complete code for this file, see our Github repository.

1. Specify the Key Vault Collection Namespace

   Specify encryption.__keyVault as the Key Vault collection namespace.

   const keyVaultNamespace = "encryption.__keyVault";

2. Specify your AWS Credentials

   Specify the aws KMS provider and your IAM user credentials:

   const kmsProviders = {
     aws: {
       accessKeyId: "<Your AWS Access Key ID>",
       secretAccessKey: "<Your AWS Secret Access Key>",
     },
   };

   Important

   Reminder: Authenticate with IAM Roles in Production

   To use an IAM role instead of an IAM user to authenticate your application, specify an empty object for your credentials in your KMS provider object. This instructs the driver to automatically retrieve the credentials from the environment:

   kmsProviders = {
     aws: { }
   };

   You cannot automatically retrieve credentials if you are using a named KMS provider.

3. Create an Encryption Schema For Your Collection

   Tip

   Add Your Data Encryption Key Base64 ID

   Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.

   dataKey = "<Your base64 DEK ID>";
   const schema = {
     bsonType: "object",
     encryptMetadata: {
       keyId: [new Binary(Buffer.from(dataKey, "base64"), 4)],
     },
     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",
         },
       },
     },
   };
   
   var patientSchema = {};
   patientSchema[namespace] = schema;

4. Specify the Location of the Automatic Encryption Shared Library

   const extraOptions = {
     cryptSharedLibPath: "<Full path to your Automatic Encryption Shared Library>",
   };

   Note

   Automatic Encryption Options

   The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.

   To learn more about the Automatic Encryption Shared Library, see the Install and Configure a CSFLE Query Analysis Component page.

5. Create the MongoClient

   Instantiate a MongoDB client object with the following automatic encryption settings that use the variables declared in the previous steps:

   const secureClient = new MongoClient(connectionString, {
     autoEncryption: {
       keyVaultNamespace,
       kmsProviders,
       schemaMap: patientSchema,
       extraOptions: extraOptions,
     },
   });

Insert a Document with Encrypted Fields

Use your CSFLE-enabled MongoClient instance to insert a document with encrypted fields into the medicalRecords.patients namespace using the following code snippet:

try {
  const writeResult = await secureClient
    .db(db)
    .collection(coll)
    .insertOne({
      name: "Jon Doe",
      ssn: 241014209,
      bloodType: "AB+",
      medicalRecords: [{ weight: 180, bloodPressure: "120/80" }],
      insurance: {
        policyNumber: 123142,
        provider: "MaestCare",
      },
    });
} catch (writeError) {
  console.error("writeError occurred:", writeError);
}

When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:

{
  "_id": { "$oid": "<_id of your document>" },
  "name": "Jon Doe",
  "ssn": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "bloodType": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "medicalRecords": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "insurance": {
    "provider": "MaestCare",
    "policyNumber": {
      "$binary": "<cipher-text>",
      "$type": "6"
    }
  }
}

Retrieve Your Document with Encrypted Fields

Retrieve the document with encrypted fields you inserted in the Insert a Document with Encrypted Fields step of this guide.

To show the functionality of CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.

console.log("Finding a document with regular (non-encrypted) client.");
console.log(
  await regularClient.db(db).collection(coll).findOne({ name: /Jon/ })
);

console.log("Finding a document with encrypted client");
console.log(
  await secureClient.db(db).collection(coll).findOne({ name: /Jon/ })
);

The output of the preceding code snippet should look like this:

Finding a document with regular (non-encrypted) client.

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6),
  bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6),
  'key-id': 'demo-data-key',
  medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6),
  insurance: {
    policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6),
    provider: 'MaestCare'
  }
}

Finding a document with encrypted client

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: 241014209,
  bloodType: 'AB+',
  'key-id': 'demo-data-key',
  medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ],
  insurance: { policyNumber: 123142, provider: 'MaestCare' }
}

Create the Customer Master Key

1. Log in to your AWS Management Console.
2. Navigate to the AWS KMS Console.

3. Create your Customer Master Key

   Create a new symmetric key by following the official AWS documentation on Creating symmetric KMS keys. The key you create is your Customer Master Key. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration of your CMK.

   In the Usage Permissions step of the key generation process, apply the following default key policy that enables Identity and Access Management (IAM) policies to grant access to your Customer Master Key:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Enable IAM User Permissions",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<ARN of your AWS account principal>"
         },
         "Action": "kms:*",
         "Resource": "*"
       }
     ]
   }

   Important

   Record the Amazon Resource Name (ARN) and Region of your Customer Master Key. You will use these in later steps of this guide.

   Tip

   Learn More

   To learn more about your Customer Master Keys, see Encryption Keys and Key Vaults.

   To learn more about key policies, see Key Policies in AWS KMS in the official AWS documentation.

Create an AWS IAM User

1. Navigate to the AWS IAM Console.

2. Create an IAM User

   Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. You will use this IAM user as a service account for your CSFLE-enabled application. Your application authenticates with AWS KMS using the IAM user to encrypt and decrypt your Data Encryption Keys (DEKs) with your Customer Master Key (CMK).

   Important

   Record your Credentials

   Ensure you record the following IAM credentials in the final step of creating your IAM user:

   • access key ID
   • secret access key

   You have one opportunity to record these credentials. If you do not record these credentials during this step, you must create another IAM user.

3. Grant Permissions

   Grant your IAM user kms:Encrypt and kms:Decrypt permissions for your remote master key.

   Important

   The new client IAM user should not have administrative permissions for the master key. To keep your data secure, follow the principle of least privilege.

   The following inline policy allows an IAM user to encrypt and decrypt with the Customer Master Key with the least privileges possible:

   Note

   Remote Master Key ARN

   The following policy requires the ARN of the key you generate in the Create the Master Key step of this guide.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["kms:Decrypt", "kms:Encrypt"],
         "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
       }
     ]
   }

   To apply the preceding policy to your IAM user, follow the Adding IAM identity permissions guide in the AWS documentation.

   Important

   Authenticate with IAM Roles in Production

   When deploying your CSFLE-enabled application to a production environment, authenticate your application by using an IAM role instead of an IAM user.

   To learn more about IAM roles, see the following pages in the official AWS documentation:

   • IAM roles
   • When to create an IAM role (instead of a user)

Create a Unique Index on your Key Vault collection

Create a unique index on the keyAltNames field in your encryption.__keyVault namespace.

connection_string = "<your connection string here>"

key_vault_coll = "__keyVault"
key_vault_db = "encryption"
key_vault_namespace = f"{key_vault_db}.{key_vault_coll}"
key_vault_client = MongoClient(connection_string)
# Drop the Key Vault Collection in case you created this collection
# in a previous run of this application.
key_vault_client.drop_database(key_vault_db)
# Drop the database storing your encrypted fields as all
# the DEKs encrypting those fields were deleted in the preceding line.
key_vault_client["medicalRecords"].drop_collection("patients")
key_vault_client[key_vault_db][key_vault_coll].create_index(
    [("keyAltNames", ASCENDING)],
    unique=True,
    partialFilterExpression={"keyAltNames": {"$exists": True}},
)

Create a New Data Encryption Key

1. Add your AWS KMS Credentials

   Add the service account credentials to your CSFLE-enabled client code.

   provider = "aws"
   kms_provider_credentials = {
       provider: {
           "accessKeyId": "<IAM User Access Key ID>",
           "secretAccessKey": "<IAM User Secret Access Key>",
       }
   }

   You can also provide a custom name for your KMS provider by passing in a string that includes the name of the KMS provider, followed by a colon and the custom name. Providing a unique name for a KMS provider allows you to specify multiple KMS providers of the same type.

   For example, you can name your AWS KMS provider "my_aws_provider" in your KMS credentials variable as shown in the following code:

   kms_provider_credentials = {
       "aws:my_aws_provider": {
       "accessKeyId": os.environ['AWS_ACCESS_KEY_ID'], # Your AWS access key ID
       "secretAccessKey": os.environ['AWS_SECRET_ACCESS_KEY'] # Your AWS secret access key
       }
   }

2. Add Your Key Information

   Update the following code to specify your Customer Master Key:

   Tip

   You recorded your Customer Master Key's ARN and Region in the Create a Customer Master Key step of this guide.

   master_key = {"region": "<Master Key AWS Region>", "key": "<Master Key ARN>"}

3. Generate your Data Encryption Key

   key_vault_database = "encryption"
   key_vault_collection = "__keyVault"
   key_vault_namespace = f"{key_vault_database}.{key_vault_collection}"
   
   client = MongoClient(connection_string)
   client_encryption = ClientEncryption(
       kms_provider_credentials,  # pass in the kms_provider_credentials variable from the previous step
       key_vault_namespace,
       client,
       CodecOptions(uuid_representation=STANDARD),
   )
   data_key_id = client_encryption.create_data_key(provider, master_key)
   
   base_64_data_key_id = base64.b64encode(data_key_id)
   print("DataKeyId [base64]: ", base_64_data_key_id)

Configure the MongoClient

To view the complete code for this file, see our Github repository.

1. Specify the Key Vault Collection Namespace

   Specify encryption.__keyVault as the Key Vault collection namespace.

   key_vault_namespace = "encryption.__keyVault"

2. Specify your AWS Credentials

   Specify the aws KMS provider and your IAM user credentials:

   provider = "aws"
   kms_providers = {
       "aws": {
           "accessKeyId": "<IAM User Access Key ID>",
           "secretAccessKey": "<IAM User Secret Access Key>",
       }
   }

   Important

   Reminder: Authenticate with IAM Roles in Production

   To use an IAM role instead of an IAM user to authenticate your application, specify an empty object for your credentials in your KMS provider object. This instructs the driver to automatically retrieve the credentials from the environment:

   kms_provider_credentials = {
     "aws": { }
   }

   You cannot automatically retrieve credentials if you are using a named KMS provider.

3. Create an Encryption Schema For Your Collection

   Tip

   Add Your Data Encryption Key Base64 ID

   Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.

   dek_id = b"<paste-base-64-encoded-data-encryption-key-id>"
   json_schema = {
       "bsonType": "object",
       "encryptMetadata": {"keyId": [Binary(base64.b64decode(dek_id), UUID_SUBTYPE)]},
       "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",
               }
           },
       },
   }
   
   patient_schema = {"medicalRecords.patients": json_schema}

4. Specify the Location of the Automatic Encryption Shared Library

   extra_options = {
       "cryptSharedLibPath": "<Full path to your Automatic Encryption Shared Library>"
   }

   Note

   Automatic Encryption Options

   The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.

   To learn more about the Automatic Encryption Shared Library, see the Install and Configure a CSFLE Query Analysis Component page.

5. Create the MongoClient

   Instantiate a MongoDB client object with the following automatic encryption settings that use the variables declared in the previous steps:

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

Insert a Document with Encrypted Fields

Use your CSFLE-enabled MongoClient instance to insert a document with encrypted fields into the medicalRecords.patients namespace using 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)


medical_record = [{"weight": 180, "bloodPressure": "120/80"}]
insert_patient(
    secureClient.medicalRecords.patients,
    "Jon Doe",
    241014209,
    "AB+",
    medical_record,
    123142,
    "MaestCare",
)

When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:

{
  "_id": { "$oid": "<_id of your document>" },
  "name": "Jon Doe",
  "ssn": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "bloodType": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "medicalRecords": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "insurance": {
    "provider": "MaestCare",
    "policyNumber": {
      "$binary": "<cipher-text>",
      "$type": "6"
    }
  }
}

Retrieve Your Document with Encrypted Fields

Retrieve the document with encrypted fields you inserted in the Insert a Document with Encrypted Fields step of this guide.

To show the functionality of CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.

print("Finding a document with regular (non-encrypted) client.")
result = regularClient.medicalRecords.patients.find_one({"name": "Jon Doe"})
pprint.pprint(result)

print("Finding a document with encrypted client")
pprint.pprint(secureClient.medicalRecords.patients.find_one({"name": "Jon Doe"}))

The output of the preceding code snippet should look like this:

Finding a document with regular (non-encrypted) client.

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6),
  bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6),
  'key-id': 'demo-data-key',
  medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6),
  insurance: {
    policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6),
    provider: 'MaestCare'
  }
}

Finding a document with encrypted client

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: 241014209,
  bloodType: 'AB+',
  'key-id': 'demo-data-key',
  medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ],
  insurance: { policyNumber: 123142, provider: 'MaestCare' }
}

Create the Customer Master Key

1. Log in to your AWS Management Console.
2. Navigate to the AWS KMS Console.

3. Create your Customer Master Key

   Create a new symmetric key by following the official AWS documentation on Creating symmetric KMS keys. The key you create is your Customer Master Key. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration of your CMK.

   In the Usage Permissions step of the key generation process, apply the following default key policy that enables Identity and Access Management (IAM) policies to grant access to your Customer Master Key:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Enable IAM User Permissions",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<ARN of your AWS account principal>"
         },
         "Action": "kms:*",
         "Resource": "*"
       }
     ]
   }

   Important

   Record the Amazon Resource Name (ARN) and Region of your Customer Master Key. You will use these in later steps of this guide.

   Tip

   Learn More

   To learn more about your Customer Master Keys, see Encryption Keys and Key Vaults.

   To learn more about key policies, see Key Policies in AWS KMS in the official AWS documentation.

Create an AWS IAM User

1. Navigate to the AWS IAM Console.

2. Create an IAM User

   Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. You will use this IAM user as a service account for your CSFLE-enabled application. Your application authenticates with AWS KMS using the IAM user to encrypt and decrypt your Data Encryption Keys (DEKs) with your Customer Master Key (CMK).

   Important

   Record your Credentials

   Ensure you record the following IAM credentials in the final step of creating your IAM user:

   • access key ID
   • secret access key

   You have one opportunity to record these credentials. If you do not record these credentials during this step, you must create another IAM user.

3. Grant Permissions

   Grant your IAM user kms:Encrypt and kms:Decrypt permissions for your remote master key.

   Important

   The new client IAM user should not have administrative permissions for the master key. To keep your data secure, follow the principle of least privilege.

   The following inline policy allows an IAM user to encrypt and decrypt with the Customer Master Key with the least privileges possible:

   Note

   Remote Master Key ARN

   The following policy requires the ARN of the key you generate in the Create the Master Key step of this guide.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["kms:Decrypt", "kms:Encrypt"],
         "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
       }
     ]
   }

   To apply the preceding policy to your IAM user, follow the Adding IAM identity permissions guide in the AWS documentation.

   Important

   Authenticate with IAM Roles in Production

   When deploying your CSFLE-enabled application to a production environment, authenticate your application by using an IAM role instead of an IAM user.

   To learn more about IAM roles, see the following pages in the official AWS documentation:

   • IAM roles
   • When to create an IAM role (instead of a user)

Create a Unique Index on your Key Vault collection

Create a unique index on the keyAltNames field in your encryption.__keyVault namespace.

var connectionString = "<Your MongoDB URI>";
var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");
var keyVaultClient = new MongoClient(connectionString);
var indexOptions = new CreateIndexOptions<BsonDocument>();
indexOptions.Unique = true;
indexOptions.PartialFilterExpression = new BsonDocument { { "keyAltNames", new BsonDocument { { "$exists", new BsonBoolean(true) } } } };
var builder = Builders<BsonDocument>.IndexKeys;
var indexKeysDocument = builder.Ascending("keyAltNames");
var indexModel = new CreateIndexModel<BsonDocument>(indexKeysDocument, indexOptions);
var keyVaultDatabase = keyVaultClient.GetDatabase(keyVaultNamespace.DatabaseNamespace.ToString());
// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.  
keyVaultDatabase.DropCollection(keyVaultNamespace.CollectionName);
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
keyVaultClient.GetDatabase("medicalRecords").DropCollection("patients");
var keyVaultCollection = keyVaultDatabase.GetCollection<BsonDocument>(keyVaultNamespace.CollectionName.ToString());
keyVaultCollection.Indexes.CreateOne(indexModel);

Create a New Data Encryption Key

1. Add your AWS KMS Credentials

   Add the service account credentials to your CSFLE-enabled client code.

   var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>();
   var provider = "aws";
   var awsKmsOptions = new Dictionary<string, object>
   {
      { "accessKeyId", "<Your AWS Access Key ID>" },
      { "secretAccessKey", "<Your AWS Secret Access Key>" }
   };
   kmsProviderCredentials.Add(provider, awsKmsOptions);

   You can also provide a custom name for your KMS provider by passing in a string that includes the name of the KMS provider, followed by a colon and the custom name. Providing a unique name for a KMS provider allows you to specify multiple KMS providers of the same type.

   For example, you can name your AWS KMS provider "my_aws_provider" in your KMS credentials variable as shown in the following code:

   var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>();
   var kmsOptions = new Dictionary<string, object>
       {
           { "accessKeyId", _appSettings["Aws:AccessKeyId"] }, // Your AWS access key ID
           { "secretAccessKey", _appSettings["Aws:SecretAccessKey"] } // Your AWS secret access key
       };
   kmsProviderCredentials.Add("aws:my_aws_provider", kmsOptions);

2. Add Your Key Information

   Update the following code to specify your Customer Master Key:

   Tip

   You recorded your Customer Master Key's ARN and Region in the Create a Customer Master Key step of this guide.

   var dataKeyOptions = new DataKeyOptions(
      masterKey: new BsonDocument
      {
          { "region", "<Your AWS Key Region>" },
          { "key", "<Your AWS Key ARN>" },
      });

3. Generate your Data Encryption Key

   var clientEncryptionOptions = new ClientEncryptionOptions(
       keyVaultClient: keyVaultClient,
       keyVaultNamespace: keyVaultNamespace,
       kmsProviders: kmsProviderCredentials
       );
   
   var clientEncryption = new ClientEncryption(clientEncryptionOptions);
   var dataKeyId = clientEncryption.CreateDataKey(provider, dataKeyOptions, CancellationToken.None);
   var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));
   Console.WriteLine($"DataKeyId [base64]: {dataKeyIdBase64}");

Configure the MongoClient

To view the complete code for this file, see our Github repository

1. Specify the Key Vault Collection Namespace

   Specify encryption.__keyVault as the Key Vault collection namespace.

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

2. Specify your AWS Credentials

   Specify the aws KMS provider and your IAM user credentials:

   var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
   var provider = "aws";
   var awsKmsOptions = new Dictionary<string, object>
   {
      { "accessKeyId", "<Your AWS Access Key ID>" },
      { "secretAccessKey", "<Your AWS Secret Access Key>" }
   };
   kmsProviders.Add(provider, awsKmsOptions);

   Important

   Reminder: Authenticate with IAM Roles in Production

   To use an IAM role instead of an IAM user to authenticate your application, specify an empty object for your credentials in your KMS provider object. This instructs the driver to automatically retrieve the credentials from the environment:

   kmsProviderCredentials.Add("aws", new Dictionary<string, object>);

   You cannot automatically retrieve credentials if you are using a named KMS provider.

3. Create an Encryption Schema For Your Collection

   Tip

   Add Your Data Encryption Key Base64 ID

   Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.

   var keyId = "<Your base64 DEK ID here>";
   var schema = new BsonDocument
   {
      { "bsonType", "object" },
      {
          "encryptMetadata",
          new BsonDocument("keyId", new BsonArray(new[] { new BsonBinaryData(Convert.FromBase64String(keyId), BsonBinarySubType.UuidStandard) }))
      },
      {
          "properties",
          new BsonDocument
          {
              {
                  "ssn", new BsonDocument
                  {
                      {
                          "encrypt", new BsonDocument
                          {
                              { "bsonType", "int" },
                              { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" }
                          }
                      }
                  }
              },
              {
                  "bloodType", new BsonDocument
                  {
                      {
                          "encrypt", new BsonDocument
                          {
                              { "bsonType", "string" },
                              { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
                          }
                      }
                  }
              },
              {
                  "medicalRecords", new BsonDocument
                  {
                      {
                          "encrypt", new BsonDocument
                          {
                              { "bsonType", "array" },
                              { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" }
                          }
                      }
                  }
              },
              {
                  "insurance", new BsonDocument
                  {
                      { "bsonType", "object" },
                      {
                          "properties", new BsonDocument
                          {
                              {
                                  "policyNumber", new BsonDocument
                                  {
                                      {
                                          "encrypt", new BsonDocument
                                          {
                                              { "bsonType", "int" },
                                              { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" }
                                          }
                                      }
                                  }
                              }
                          }
                      }
                  }
              }
          }
      }
   };
   var schemaMap = new Dictionary<string, BsonDocument>();
   schemaMap.Add(dbNamespace, schema);

4. Specify the Location of the Automatic Encryption Shared Library

   var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";
   var extraOptions = new Dictionary<string, object>()
   {
      { "cryptSharedLibPath", mongoBinariesPath },
   };

   Note

   Automatic Encryption Options

   The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.

   To learn more about the Automatic Encryption Shared Library, see the Install and Configure a CSFLE Query Analysis Component page.

5. Create the MongoClient

   Instantiate a MongoDB client object with the following automatic encryption settings that use the variables declared in the previous steps:

   MongoClientSettings.Extensions.AddAutoEncryption(); // .NET/C# Driver v3.0 or later only
   var clientSettings = MongoClientSettings.FromConnectionString(connectionString);
   var autoEncryptionOptions = new AutoEncryptionOptions(
       keyVaultNamespace: keyVaultNamespace,
       kmsProviders: kmsProviders,
       schemaMap: schemaMap,
       extraOptions: extraOptions
       );
   clientSettings.AutoEncryptionOptions = autoEncryptionOptions;
   var secureClient = new MongoClient(clientSettings);

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

Insert a Document with Encrypted Fields

Use your CSFLE-enabled MongoClient instance to insert a document with encrypted fields into the medicalRecords.patients namespace using the following code snippet:

            var sampleDocFields = new BsonDocument
            {
                { "name", "Jon Doe" },
                { "ssn", 145014000 },
                { "bloodType", "AB-" },
                {
                    "medicalRecords", new BsonArray
                    {
                        new BsonDocument("weight", 180),
                        new BsonDocument("bloodPressure", "120/80")
                    }
                },
                {
                    "insurance", new BsonDocument
                    {
                        { "policyNumber", 123142 },
                        { "provider", "MaestCare" }
                    }
                }
            };

            // Construct an auto-encrypting client
            var secureCollection = secureClient.GetDatabase(db).GetCollection<BsonDocument>(coll);

            // Insert a document into the collection
            secureCollection.InsertOne(sampleDocFields);

When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:

{
  "_id": { "$oid": "<_id of your document>" },
  "name": "Jon Doe",
  "ssn": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "bloodType": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "medicalRecords": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "insurance": {
    "provider": "MaestCare",
    "policyNumber": {
      "$binary": "<cipher-text>",
      "$type": "6"
    }
  }
}

Retrieve Your Document with Encrypted Fields

Retrieve the document with encrypted fields you inserted in the Insert a Document with Encrypted Fields step of this guide.

To show the functionality of CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.

Console.WriteLine("Finding a document with regular (non-encrypted) client.");
var filter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");
var regularResult = regularCollection.Find(filter).Limit(1).ToList()[0];
Console.WriteLine($"\n{regularResult}\n");

Console.WriteLine("Finding a document with encrypted client");
var ssnFilter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");
var secureResult = secureCollection.Find(ssnFilter).Limit(1).First();
Console.WriteLine($"\n{secureResult}\n");

The output of the preceding code snippet should look like this:

Finding a document with regular (non-encrypted) client.

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6),
  bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6),
  'key-id': 'demo-data-key',
  medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6),
  insurance: {
    policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6),
    provider: 'MaestCare'
  }
}

Finding a document with encrypted client

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: 241014209,
  bloodType: 'AB+',
  'key-id': 'demo-data-key',
  medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ],
  insurance: { policyNumber: 123142, provider: 'MaestCare' }
}

Create the Customer Master Key

1. Log in to your AWS Management Console.
2. Navigate to the AWS KMS Console.

3. Create your Customer Master Key

   Create a new symmetric key by following the official AWS documentation on Creating symmetric KMS keys. The key you create is your Customer Master Key. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration of your CMK.

   In the Usage Permissions step of the key generation process, apply the following default key policy that enables Identity and Access Management (IAM) policies to grant access to your Customer Master Key:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "Enable IAM User Permissions",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<ARN of your AWS account principal>"
         },
         "Action": "kms:*",
         "Resource": "*"
       }
     ]
   }

   Important

   Record the Amazon Resource Name (ARN) and Region of your Customer Master Key. You will use these in later steps of this guide.

   Tip

   Learn More

   To learn more about your Customer Master Keys, see Encryption Keys and Key Vaults.

   To learn more about key policies, see Key Policies in AWS KMS in the official AWS documentation.

Create an AWS IAM User

1. Navigate to the AWS IAM Console.

2. Create an IAM User

   Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. You will use this IAM user as a service account for your CSFLE-enabled application. Your application authenticates with AWS KMS using the IAM user to encrypt and decrypt your Data Encryption Keys (DEKs) with your Customer Master Key (CMK).

   Important

   Record your Credentials

   Ensure you record the following IAM credentials in the final step of creating your IAM user:

   • access key ID
   • secret access key

   You have one opportunity to record these credentials. If you do not record these credentials during this step, you must create another IAM user.

3. Grant Permissions

   Grant your IAM user kms:Encrypt and kms:Decrypt permissions for your remote master key.

   Important

   The new client IAM user should not have administrative permissions for the master key. To keep your data secure, follow the principle of least privilege.

   The following inline policy allows an IAM user to encrypt and decrypt with the Customer Master Key with the least privileges possible:

   Note

   Remote Master Key ARN

   The following policy requires the ARN of the key you generate in the Create the Master Key step of this guide.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["kms:Decrypt", "kms:Encrypt"],
         "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
       }
     ]
   }

   To apply the preceding policy to your IAM user, follow the Adding IAM identity permissions guide in the AWS documentation.

   Important

   Authenticate with IAM Roles in Production

   When deploying your CSFLE-enabled application to a production environment, authenticate your application by using an IAM role instead of an IAM user.

   To learn more about IAM roles, see the following pages in the official AWS documentation:

   • IAM roles
   • When to create an IAM role (instead of a user)

Create a Unique Index on your Key Vault collection

Create a unique index on the keyAltNames field in your encryption.__keyVault namespace.

uri := "<Your MongoDB URI>"
keyVaultClient, err := mongo.Connect(options.Client().ApplyURI(uri))
if err != nil {
	return fmt.Errorf("Connect error for regular client: %v", err)
}
defer func() {
	_ = keyVaultClient.Disconnect(context.TODO())
}()

keyVaultColl := "__keyVault"
keyVaultDb := "encryption"
keyVaultNamespace := keyVaultDb + "." + keyVaultColl
keyVaultIndex := mongo.IndexModel{
	Keys: bson.D{{"keyAltNames", 1}},
	Options: options.Index().
		SetUnique(true).
		SetPartialFilterExpression(bson.D{
			{"keyAltNames", bson.D{
				{"$exists", true},
			}},
		}),
}
// Drop the Key Vault Collection in case you created this collection
// in a previous run of this application.
if err = keyVaultClient.Database(keyVaultDb).Collection(keyVaultColl).Drop(context.TODO()); err != nil {
	log.Fatalf("Collection.Drop error: %v", err)
}
// Drop the database storing your encrypted fields as all
// the DEKs encrypting those fields were deleted in the preceding line.
if err = keyVaultClient.Database("medicalRecords").Collection("patients").Drop(context.TODO()); err != nil {
	log.Fatalf("Collection.Drop error: %v", err)
}
_, err = keyVaultClient.Database(keyVaultDb).Collection(keyVaultColl).Indexes().CreateOne(context.TODO(), keyVaultIndex)
if err != nil {
	panic(err)
}

Create a New Data Encryption Key

1. Add your AWS KMS Credentials

   Add the service account credentials to your CSFLE-enabled client code.

   provider := "aws"
   kmsProviders := map[string]map[string]interface{}{
   	provider: {
   		"accessKeyId":     "<Your AWS Access Key ID>",
   		"secretAccessKey": "<Your AWS Secret Access Key>",
   	},
   }

2. Add Your Key Information

   Update the following code to specify your Customer Master Key:

   Tip

   You recorded your Customer Master Key's ARN and Region in the Create a Customer Master Key step of this guide.

   masterKey := map[string]interface{}{
   	"key":    "<Your AWS Key ARN>",
   	"region": "<Your AWS Key Region>",
   }

3. Generate your Data Encryption Key

   clientEncryptionOpts := options.ClientEncryption().SetKeyVaultNamespace(keyVaultNamespace).
   	SetKmsProviders(kmsProviders)
   clientEnc, err := mongo.NewClientEncryption(keyVaultClient, clientEncryptionOpts)
   if err != nil {
   	return fmt.Errorf("NewClientEncryption error %v", err)
   }
   defer func() {
   	_ = clientEnc.Close(context.TODO())
   }()
   dataKeyOpts := options.DataKey().
   	SetMasterKey(masterKey)
   
   dataKeyID, err := clientEnc.CreateDataKey(context.TODO(), provider, dataKeyOpts)
   if err != nil {
   	return fmt.Errorf("create data key error %v", err)
   }
   
   fmt.Printf("DataKeyId [base64]: %s\n", base64.StdEncoding.EncodeToString(dataKeyID.Data))

Configure the MongoClient

To view the complete code for this file, see our Github repository.

1. Specify the Key Vault Collection Namespace

   Specify encryption.__keyVault as the Key Vault collection namespace.

   keyVaultNamespace := "encryption.__keyVault"

2. Specify your AWS Credentials

   Specify the aws KMS provider and your IAM user credentials:

   kmsProviders := map[string]map[string]interface{}{
   	"aws": {
   		"accessKeyId":     "<Your AWS Access Key ID>",
   		"secretAccessKey": "<Your AWS Secret Access Key>",
   	},
   }

   Important

   Reminder: Authenticate with IAM Roles in Production

   To use an IAM role instead of an IAM user to authenticate your application, specify an empty object for your credentials in your KMS provider object. This instructs the driver to automatically retrieve the credentials from the environment:

   kmsProviderCredentials := map[string]map[string]interface{}{
     "aws": { },
   }

   You cannot automatically retrieve credentials if you are using a named KMS provider.

3. Create an Encryption Schema For Your Collection

   Tip

   Add Your Data Encryption Key Base64 ID

   Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.

   dek_id := "<Your Base64 DEK ID>"
   schema_template := `{
   	"bsonType": "object",
   	"encryptMetadata": {
   		"keyId": [
   			{
   				"$binary": {
   					"base64": "%s",
   					"subType": "04"
   				}
   			}
   		]
   	},
   	"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"
   			}
   		}
   	}
   }`
   schema := fmt.Sprintf(schema_template, dek_id)
   var schemaDoc bson.Raw
   if err := bson.UnmarshalExtJSON([]byte(schema), true, &schemaDoc); err != nil {
   	return fmt.Errorf("UnmarshalExtJSON error: %v", err)
   }
   schemaMap := map[string]interface{}{
   	dbName + "." + collName: schemaDoc,
   }

4. Specify the Location of the Automatic Encryption Shared Library

   extraOptions := map[string]interface{}{
   	"cryptSharedLibPath": "<Full path to your Automatic Encryption Shared Library>",
   }

   Note

   Automatic Encryption Options

   The automatic encryption options provide configuration information to the Automatic Encryption Shared Library, which modifies the application's behavior when accessing encrypted fields.

   To learn more about the Automatic Encryption Shared Library, see the Install and Configure a CSFLE Query Analysis Component page.

5. Create the MongoClient

   Instantiate a MongoDB client object with the following automatic encryption settings that use the variables declared in the previous steps:

   	autoEncryptionOpts := options.AutoEncryption().
   		SetKmsProviders(kmsProviders).
   		SetKeyVaultNamespace(keyVaultNamespace).
   		SetSchemaMap(schemaMap).
   		SetExtraOptions(extraOptions)
   	secureClient, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri).SetAutoEncryptionOptions(autoEncryptionOpts))
   	if err != nil {
   		return fmt.Errorf("Connect error for encrypted client: %v", err)
   	}
   	defer func() {
   		_ = secureClient.Disconnect(context.TODO())
   	}()

Insert a Document with Encrypted Fields

Use your CSFLE-enabled MongoClient instance to insert a document with encrypted fields into the medicalRecords.patients namespace using the following code snippet:

	test_patient := map[string]interface{}{
		"name":      "Jon Doe",
		"ssn":       241014209,
		"bloodType": "AB+",
		"medicalRecords": []map[string]interface{}{{
			"weight":        180,
			"bloodPressure": "120/80",
		}},
		"insurance": map[string]interface{}{
			"provider":     "MaestCare",
			"policyNumber": 123142,
		},
	}
	if _, err := secureClient.Database(dbName).Collection(collName).InsertOne(context.TODO(), test_patient); err != nil {
		return fmt.Errorf("InsertOne error: %v", err)
	}

When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:

{
  "_id": { "$oid": "<_id of your document>" },
  "name": "Jon Doe",
  "ssn": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "bloodType": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "medicalRecords": {
    "$binary": "<cipher-text>",
    "$type": "6"
  },
  "insurance": {
    "provider": "MaestCare",
    "policyNumber": {
      "$binary": "<cipher-text>",
      "$type": "6"
    }
  }
}

Retrieve Your Document with Encrypted Fields

Retrieve the document with encrypted fields you inserted in the Insert a Document with Encrypted Fields step of this guide.

To show the functionality of CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.

fmt.Println("Finding a document with regular (non-encrypted) client.")
var resultRegular bson.M
err = regularClient.Database(dbName).Collection(collName).FindOne(context.TODO(), bson.D{{"name", "Jon Doe"}}).Decode(&resultRegular)
if err != nil {
	panic(err)
}
outputRegular, err := json.MarshalIndent(resultRegular, "", "    ")
if err != nil {
	panic(err)
}
fmt.Printf("%s\n", outputRegular)

fmt.Println("Finding a document with encrypted client")
var resultSecure bson.M
err = secureClient.Database(dbName).Collection(collName).FindOne(context.TODO(), bson.D{{"name", "Jon Doe"}}).Decode(&resultSecure)
if err != nil {
	panic(err)
}
outputSecure, err := json.MarshalIndent(resultSecure, "", "    ")
if err != nil {
	panic(err)
}
fmt.Printf("%s\n", outputSecure)

The output of the preceding code snippet should look like this:

Finding a document with regular (non-encrypted) client.

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6),
  bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6),
  'key-id': 'demo-data-key',
  medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6),
  insurance: {
    policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6),
    provider: 'MaestCare'
  }
}

Finding a document with encrypted client

{
  _id: new ObjectId("629a452e0861b3130887103a"),
  name: 'Jon Doe',
  ssn: 241014209,
  bloodType: 'AB+',
  'key-id': 'demo-data-key',
  medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ],
  insurance: { policyNumber: 123142, provider: 'MaestCare' }
}