Skip to content

Commit 362e088

Browse files
jmd-mongojmd-mongo
authored
DOCSP-28275 createEncryptedClient (#3412)
* DOCSP-28275 createEncryptedClient * fix filename * fix filename * includify * include * internal review * removes title * nav * use procedure admonition in example * clean up options * procedure-ify * external review feedback * removes createEncryptedCollection method mention from release notes
1 parent 10b0dc9 commit 362e088

10 files changed

+424
-187
lines changed

‎source/includes/create-an-encrypted-db-conn.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
The :binary:`~bin.mongosh` client-side field level and queryable
2+
encryption methods require a database connection configured for
3+
client-side encryption. If the current database connection was not
4+
initiated with client-side field level encryption enabled, either:
5+
6+
- Use the :method:`Mongo()` constructor from the ``mongosh``
7+
to establish a connection with the required client-side field
8+
level encryption options. The ``Mongo()`` method supports the
9+
following Key Management Service (KMS) providers for Customer
10+
Master Key (CMK) management:
11+
12+
- :ref:`Amazon Web Services KMS <field-level-encryption-aws-kms>`
13+
- :ref:`Azure Key Vault <field-level-encryption-azure-keyvault>`
14+
- :ref:`Google Cloud Platform KMS <field-level-encryption-gcp-kms>`
15+
- :ref:`Locally Managed Key <field-level-encryption-local-kms>`
16+
17+
*or*
18+
19+
- Use the ``mongosh`` :ref:`command line options
20+
<mongosh-client-side-field-level-encryption-options>` to establish a
21+
connection with the required options. The command line options only
22+
support the :ref:`Amazon Web Services KMS
23+
<field-level-encryption-aws-kms>` provider for CMK management.

‎source/includes/csfle-connection-boilerplate-example.rst

Lines changed: 52 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,52 @@
1-
To configure client-side field level encryption for a locally managed
2-
key:
3-
4-
- generate a base64-encoded 96-byte string with no line breaks
5-
- use :binary:`mongosh` to load the key
6-
7-
.. code-block:: bash
8-
:emphasize-lines: 1
9-
10-
export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
11-
12-
mongosh --nodb
13-
14-
Create the client-side field level encryption object using the
15-
generated local key string:
16-
17-
.. code-block:: javascript
18-
:emphasize-lines: 5
19-
20-
var autoEncryptionOpts = {
21-
"keyVaultNamespace" : "encryption.__dataKeys",
22-
"kmsProviders" : {
23-
"local" : {
24-
"key" : BinData(0, process.env["TEST_LOCAL_KEY"])
25-
}
26-
}
27-
}
28-
29-
Use the :method:`Mongo()` constructor with the client-side field level
30-
encryption options configured to create a database connection. Replace
31-
the ``mongodb://myMongo.example.net`` URI with the :ref:`connection
32-
string URI <mongodb-uri>` of the target cluster.
33-
34-
.. code-block:: javascript
35-
:emphasize-lines: 2
36-
37-
encryptedClient = Mongo(
38-
"mongodb://myMongo.example.net:27017/?replSetName=myMongo",
39-
autoEncryptionOpts
40-
)
1+
.. procedure::
2+
:style: normal
3+
4+
.. step:: Start mongosh
5+
6+
Start the ``mongosh`` client.
7+
8+
.. code-block:: bash
9+
10+
mongosh --nodb
11+
12+
.. step:: Generate Your Key
13+
14+
To configure client-side field level encryption for a locally
15+
managed key, generate a base64-encoded 96-byte string with no line
16+
breaks.
17+
18+
.. code-block:: javascript
19+
20+
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
21+
22+
.. step:: Create the Client-Side Field Level Encryption Options
23+
24+
Create the client-side field level encryption options using the
25+
generated local key string:
26+
27+
.. code-block:: javascript
28+
:emphasize-lines: 5
29+
30+
var autoEncryptionOpts = {
31+
"keyVaultNamespace" : "encryption.__dataKeys",
32+
"kmsProviders" : {
33+
"local" : {
34+
"key" : BinData(0, TEST_LOCAL_KEY)
35+
}
36+
}
37+
}
38+
39+
.. step:: Create Your Encrypted Client
40+
41+
Use the :method:`Mongo()` constructor with the client-side field level
42+
encryption options configured to create a database connection. Replace
43+
the ``mongodb://myMongo.example.net`` URI with the :ref:`connection
44+
string URI <mongodb-uri>` of the target cluster.
45+
46+
.. code-block:: javascript
47+
:emphasize-lines: 2
48+
49+
encryptedClient = Mongo(
50+
"mongodb://myMongo.example.net:27017/?replSetName=myMongo",
51+
autoEncryptionOpts
52+
)

‎source/includes/qe-connection-boilerplate.rst

Lines changed: 49 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,50 @@
1-
Configuring queryable encryption for a locally managed key requires
2-
specifying a base64-encoded 96-byte string with no line breaks. The
3-
following operation generates a key that meets the stated requirements
4-
and loads it into :binary:`~bin.mongosh`:
5-
6-
.. code-block:: bash
7-
:emphasize-lines: 1
8-
9-
export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
10-
11-
mongosh --nodb
12-
13-
Create the client-side field level encryption object using the
14-
generated local key string:
15-
16-
.. code-block:: javascript
17-
:emphasize-lines: 5
18-
19-
var autoEncryptionOpts = {
20-
"keyVaultNamespace" : "encryption.__keyVault",
21-
"kmsProviders" : {
22-
"local" : {
23-
"key" : BinData(0, process.env["TEST_LOCAL_KEY"])
24-
}
25-
}
26-
}
27-
28-
Use the :method:`Mongo()` constructor to create a database connection
29-
with the queryable encryption options. Replace the
30-
``mongodb://myMongo.example.net`` URI with the :ref:`connection string
31-
URI <mongodb-uri>` of the target cluster.
32-
33-
.. code-block:: javascript
34-
:emphasize-lines: 2
1+
.. procedure::
2+
:style: normal
3+
4+
.. step:: Start mongosh
5+
6+
Start the ``mongosh`` client.
7+
8+
.. code-block:: bash
9+
10+
mongosh --nodb
11+
12+
.. step:: Generate Your Key
13+
14+
To configure queryable encryption for a locally managed key,
15+
generate a base64-encoded 96-byte string with no line breaks.
16+
17+
.. code-block:: javascript
18+
19+
const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
20+
21+
.. step:: Create the Queryable Encryption Options
3522

36-
encryptedClient = Mongo(
37-
"mongodb://myMongo.example.net:27017/?replSetName=myMongo",
38-
autoEncryptionOpts
39-
)
23+
Create the queryable encryption options using the generated local key string:
24+
25+
.. code-block:: javascript
26+
:emphasize-lines: 5
27+
28+
var autoEncryptionOpts = {
29+
"keyVaultNamespace" : "encryption.__dataKeys",
30+
"kmsProviders" : {
31+
"local" : {
32+
"key" : BinData(0, TEST_LOCAL_KEY)
33+
}
34+
}
35+
}
36+
37+
.. step:: Create Your Encrypted Client
38+
39+
Use the :method:`Mongo()` constructor with the queryable
40+
encryption options configured to create a database connection. Replace
41+
the ``mongodb://myMongo.example.net`` URI with the :ref:`connection
42+
string URI <mongodb-uri>` of the target cluster.
43+
44+
.. code-block:: javascript
45+
:emphasize-lines: 2
46+
47+
encryptedClient = Mongo(
48+
"mongodb://myMongo.example.net:27017/?replSetName=myMongo",
49+
autoEncryptionOpts
50+
)

‎source/reference/method.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1319,6 +1319,10 @@ Client-Side Field Level Encryption
13191319

13201320
- Returns the client encryption object for supporting explicit encryption/decryption of fields.
13211321

1322+
* - :method:`ClientEncryption.createEncryptedCollection()`
1323+
1324+
- Creates a collection with encrypted fields.
1325+
13221326
* - :method:`ClientEncryption.encrypt()`
13231327

13241328
- Encrypts a field using a specified data encryption key and encryption algorithm.

‎source/reference/method/ClientEncryption.createEncryptedCollection.txt

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
============================================
2+
ClientEncryption.createEncryptedCollection()
3+
============================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. versionadded:: 7.0
14+
15+
.. method:: ClientEncryption.createEncryptedCollection(dbName, collName, clientEncOpts)
16+
17+
``ClientEncryption.createEncryptedCollection`` creates an
18+
encrypted collection specified by ``collName`` on the database
19+
specified by ``dbName``.
20+
21+
Syntax
22+
------
23+
24+
``ClientEncryption.createEncryptedCollection`` has the
25+
following syntax:
26+
27+
.. code-block:: javascript
28+
29+
clientEncryption = db.getMongo().getClientEncryption()
30+
31+
clientEncryption.createEncryptedCollection(
32+
dbName,
33+
collName,
34+
{
35+
provider: kmsProviderName,
36+
createCollectionOptions: encryptedFieldsMap,
37+
masterKey: customerMasterKeyCredentials
38+
}
39+
)
40+
41+
Command Fields
42+
--------------
43+
44+
``createEncryptedCollection`` takes these fields:
45+
46+
.. list-table::
47+
:header-rows: 1
48+
:widths: 20 20 20 80
49+
50+
* - Field
51+
- Type
52+
- Necessity
53+
- Description
54+
55+
* - ``dbName``
56+
- string
57+
- Required
58+
- Name of the database to encrypt.
59+
60+
* - ``collName``
61+
- string
62+
- Required
63+
- Name of the collection to encrypt.
64+
65+
* - ``clientEncOpts``
66+
- document
67+
- Required
68+
- Options to configure the encrypted collection.
69+
70+
* - ``clientEncOpts.provider``
71+
- string
72+
- Required
73+
- KMS you are using to store your {+cmk-long+}.
74+
75+
* - ``clientEncOpts.createCollectionOptions``
76+
- document
77+
- Required
78+
- Fields to encrypt. See :ref:`qe-specify-fields-for-encryption`
79+
for details on how to configure the ``encryptedFieldsMap`` object.
80+
81+
* - ``clientEncOpts.masterKey``
82+
- document
83+
- Optional
84+
- How to get the master key when the KMS Provider is AWS, GCP, or
85+
Azure.
86+
87+
Behavior
88+
--------
89+
90+
.. include:: /includes/create-an-encrypted-db-conn.rst
91+
92+
Example
93+
-------
94+
95+
The following example uses a locally managed KMS for the
96+
queryable encryption configuration.
97+
98+
.. procedure::
99+
:style: normal
100+
101+
.. step:: Create Your Encrypted Connection
102+
103+
.. include:: /includes/csfle-connection-boilerplate-example.rst
104+
105+
.. step:: Specify which Fields to Encrypt
106+
107+
Create an ``encryptedFieldsMaps`` to specify which fields to encrypt:
108+
109+
.. code-block:: javascript
110+
111+
const encryptedFieldsMap = {
112+
encryptedFields: {
113+
fields: [
114+
{
115+
path: "secretField",
116+
bsonType: "string",
117+
queries: { queryType: "equality" },
118+
},
119+
],
120+
},
121+
};
122+
123+
.. step:: Create Your Encrypted Collection
124+
125+
Create an encrypted ``enc.users`` collection:
126+
127+
.. code-block:: javascript
128+
129+
clientEncryption = encryptedClient.getClientEncryption();
130+
131+
var result = clientEncryption.createEncryptedCollection(
132+
"enc",
133+
"users",
134+
{
135+
provider: "local",
136+
createCollectionOptions: encryptedFieldsMap,
137+
masterKey: {} // masterKey is optional when provider is local
138+
}
139+
)
140+
141+
.. step:: Check Your Result Object
142+
143+
``createEncryptedCollection`` returns a large result object with many
144+
fields. Check the value of ``result.collection`` to confirm the
145+
collection was created in the desired location.
146+
147+
.. code-block:: javascript
148+
:copyable: false
149+
150+
enc> result.collection
151+
enc.users
152+
153+
Learn More
154+
----------
155+
156+
- For complete documentation on initiating MongoDB connections with
157+
client-side field level encryption enabled, see :method:`Mongo()`.
158+
159+
- For a complete example of how to create and query an encrypted
160+
collection, see :ref:`qe-quick-start`.

0 commit comments

Comments
 (0)