How to Use MongoDB Client-Side Field Level Encryption (CSFLE) with C#

1
Install-Package MongoDB.Driver -Version 2.12.0-beta1

1
// KmsKeyHelper.cs
2
3
using System;
4
using System.IO;
5
6
namespace EnvoyMedSys
7
{
8
   public class KmsKeyHelper
9
   {
10
      private readonly static string __localMasterKeyPath = "../../../master-key.txt";
11
12
      public void GenerateLocalMasterKey()
13
      {
14
         using (var randomNumberGenerator = System.Security.Cryptography.RandomNumberGenerator.Create())
15
         {
16
            var bytes = new byte[96];
17
            randomNumberGenerator.GetBytes(bytes);
18
            var localMasterKeyBase64 = Convert.ToBase64String(bytes);
19
            Console.WriteLine(localMasterKeyBase64);
20
            File.WriteAllText(__localMasterKeyPath, localMasterKeyBase64);
21
         }
22
      }
23
   }
24
}

1
// Program.cs
2
3
using System;
4
using System.IO;
5
6
namespace EnvoyMedSys
7
{
8
   class Program
9
   {
10
      public static void Main()
11
      {
12
         var kmsKeyHelper = new KmsKeyHelper();
13
14
         // Ensure GenerateLocalMasterKey() only runs once!
15
         if (!File.Exists("../../../master-key.txt"))
16
         {
17
            kmsKeyHelper.GenerateLocalMasterKey();
18
         }
19
20
         Console.ReadKey();
21
      }
22
   }
23
}

1
using System;
2
using System.IO;
3
using MongoDB.Driver;
4
5
namespace EnvoyMedSys
6
{
7
   class Program
8
   {
9
      public static void Main()
10
      {
11
         var connectionString = Environment.GetEnvironmentVariable("MDB_URI");
12
         var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");
13
14
         var kmsKeyHelper = new KmsKeyHelper(
15
            connectionString: connectionString,
16
            keyVaultNamespace: keyVaultNamespace);
17
18
         string kmsKeyIdBase64;
19
20
         // Ensure GenerateLocalMasterKey() only runs once!
21
         if (!File.Exists("../../../master-key.txt"))
22
         {
23
            kmsKeyHelper.GenerateLocalMasterKey();
24
         }
25
26
         kmsKeyIdBase64 = kmsKeyHelper.CreateKeyWithLocalKmsProvider();
27
28
         Console.ReadKey();
29
      }
30
   }
31
}

1
// KmsKeyHelper.cs
2
3
using System.Collections.Generic;
4
using System.Threading;
5
using MongoDB.Bson;
6
using MongoDB.Driver;
7
using MongoDB.Driver.Encryption;

1
// KmsKeyhelper.cs
2
3
private readonly string _mdbConnectionString;
4
private readonly CollectionNamespace _keyVaultNamespace;
5
6
public KmsKeyHelper(
7
   string connectionString,
8
   CollectionNamespace keyVaultNamespace)
9
{
10
   _mdbConnectionString = connectionString;
11
   _keyVaultNamespace = keyVaultNamespace;
12
}

1
// KmsKeyHelper.cs
2
3
public string CreateKeyWithLocalKmsProvider()
4
{
5
   // Read Master Key from file & convert
6
   string localMasterKeyBase64 = File.ReadAllText(__localMasterKeyPath);
7
   var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64);
8
9
   // Set KMS Provider Settings
10
   // Client uses these settings to discover the master key
11
   var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
12
   var localOptions = new Dictionary<string, object>
13
   {
14
         { "key", localMasterKeyBytes }
15
   };
16
   kmsProviders.Add("local", localOptions);
17
18
   // Create Data Encryption Key
19
   var clientEncryption = GetClientEncryption(kmsProviders);
20
   var dataKeyid = clientEncryption.CreateDataKey("local", new DataKeyOptions(), CancellationToken.None);
21
   clientEncryption.Dispose();
22
   Console.WriteLine($"Local DataKeyId [UUID]: {dataKeyid}");
23
24
   var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyid, GuidRepresentation.Standard));
25
   Console.WriteLine($"Local DataKeyId [base64]: {dataKeyIdBase64}");
26
27
   // Optional validation; checks that key was created successfully
