Skip to content

Commit 7df218e

Browse files
vincentkamvincentkam
committed
CSHARP-2737: Add FLE documentation
1 parent 8aaab9e commit 7df218e

File tree

2 files changed

+196
-1
lines changed

2 files changed

+196
-1
lines changed

‎Docs/reference/content/reference/driver/crud/client_side_encryption.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
2+
+++
3+
date = "2019-09-30T20:38:-04:00"
4+
title = "Client-Side Field Level Encryption"
5+
[menu.main]
6+
parent = "Reference Reading and Writing"
7+
identifier = "Client-Side Field Level Encryption"
8+
weight = 40
9+
pre = "<i class='fa fa-lock'></i>"
10+
+++
11+
12+
# Client-Side Field Level Encryption
13+
14+
New in MongoDB 4.2, client-side field level encryption allows administrators and
15+
developers to encrypt specific data fields in addition to other MongoDB
16+
encryption features.
17+
18+
With client-side field level encryption, developers can encrypt fields
19+
client-side without any server-side configuration or directives. Client-side
20+
field level encryption supports workloads where applications must guarantee that
21+
unauthorized parties, including server administrators, cannot read the encrypted
22+
data.
23+
24+
{{% note class="important" %}}
25+
Support for client-side field level encryption is in beta, and the beta only
26+
supports Windows. Backwards-breaking changes may be made before the
27+
final release (which will support MacOS and Linux).
28+
{{% /note %}}
29+
30+
## mongocryptd configuration
31+
32+
Client-side field level encryption requires the `mongocryptd` daemon / process
33+
to be running. If `mongocryptd` isn't running, the driver will atempt to spawn
34+
an instance, utilizing the `PATH` environment variable. Alternatively, the path
35+
to `mongocryptd` can be specified by setting `mongocryptdSpawnPath` in
36+
`extraOptions`. A specific daemon / process URI can also be configured in the
37+
`AutoEncryptionSettings` class by setting `mongocryptdURI` in `extraOptions`.
38+
39+
More information about `mongocryptd` will soon be available from the official
40+
documentation.
41+
42+
43+
## Examples
44+
45+
The following is a sample app that assumes the **key** and **schema** have
46+
already been created in MongoDB. The example uses a local key, however using AWS
47+
Key Management Service is also an option. The data in the `encryptedField` field
48+
is automatically encrypted on the insert and decrypted when using find on the
49+
client-side. The following example has been adapted from
50+
[`ClientSideEncryptionExamples.cs`](https://github.com/mongodb/mongo-csharp-driver/blob/master/tests/MongoDB.Driver.Examples/ClientEncryptionExamples.cs), which can be found on GitHub along with the driver source.
51+
52+
```csharp
53+
using MongoDB.Driver.Core.Misc;
54+
using MongoDB.Driver.Core.TestHelpers.XunitExtensions;
55+
using System;
56+
using System.Collections.Generic;
57+
using System.Threading;
58+
using MongoDB.Bson;
59+
using MongoDB.Driver.Encryption;
60+
using Xunit;
61+
using Xunit.Abstractions;
62+
63+
namespace MongoDB.Driver.Examples
64+
{
65+
public class ClientEncryptionExamples
66+
{
67+
private const string LocalMasterKey = "Mng0NCt4ZHVUYUJCa1kxNkVyNUR1QURhZ2h2UzR2d2RrZzh0cFBwM3R6NmdWMDFBMUN3YkQ5aXRRMkhGRGdQV09wOGVNYUMxT2k3NjZKelhaQmRCZGJkTXVyZG9uSjFk";
68+
69+
public void ClientSideEncryptionSimpleTour()
70+
{
71+
var localMasterKey = Convert.FromBase64String(LocalMasterKey);
72+
73+
var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
74+
var localKey = new Dictionary<string, object>
75+
{
76+
{ "key", localMasterKey }
77+
};
78+
kmsProviders.Add("local", localKey);
79+
80+
var keyVaultNamespace = CollectionNamespace.FromFullName("admin.datakeys");
81+
var autoEncryptionOptions = new AutoEncryptionOptions(keyVaultNamespace, kmsProviders);
82+
83+
var mongoClientSettings = new MongoClientSettings
84+
{
85+
AutoEncryptionOptions = autoEncryptionOptions
86+
};
87+
var client = new MongoClient(mongoClientSettings);
88+
var database = client.GetDatabase("test");
89+
database.DropCollection("coll");
90+
var collection = database.GetCollection<BsonDocument>("coll");
91+
92+
collection.InsertOne(new BsonDocument("encryptedField", "123456789"));
93+
94+
var result = collection.Find(FilterDefinition<BsonDocument>.Empty).First();
95+
Console.WriteLine(result.ToJson());
96+
}
97+
}
98+
}
99+
```
100+
101+
{{% note %}}
102+
Auto encryption is an **enterprise** only feature.
103+
{{% /note %}}
104+
105+
The following example shows how to configure the `AutoEncryptionSettings`
106+
instance to create a new key and how to set the json schema map. The following
107+
example has been adapted from
108+
[`ClientSideEncryptionExamples.cs`](https://github.com/mongodb/mongo-csharp-driver/blob/master/tests/MongoDB.Driver.Examples/ClientEncryptionExamples.cs),
109+
which can be found on Github along with the driver source.
110+
111+
```csharp
112+
using MongoDB.Driver.Core.Misc;
113+
using MongoDB.Driver.Core.TestHelpers.XunitExtensions;
114+
using System;
115+
using System.Collections.Generic;
116+
using System.Threading;
117+
using MongoDB.Bson;
118+
using MongoDB.Driver.Encryption;
119+
using Xunit;
120+
using Xunit.Abstractions;
121+
122+
namespace MongoDB.Driver.Examples
123+
{
124+
public class ClientEncryptionExamples
125+
{
126+
private const string LocalMasterKey = "Mng0NCt4ZHVUYUJCa1kxNkVyNUR1QURhZ2h2UzR2d2RrZzh0cFBwM3R6NmdWMDFBMUN3YkQ5aXRRMkhGRGdQV09wOGVNYUMxT2k3NjZKelhaQmRCZGJkTXVyZG9uSjFk";
127+
128+
public void ClientSideEncryptionAutoEncryptionSettingsTour()
129+
{
130+
var localMasterKey = Convert.FromBase64String(LocalMasterKey);
131+
132+
var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
133+
var localKey = new Dictionary<string, object>
134+
{
135+
{ "key", localMasterKey }
136+
};
137+
kmsProviders.Add("local", localKey);
138+
139+
var keyVaultNamespace = CollectionNamespace.FromFullName("admin.datakeys");
140+
var keyVaultMongoClient = new MongoClient();
141+
var clientEncryptionSettings = new ClientEncryptionOptions(
142+
keyVaultMongoClient,
143+
keyVaultNamespace,
144+
kmsProviders);
145+
146+
var clientEncryption = new ClientEncryption(clientEncryptionSettings);
147+
var dataKeyId = clientEncryption.CreateDataKey("local", new DataKeyOptions(), CancellationToken.None);
148+
var base64DataKeyId = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));
149+
clientEncryption.Dispose();
150+
151+
var collectionNamespace = CollectionNamespace.FromFullName("test.coll");
152+
153+
var schemaMap = $@"{{
154+
properties: {{
155+
encryptedField: {{
156+
encrypt: {{
157+
keyId: [{{
158+
'$binary' : {{
159+
'base64' : '{base64DataKeyId}',
160+
'subType' : '04'
161+
}}
162+
}}],
163+
bsonType: 'string',
164+
algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic'
165+
}}
166+
}}
167+
}},
168+
'bsonType': 'object'
169+
}}";
170+
var autoEncryptionSettings = new AutoEncryptionOptions(
171+
keyVaultNamespace,
172+
kmsProviders,
173+
schemaMap: new Dictionary<string, BsonDocument>()
174+
{
175+
{ collectionNamespace.ToString(), BsonDocument.Parse(schemaMap) }
176+
});
177+
var clientSettings = new MongoClientSettings
178+
{
179+
AutoEncryptionOptions = autoEncryptionSettings
180+
};
181+
var client = new MongoClient(clientSettings);
182+
var database = client.GetDatabase("test");
183+
database.DropCollection("coll");
184+
var collection = database.GetCollection<BsonDocument>("coll");
185+
186+
collection.InsertOne(new BsonDocument("encryptedField", "123456789"));
187+
188+
var result = collection.Find(FilterDefinition<BsonDocument>.Empty).First();
189+
Console.WriteLine(result.ToJson());
190+
}
191+
}
192+
}
193+
```
194+
195+
**Coming soon:** An example using the community version and demonstrating explicit encryption/decryption.

‎Release Notes/Release Notes v2.10.0-beta1.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This is a beta release for the 2.10.0 version of the driver.
44

55
The main new features in 2.10.0-beta1 are:
66

7-
* Support Client-side Field Level Encryption
7+
* Support for Client-Side Field Level Encryption (Windows-only)
88

99
An online version of these release notes is available at:
1010

0 commit comments

Comments
 (0)