Skip to content

Commit 36ab5e1

Browse files
rozzajyemin
rozza
authored and
jyemin
committed
Docs: Added initial FLE documentation
JAVA-3317
1 parent 5108446 commit 36ab5e1

File tree

4 files changed

+171
-6
lines changed

4 files changed

+171
-6
lines changed

‎docs/reference/content/driver/reference/monitoring.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title = "Monitoring"
44
[menu.main]
55
parent = "Sync Reference"
66
identifier = "Sync Monitoring"
7-
weight = 100
7+
weight = 20
88
pre = "<i class='fa'></i>"
99
+++
1010

@@ -258,4 +258,4 @@ MongoClient client = MongoClients.create(settings);
258258
```
259259

260260
A `MongoClient` configured with these options will print a message to `System.out` for each connection pool-related event for each MongoDB
261-
server to which the MongoClient is connected.
261+
server to which the MongoClient is connected.

‎docs/reference/content/driver/tutorials/client-side-encryption.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
+++
2+
date = "2019-06-13T09:00:01+01:00"
3+
title = "Client Site Encryption"
4+
[menu.main]
5+
parent = "Sync Tutorials"
6+
identifier = "Sync Client Side Encryption"
7+
weight = 16
8+
pre = "<i class='fa fa-lock'></i>"
9+
+++
10+
11+
# Client Site Encryption
12+
13+
New in MongoDB 4.2 client side encryption allows administrators and developers to encrypt specific data fields in addition to other
14+
MongoDB encryption features.
15+
16+
With field level encryption, developers can encrypt fields client side without any server-side
17+
configuration or directives. Client-side field level encryption supports workloads where applications must guarantee that
18+
unauthorized parties, including server administrators, cannot read the encrypted data.
19+
20+
## Installation
21+
22+
The recommended way to get started using field level encryption in your project is with a dependency management system.
23+
Field level encryption requires additional packages to be installed as well as the driver itself.
24+
See the [installation]({{< relref "driver/getting-started/installation.md" >}}) for instructions on how to install the MongoDB driver.
25+
26+
{{< distroPicker >}}
27+
28+
### libmongocrypt
29+
30+
There is a separate jar file containing`libmongocrypt` bindings.
31+
32+
{{< install artifactId="mongodb-mongocrypt" version="1.0.0-beta1">}}
33+
34+
If the jar fails to run there are separate jar files for specific architectures:
35+
36+
#### RHEL 7.0*
37+
{{< install artifactId="mongodb-crypt" version="1.0.0-beta1" classifier="linux64-rhel70">}}
38+
39+
#### OSX*
40+
{{< install artifactId="mongodb-crypt" version="1.0.0-beta1" classifier="osx">}}
41+
42+
#### Windows*
43+
{{< install artifactId="mongodb-crypt" version="1.0.0-beta1" classifier="win64">}}
44+
45+
#### Ubuntu 16.04
46+
{{< install artifactId="mongodb-crypt" version="1.0.0-beta1" classifier="linux64-ubuntu1604">}}
47+
48+
49+
* Distribution is included in the main `mongodb-crypt` jar file.
50+
51+
### mongocryptd configuration
52+
53+
`libmongocrypt` requires the `mongocryptd` daemon / process to be running. A specific daemon / process uri can be configured in the
54+
`AutoEncryptionSettings` class by setting `mongocryptdURI` in the `extraOptions`.
55+
56+
More information about libmongocrypt will soon be available from the official documentation.
57+
58+
59+
### Examples
60+
61+
The following is a sample app that assumes key and schema have already been created in MongoDB. The example uses a local key,
62+
however using AWS Key Management Service is also an option. The data in the `encryptedField` field is automatically encrypted on the
63+
insert and decrypted when using find on the client side:
64+
65+
```java
66+
import com.mongodb.AutoEncryptionSettings;
67+
import com.mongodb.MongoClientSettings;
68+
import com.mongodb.client.MongoClients;
69+
import org.bson.Document;
70+
71+
import java.security.SecureRandom;
72+
import java.util.Map;
73+
74+
public class ClientSideEncryptionSimpleTest {
75+
76+
public static void main(String[] args) {
77+
78+
// This would have to be the same master key as was used to create the encryption key
79+
var localMasterKey = new byte[96];
80+
new SecureRandom().nextBytes(localMasterKey);
81+
82+
var kmsProviders = Map.of("local", Map.<String, Object>of("key", localMasterKey));
83+
var keyVaultNamespace = "admin.datakeys";
84+
85+
var autoEncryptionSettings = AutoEncryptionSettings.builder()
86+
.keyVaultNamespace(keyVaultNamespace)
87+
.kmsProviders(kmsProviders)
88+
.build();
89+
90+
var clientSettings = MongoClientSettings.builder()
91+
.autoEncryptionSettings(autoEncryptionSettings)
92+
.build();
93+
94+
var client = MongoClients.create(clientSettings);
95+
var collection = client.getDatabase("test").getCollection("coll");
96+
collection.drop(); // Clear old data
97+
98+
collection.insertOne(new Document("encryptedField", "123456789"));
99+
100+
System.out.println(collection.find().first().toJson());
101+
}
102+
}
103+
```
104+
105+
{{% note %}}
106+
Auto encryption is an **enterprise** only feature.
107+
{{% /note %}}
108+
109+
The following example shows how to configure the `AutoEncryptionSettings` instance to create a new key and setting the json schema map:
110+
111+
```java
112+
import com.mongodb.ConnectionString;
113+
import com.mongodb.ClientEncryptionSettings;
114+
import com.mongodb.client.vault.ClientEncryptions;
115+
116+
...
117+
118+
119+
var keyVaultNamespace = "admin.datakeys";
120+
var clientEncryptionSettings = ClientEncryptionSettings.builder()
121+
.keyVaultMongoClientSettings(MongoClientSettings.builder()
122+
.applyConnectionString(new ConnectionString("mongodb://localhost"))
123+
.build())
124+
.keyVaultNamespace(keyVaultNamespace)
125+
.kmsProviders(kmsProviders)
126+
.build();
127+
128+
var clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
129+
var dataKeyId = keyVault.createDataKey("local", new DataKeyOptions());
130+
var base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());
131+
132+
var dbName = "test";
133+
var collName = "coll";
134+
var autoEncryptionSettings = AutoEncryptionSettings.builder()
135+
.keyVaultNamespace(keyVaultNamespace)
136+
.kmsProviders(kmsProviders)
137+
.namespaceToLocalSchemaDocumentMap(Map.of(dbName + "." + collName,
138+
// Need a schema that references the new data key
139+
BsonDocument.parse("{" +
140+
" properties: {" +
141+
" encryptedField: {" +
142+
" encrypt: {" +
143+
" keyId: [{" +
144+
" \"$binary\": {" +
145+
" \"base64\": \"" + base64DataKeyId + "\"," +
146+
" \"subType\": \"04\"" +
147+
" }" +
148+
" }]," +
149+
" bsonType: \"string\"," +
150+
" algorithm: \"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic\"" +
151+
" }" +
152+
" }" +
153+
" }," +
154+
" \"bsonType\": \"object\"" +
155+
"}"))
156+
).build();
157+
```
158+
159+
{{% note %}}
160+
Auto encryption is an **enterprise** only feature.
161+
{{% /note %}}
162+
163+
**Coming soon:** An example using the community version and demonstrating explicit encryption/decryption.

‎docs/reference/layouts/shortcodes/apiref.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{{ .Page.Site.BaseURL}}{{ .Page.Site.Data.mongodb.apiUrl }}?{{ with (.Get 0) }}{{ . }}{{ if ne (in . ".html") true}}.html{{ end }}{{ end }}
1+
{{ .Page.Site.BaseURL}}{{ .Page.Site.Data.mongodb.apiUrl }}{{ with (.Get 0) }}{{ . }}{{ if ne (in . ".html") true}}.html{{ end }}{{ end }}

‎docs/reference/layouts/shortcodes/install.html

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{{- $artifactId := .Get "artifactId"}}
22
{{- $version := .Get "version" -}}
3+
{{- $classifier := .Get "classifier" -}}
34
{{- $dependencies := .Get "dependencies" -}}
45
{{- $snapshot := in $version "SNAPSHOT" -}}
56

@@ -29,7 +30,7 @@
2930
<section class="gradle hidden">
3031
<pre><code>
3132
dependencies {
32-
compile 'org.mongodb:{{$artifactId}}:{{$version}}'
33+
compile 'org.mongodb:{{$artifactId}}:{{$version}}{{- if $classifier -}}:{{$classifier}}{{- end -}}'
3334
}
3435
repositories {
3536
maven {
@@ -59,7 +60,8 @@
5960
&lt;dependency&gt;
6061
&lt;groupId&gt;org.mongodb&lt;/groupId&gt;
6162
&lt;artifactId&gt;{{$artifactId}}&lt;/artifactId&gt;
62-
&lt;version&gt;{{$version}}&lt;/version&gt;
63+
&lt;version&gt;{{$version}}&lt;/version&gt;{{- if $classifier -}}
64+
<classifier>{{$classifier}}</classifier>{{- end -}}
6365
&lt;/dependency&gt;
6466
&lt;/dependencies&gt;
6567

@@ -68,7 +70,7 @@
6870
<section class="gradle hidden">
6971
<pre><code>
7072
dependencies {
71-
compile 'org.mongodb:{{$artifactId}}:{{$version}}'
73+
compile 'org.mongodb:{{$artifactId}}:{{$version}}{{- if $classifier -}}:{{$classifier}}{{- end -}}'
7274
}
7375

7476
</code></pre>

0 commit comments

Comments
 (0)