28
   ValidateKey(dataKeyid);
29
   return dataKeyIdBase64;
30
}

1
// KmsKeyHelper.cs
2
3
private ClientEncryption GetClientEncryption(
4
   Dictionary<string, IReadOnlyDictionary<string, object>> kmsProviders)
5
{
6
   var keyVaultClient = new MongoClient(_mdbConnectionString);
7
   var clientEncryptionOptions = new ClientEncryptionOptions(
8
         keyVaultClient: keyVaultClient,
9
         keyVaultNamespace: _keyVaultNamespace,
10
         kmsProviders: kmsProviders);
11
12
   return new ClientEncryption(clientEncryptionOptions);
13
}

1
// KmsKeyHelper.cs
2
3
private void ValidateKey(Guid dataKeyId)
4
{
5
   var client = new MongoClient(_mdbConnectionString);
6
   var collection = client
7
         .GetDatabase(_keyVaultNamespace.DatabaseNamespace.DatabaseName)
8
   #pragma warning disable CS0618 // Type or member is obsolete
9
         .GetCollection<BsonDocument>(_keyVaultNamespace.CollectionName, new MongoCollectionSettings { GuidRepresentation = GuidRepresentation.Standard });
10
   #pragma warning restore CS0618 // Type or member is obsolete
11
12
   var query = Builders<BsonDocument>.Filter.Eq("_id", new BsonBinaryData(dataKeyId, GuidRepresentation.Standard));
13
   var keyDocument = collection
14
         .Find(query)
15
         .Single();
16
17
   Console.WriteLine(keyDocument);
18
}

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

1
// JsonSchemaCreator.cs
2
3
using MongoDB.Bson;
4
using System;
5
6
namespace EnvoyMedSys
7
{
8
   public static class JsonSchemaCreator
9
   {
10
      private static readonly string DETERMINISTIC_ENCRYPTION_TYPE = "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic";
11
      private static readonly string RANDOM_ENCRYPTION_TYPE = "AEAD_AES_256_CBC_HMAC_SHA_512-Random";
12
13
      private static BsonDocument CreateEncryptMetadata(string keyIdBase64)
14
      {
15
         var keyId = new BsonBinaryData(Convert.FromBase64String(keyIdBase64), BsonBinarySubType.UuidStandard);
16
         return new BsonDocument("keyId", new BsonArray(new[] { keyId }));
17
      }
18
19
      private static BsonDocument CreateEncryptedField(string bsonType, bool isDeterministic)
20
      {
21
         return new BsonDocument
22
         {
23
            {
24
               "encrypt",
25
               new BsonDocument
26
               {
27
                  { "bsonType", bsonType },
28
                  { "algorithm", isDeterministic ? DETERMINISTIC_ENCRYPTION_TYPE : RANDOM_ENCRYPTION_TYPE}
29
               }
30
            }
31
         };
32
      }
33
34
      public static BsonDocument CreateJsonSchema(string keyId)
35
      {
36
         return new BsonDocument
37
         {
38
            { "bsonType", "object" },
39
            { "encryptMetadata", CreateEncryptMetadata(keyId) },
40
            {
41
               "properties",
42
               new BsonDocument
43
               {
44
                  { "ssn", CreateEncryptedField("int", true) },
45
                  { "bloodType", CreateEncryptedField("string", false) },
46
                  { "medicalRecords", CreateEncryptedField("array", false) },
47
                  {
48
                     "insurance",
49
                     new BsonDocument
50
                     {
51
                        { "bsonType", "object" },
52
                        {
53
                           "properties",
54
                           new BsonDocument
55
                           {
56
                              { "policyNumber", CreateEncryptedField("int", true) }
57
                           }
58
                        }
59
                     }
60
                  }
61
               }
62
            }
63
         };
64
      }
65
   }
66
}

1
"ssn": {
2
   "encrypt": {
3
      "bsonType": "int",
4
      "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
5
   }
6
}

