@@ -18,20 +18,20 @@ Level Encryption (CSFLE)** in the MongoDB Node.js driver.
18
18
19
19
CSFLE allows you to encrypt specific data fields within a document with
20
20
your MongoDB client application before sending the data to the server.
21
- Starting in MongoDB 4.2 Enterprise, you can perform this client-side
21
+ Starting in MongoDB 4.2 Enterprise, you can perform this client-side
22
22
encryption automatically.
23
23
24
- With CSFLE, your client application encrypts fields client-side without
25
- requiring any server-side configuration or directives. CSFLE is useful
26
- for situations in which applications must guarantee that unauthorized
27
- parties, including server administrators, cannot read the encrypted
24
+ With CSFLE, your client application encrypts fields client-side without
25
+ requiring any server-side configuration or directives. CSFLE is useful
26
+ for situations in which applications must guarantee that unauthorized
27
+ parties, including server administrators, cannot read the encrypted
28
28
data.
29
29
30
- This guide is a quick introduction to CSFLE using the Node.js driver.
30
+ This guide is a quick introduction to CSFLE using the Node.js driver.
31
31
For in-depth information on how CSFLE works, see
32
- the :manual:`CSFLE reference </core/security-client-side-encryption/>`
33
- documentation. For a real-world scenario and implementation, see our
34
- `CSFLE Guide <https://docs .mongodb.com/drivers/security/client-side-field-level-encryption-guide>`_ .
32
+ the :manual:`CSFLE reference </core/security-client-side-encryption/>`
33
+ documentation. For a real-world scenario and implementation, see our
34
+ `CSFLE Guide <https://www .mongodb.com/docs/ drivers/security/client-side-field-level-encryption-guide>`__ .
35
35
36
36
Installation
37
37
------------
@@ -45,8 +45,8 @@ To get started with CSFLE in your client application, you need:
45
45
``mongodb-client-encryption``
46
46
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47
47
48
- The ``mongodb-client-encryption`` module is the official client
49
- encryption module for the MongoDB Node.js driver. It contains bindings
48
+ The ``mongodb-client-encryption`` module is the official client
49
+ encryption module for the MongoDB Node.js driver. It contains bindings
50
50
to communicate with the native library that manages the encryption.
51
51
52
52
Add it to your project using ``npm``:
@@ -59,10 +59,10 @@ Add it to your project using ``npm``:
59
59
``mongocryptd``
60
60
~~~~~~~~~~~~~~~
61
61
62
- ``mongocryptd`` is launched automatically by the package, and it is used for
63
- automatic encryption. ``mongocryptd`` communicates with
64
- ``mongodb-client-encryption`` to automatically encrypt the information
65
- specified by a user-provided
62
+ ``mongocryptd`` is launched automatically by the package, and it is used for
63
+ automatic encryption. ``mongocryptd`` communicates with
64
+ ``mongodb-client-encryption`` to automatically encrypt the information
65
+ specified by a user-provided
66
66
:manual:`JSON Schema </reference/security-client-side-automatic-json-schema/>`.
67
67
68
68
For more detailed information on ``mongocryptd``, see the
@@ -71,23 +71,23 @@ For more detailed information on ``mongocryptd``, see the
71
71
Example
72
72
-------
73
73
74
- The following example shows how to configure a CSFLE-enabled client
75
- with a local key and a JSON schema. Values in the ``ssn`` field are
76
- automatically encrypted before insertion, and decrypted when calling
74
+ The following example shows how to configure a CSFLE-enabled client
75
+ with a local key and a JSON schema. Values in the ``ssn`` field are
76
+ automatically encrypted before insertion, and decrypted when calling
77
77
``find()`` with a CSFLE-enabled client.
78
78
79
79
.. warning::
80
80
81
- MongoDB recommends using local key management only for testing
81
+ MongoDB recommends using local key management only for testing
82
82
purposes, and using a remote key management service
83
83
for production.
84
84
85
- An expanded example with support for remote key management services is
86
- available at MongoDB University's GitHub
85
+ An expanded example with support for remote key management services is
86
+ available at MongoDB University's GitHub
87
87
`Node CSFLE Example <https://github.com/mongodb-university/csfle-guides/tree/master/nodejs>`__.
88
88
89
89
.. note::
90
-
90
+
91
91
Auto encryption requires MongoDB **Enterprise** or **Atlas**.
92
92
93
93
To run this example, first complete the following steps:
@@ -98,16 +98,16 @@ To run this example, first complete the following steps:
98
98
- Start a ``mongocryptd`` locally on the default port 27020.
99
99
100
100
.. code-block:: javascript
101
-
101
+
102
102
const { MongoClient, Binary } = require("mongodb");
103
103
const { ClientEncryption } = require("mongodb-client-encryption");
104
104
const fs = require("fs/promises");
105
-
105
+
106
106
async function getRegularClient() {
107
107
const client = new MongoClient("mongodb://localhost:27017");
108
108
return await client.connect();
109
109
}
110
-
110
+
111
111
async function getCsfleEnabledClient(schemaMap) {
112
112
const client = new MongoClient("mongodb://localhost:27017", {
113
113
autoEncryption: {
@@ -122,7 +122,7 @@ To run this example, first complete the following steps:
122
122
});
123
123
return await client.connect();
124
124
}
125
-
125
+
126
126
function createJsonSchemaMap(dataKey) {
127
127
return {
128
128
"users.ssns": {
@@ -141,7 +141,7 @@ To run this example, first complete the following steps:
141
141
},
142
142
};
143
143
}
144
-
144
+
145
145
async function makeDataKey(client) {
146
146
const encryption = new ClientEncryption(client, {
147
147
keyVaultNamespace: "encryption.__keyVault",
@@ -151,69 +151,69 @@ To run this example, first complete the following steps:
151
151
},
152
152
},
153
153
});
154
-
154
+
155
155
let dataKey = await encryption.createDataKey("local", {
156
156
masterKey: null,
157
157
});
158
-
158
+
159
159
return dataKey.toString("base64");
160
160
}
161
-
161
+
162
162
async function run(regularClient, csfleClient) {
163
163
try {
164
-
164
+
165
165
regularClient = await getRegularClient();
166
-
166
+
167
167
let dataKey = await makeDataKey(regularClient);
168
168
console.log(
169
169
"New dataKey created for this run:\n",
170
170
dataKey
171
171
);
172
-
172
+
173
173
const schemaMap = createJsonSchemaMap(dataKey);
174
-
174
+
175
175
csfleClient = await getCsfleEnabledClient(schemaMap);
176
-
176
+
177
177
const regularClientSsnsColl = regularClient
178
178
.db("users")
179
179
.collection("ssns");
180
180
const csfleClientSsnsColl = csfleClient
181
181
.db("users")
182
182
.collection("ssns");
183
-
183
+
184
184
const exampleDocument = {
185
185
name: "Jon Doe",
186
186
ssn: 241014209,
187
187
};
188
-
188
+
189
189
await csfleClientSsnsColl.updateOne(
190
190
{ ssn: exampleDocument.ssn },
191
191
{ $set: exampleDocument },
192
192
{ upsert: true }
193
193
);
194
-
194
+
195
195
const csfleFindResult = await csfleClientSsnsColl.findOne({
196
196
ssn: exampleDocument.ssn,
197
197
});
198
198
console.log(
199
199
"Document retrieved with csfle enabled client:\n",
200
200
csfleFindResult
201
201
);
202
-
202
+
203
203
const regularFindResult = await regularClientSsnsColl.findOne({
204
204
name: "Jon Doe",
205
205
});
206
206
console.log(
207
- "Document retrieved with regular client:\n",
207
+ "Document retrieved with regular client:\n",
208
208
regularFindResult
209
209
);
210
-
210
+
211
211
} finally {
212
212
if (regularClient) await regularClient.close();
213
213
if (csfleClient) await csfleClient.close();
214
214
}
215
215
}
216
-
216
+
217
217
run().catch(error => {
218
218
console.dir(error);
219
219
process.exit(1);
0 commit comments