Use Automatic Client-Side Field Level Encryption with KMIP

Configure your KMIP-compliant key provider

To connect a MongoDB driver client to your KMIP-compliant key provider, you must configure your KMIP-compliant key provider such that it accepts your client's TLS certificate.

Consult the documentation for your KMIP-compliant key provider for information on how to accept your client certificate.

Specify your Certificates

Your client must connect to your KMIP-compliant key provider through TLS and present a client certificate that your KMIP-compliant key provider accepts:

var tlsOptions = new Dictionary<string, SslSettings>();var sslSettings = new SslSettings();var clientCertificate = new X509Certificate2("<path to your pkcs12 client certificate file>");sslSettings.ClientCertificates = new List<X509Certificate>() {    clientCertificate, };tlsOptions.Add(provider, sslSettings);

openssl pkcs12 -export -out "<new pkcs12 certificate>" -in "<certificate to convert>" \-name "<new certificate name>" -password "<new certificate password>"

tlsConfig := make(map[string]*tls.Config)tlsOpts := map[string]interface{}{	"tlsCertificateKeyFile": "<path to your client certificate file>",	"tlsCAFile":             "<path to file containing your Certificate Authority certificate>",}kmipConfig, err := options.BuildTLSConfig(tlsOpts)tlsConfig["kmip"] = kmipConfig

-Djavax.net.ssl.keyStoreType=pkcs12-Djavax.net.ssl.keyStore=<path to pkcs12 KeyStore containing your client certificate>-Djavax.net.ssl.keyStorePassword=<KeyStore password>

const tlsOptions = {  kmip: {    tlsCAFile:      "<path to file containing your Certificate Authority certificate>",    tlsCertificateKeyFile: "<path to your client certificate file>",  },};

tls_options = {    "kmip": {        "tlsCAFile": "<path to file containing your Certificate Authority certificate>",        "tlsCertificateKeyFile": "<path to your client certificate file>",    }}

Create a Unique Index on Your Key Vault Collection

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

Select the tab corresponding to your preferred MongoDB driver:

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);

uri := "<Your MongoDB URI>"keyVaultClient, err := mongo.Connect(context.TODO(), 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 + "." + keyVaultCollkeyVaultIndex := 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)}

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();

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 } },  });

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 Data Encryption Key

1. Add your Endpoint

   Specify the URI endpoint of your KMIP-compliant key provider:

    C#GoJava (Sync)Node.jsPython

   var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "kmip";var kmipKmsOptions = new Dictionary<string, object>{   { "endpoint", "<endpoint for your KMIP-compliant key provider>" },};kmsProviders.Add(provider, kmipKmsOptions);

2. Add Your Key Information

   The following code prompts your KMIP-compliant key provider to automatically generate a Customer Master Key:

    C#GoJava (Sync)Node.jsPython

   var dataKeyOptions = new DataKeyOptions(    masterKey: new BsonDocument { } // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key);

3. Generate your Data Encryption Key

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

    C#GoJava (Sync)Node.jsPython

   var clientEncryptionOptions = new ClientEncryptionOptions(    keyVaultClient: keyVaultClient,    keyVaultNamespace: keyVaultNamespace,    kmsProviders: kmsProviders,    tlsOptions: tlsOptions    );
   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

1. Specify the Key Vault Collection Namespace

   Specify encryption.__keyVault as the Key Vault collection namespace.

    C#GoJava (Sync)Node.jsPython

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

2. Specify your KMIP Endpoint

   Specify kmip in your kmsProviders object and enter the URI endpoint of your KMIP-compliant key provider:

    C#GoJava (Sync)Node.jsPython

   var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "kmip";var kmipKmsOptions = new Dictionary<string, object>{   { "endpoint", "<endpoint for your KMIP-compliant key provider>" },};kmsProviders.Add(provider, kmipKmsOptions);

3. Create an Encryption Schema For Your Collection

   Create an encryption schema that specifies how your client application encrypts your documents' fields:

   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.

    C#GoJava (Sync)Node.jsPython

   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);

   Tip

   Further Reading on Schemas

   To view an in-depth description of how to construct the schema you use in this step, see the Encryption Schemas guide.

   To view a list of all supported encryption rules for your encryption schemas, see the CSFLE Encryption Schemas guide.

4. Specify the Location of the Automatic Encryption Shared Library

    C#GoJava (Sync)Node.jsPython

   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:

   .NET/C# Driver v3.0+.NET/C# Driver < v3.0

    C#GoJava (Sync)Node.jsPython

   MongoClientSettings.Extensions.AddAutoEncryption(); // .NET/C# Driver v3.0 or later onlyvar clientSettings = MongoClientSettings.FromConnectionString(connectionString);var autoEncryptionOptions = new AutoEncryptionOptions(    keyVaultNamespace: keyVaultNamespace,    kmsProviders: kmsProviders,    schemaMap: schemaMap,    extraOptions: extraOptions,    tlsOptions: tlsOptions    );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 clientvar secureCollection = secureClient.GetDatabase(db).GetCollection<BsonDocument>(coll);
// Insert a document into the collectionsecureCollection.InsertOne(sampleDocFields);

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

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);

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

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.

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");