1
// AutoEncryptHelper.cs
2
3
using System;
4
using System.Collections.Generic;
5
using System.IO;
6
using MongoDB.Bson;
7
using MongoDB.Driver;
8
using MongoDB.Driver.Encryption;
9
10
namespace EnvoyMedSys
11
{
12
   public class AutoEncryptHelper
13
   {
14
      private static readonly string __localMasterKeyPath = "../../../master-key.txt";
15
16
      // Most of what follows are sample fields and a sample medical record we'll be using soon.
17
      private static readonly string __sampleNameValue = "Takeshi Kovacs";
18
      private static readonly int __sampleSsnValue = 213238414;
19
20
      private static readonly BsonDocument __sampleDocFields =
21
         new BsonDocument
22
         {
23
            { "name", __sampleNameValue },
24
            { "ssn", __sampleSsnValue },
25
            { "bloodType", "AB-" },
26
            {
27
               "medicalRecords",
28
               new BsonArray(new []
29
               {
30
                  new BsonDocument("weight", 180),
31
                  new BsonDocument("bloodPressure", "120/80")
32
               })
33
            },
34
            {
35
               "insurance",
36
               new BsonDocument
37
               {
38
                  { "policyNumber", 211241 },
39
                  { "provider", "EnvoyHealth" }
40
               }
41
            }
42
         };
43
44
      // Scaffolding of some private variables we'll need.
45
      private readonly string _connectionString;
46
      private readonly CollectionNamespace _keyVaultNamespace;
47
      private readonly CollectionNamespace _medicalRecordsNamespace;
48
49
      // Constructor that will allow us to specify our auto-encrypting
50
      // client settings. This also makes it a bit easier to extend and
51
      // use with a remote KMS provider later on.
52
      public AutoEncryptHelper(string connectionString, CollectionNamespace keyVaultNamespace)
53
      {
54
         _connectionString = connectionString;
55
         _keyVaultNamespace = keyVaultNamespace;
56
         _medicalRecordsNamespace = CollectionNamespace.FromFullName("medicalRecords.patients");
57
      }
58
59
      // The star of the show. Accepts a key location,
60
      // a key vault namespace, and a schema; all needed
61
      // to construct our CSFLE-enabled MongoClient.
62
      private IMongoClient CreateAutoEncryptingClient(
63
         KmsKeyLocation kmsKeyLocation,
64
         CollectionNamespace keyVaultNamespace,
65
         BsonDocument schema)
66
      {
67
         var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
68
69
         // Specify the local master encryption key
70
         if (kmsKeyLocation == KmsKeyLocation.Local)
71
         {
72
            var localMasterKeyBase64 = File.ReadAllText(__localMasterKeyPath);
73
            var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64);
74
            var localOptions = new Dictionary<string, object>
75
               {
76
                  { "key", localMasterKeyBytes }
77
               };
78
            kmsProviders.Add("local", localOptions);
79
         }
80
81
         // Because we didn't explicitly specify the collection our
82
         // JSON schema applies to, we assign it here. This will map it
83
         // to a database called medicalRecords and a collection called
84
         // patients.
85
         var schemaMap = new Dictionary<string, BsonDocument>();
86
         schemaMap.Add(_medicalRecordsNamespace.ToString(), schema);
87
88
         // Specify location of mongocryptd binary, if necessary.
89
         // Not required if path to the mongocryptd.exe executable
90
         // has been added to your PATH variables
91
         var extraOptions = new Dictionary<string, object>()
92
         {
93
            // Optionally uncomment the following line if you are running mongocryptd manually
94
            // { "mongocryptdBypassSpawn", true }
95
         };
96
97
         // Create CSFLE-enabled MongoClient
98
         // The addition of the automatic encryption settings are what 
99
         // transform this from a standard MongoClient to a CSFLE-enabled
100
         // one
101
         var clientSettings = MongoClientSettings.FromConnectionString(_connectionString);
102
         var autoEncryptionOptions = new AutoEncryptionOptions(
103
            keyVaultNamespace: keyVaultNamespace,
104
            kmsProviders: kmsProviders,
105
            schemaMap: schemaMap,
106
            extraOptions: extraOptions);
107
         clientSettings.AutoEncryptionOptions = autoEncryptionOptions;
108
         return new MongoClient(clientSettings);
109
      }
110
   }
111
}

1
// AutoEncryptHelper.cs
2
3
public async void EncryptedWriteAndReadAsync(string keyIdBase64, KmsKeyLocation kmsKeyLocation)
4
{
5
   // Construct a JSON Schema
6
   var schema = JsonSchemaCreator.CreateJsonSchema(keyIdBase64);
7
8
   // Construct an auto-encrypting client
9
   var autoEncryptingClient = CreateAutoEncryptingClient(
10
      kmsKeyLocation,
11
      _keyVaultNamespace,
12
      schema);
13
14
   var collection = autoEncryptingClient
15
      .GetDatabase(_medicalRecordsNamespace.DatabaseNamespace.DatabaseName)
16
      .GetCollection<BsonDocument>(_medicalRecordsNamespace.CollectionName);
17
18
   var ssnQuery = Builders<BsonDocument>.Filter.Eq("ssn", __sampleSsnValue);
19
20
   // Upsert (update document if found, otherwise create it) a document into the collection
21
   var medicalRecordUpdateResult = await collection
22
      .UpdateOneAsync(ssnQuery, new BsonDocument("$set", __sampleDocFields), new UpdateOptions() { IsUpsert = true });
23
24
   if (!medicalRecordUpdateResult.UpsertedId.IsBsonNull) 
25
   {
26
      Console.WriteLine("Successfully upserted the sample document!");
27
   }
28
29
   // Query by SSN field with auto-encrypting client
30
   var result = collection.Find(ssnQuery).Single();
31
32
   Console.WriteLine($"Encrypted client query by the SSN (deterministically-encrypted) field:\n {result}\n");
33
}

1
// Program.cs
2
3
using System;
4
using System.IO;
5
using MongoDB.Driver;
6
7
namespace EnvoyMedSys
8
{
9
   public enum KmsKeyLocation
10
   {
11
      Local,
12
   }
13
14
   class Program
15
   {
16
      public static void Main()
17
      {
18
         var connectionString = "PASTE YOUR MONGODB CONNECTION STRING/ATLAS URI HERE";
19
         var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");
20
21
         var kmsKeyHelper = new KmsKeyHelper(
22
            connectionString: connectionString,
23
            keyVaultNamespace: keyVaultNamespace);
24
         var autoEncryptHelper = new AutoEncryptHelper(
25
            connectionString: connectionString,
26
            keyVaultNamespace: keyVaultNamespace);
27
28
         string kmsKeyIdBase64;
29
30
         // Ensure GenerateLocalMasterKey() only runs once!
31
         if (!File.Exists("../../../master-key.txt"))
32
         {
33
            kmsKeyHelper.GenerateLocalMasterKey();
34
         }
35
36
         kmsKeyIdBase64 = kmsKeyHelper.CreateKeyWithLocalKmsProvider();
37
         autoEncryptHelper.EncryptedWriteAndReadAsync(kmsKeyIdBase64, KmsKeyLocation.Local);
38
39
         Console.ReadKey();
40
      }
41
   }
42
}

1
// AutoEncryptHelper.cs
2
3
public void QueryWithNonEncryptedClient()
4
{
5
   var nonAutoEncryptingClient = new MongoClient(_connectionString);
6
   var collection = nonAutoEncryptingClient
7
      .GetDatabase(_medicalRecordsNamespace.DatabaseNamespace.DatabaseName)
8
      .GetCollection<BsonDocument>(_medicalRecordsNamespace.CollectionName);
9
   var ssnQuery = Builders<BsonDocument>.Filter.Eq("ssn", __sampleSsnValue);
10
11
   var result = collection.Find(ssnQuery).FirstOrDefault();
12
   if (result != null)
13
   {
14
         throw new Exception("Expected no document to be found but one was found.");
15
   }
16
17
   // Query by name field with a normal non-auto-encrypting client
18
   var nameQuery = Builders<BsonDocument>.Filter.Eq("name", __sampleNameValue);
19
   result = collection.Find(nameQuery).FirstOrDefault();
20
   if (result == null)
21
   {
22
         throw new Exception("Expected the document to be found but none was found.");
23
   }
24
25
   Console.WriteLine($"Query by name (non-encrypted field) using non-auto-encrypting client returned:\n {result}\n");
26
}

1
// Program.cs
2
3
// Comparison query on non-encrypting client
4
autoEncryptHelper.QueryWithNonEncryptedClient();