Skip to content

Commit a83dbb2

Browse files
andf-mongodbandf-mongodb
committed
DOCSP-14691 add shell csfle section
1 parent 64b2638 commit a83dbb2

9 files changed

+496
-3
lines changed

‎snooty.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title = "MongoDB Shell"
33

44
intersphinx = ["https://docs.mongodb.com/manual/objects.inv"]
55

6-
toc_landing_pages = ["/run-commands", "/crud"]
6+
toc_landing_pages = ["/run-commands", "/crud", "/field-level-encryption"]
77

88
[constants]
99

‎source/changelog.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ v0.8.0
2626

2727
New features in this release:
2828

29-
- Support for :ref:`client-side field level encryption <fle-methods-mongosh>`.
29+
- Support for :doc:`field-level-encryption`.
3030

3131
Bug fixes in this release:
3232

@@ -36,7 +36,7 @@ Bug fixes in this release:
3636
- Pressing the backspace key in the password prompt no longer adds an
3737
asterisk, and now behaves as expected.
3838

39-
- Running :method:`~UUID()` without a value now generates a random UUID.
39+
- Running ``UUID()`` without a value now generates a random UUID.
4040

4141
v0.7.7
4242
------

‎source/field-level-encryption.txt

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
.. _mdb-shell-csfle:
2+
3+
==================================
4+
Client-Side Field Level Encryption
5+
==================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
When working with a `MongoDB Enterprise
16+
<http://www.mongodb.com/products/mongodb-enterprise-advanced?jmp=docs>`__
17+
or MongoDB Atlas cluster, you can use ``mongosh`` to configure
18+
:manual:`Client-Side Field Level Encryption
19+
</core/security-client-side-encryption>` and connect with encryption
20+
support. Client-side field level encryption uses data encryption keys
21+
for supporting encryption and decryption of field values, and stores
22+
this encryption key material in a Key Management Service (KMS).
23+
24+
``mongosh`` supports the following KMS providers for use with
25+
client-side field level encryption:
26+
27+
- Amazon Web Services KMS
28+
- Azure Key Vault
29+
- Google Cloud Platform KMS
30+
- Locally Managed Keyfile
31+
32+
Create a Data Encryption Key
33+
----------------------------
34+
35+
The following procedure uses ``mongosh`` to create a data encryption key
36+
for use with client-side field level encryption and decryption.
37+
38+
Use the tabs below to select the :abbr:`KMS (Key Management Service)`
39+
appropriate for your deployment:
40+
41+
.. tabs::
42+
43+
.. tab:: Amazon KMS
44+
:tabid: aws-kms
45+
46+
.. include:: /includes/steps/aws-kms.rst
47+
48+
.. tab:: Azure Key Vault
49+
:tabid: azure-vault
50+
51+
.. include:: /includes/steps/azure-vault.rst
52+
53+
.. tab:: Google Cloud KMS
54+
:tabid: gcp-kms
55+
56+
.. include:: /includes/steps/gcp-kms.rst
57+
58+
.. tab:: Local Keyfile
59+
:tabid: local-keyfile
60+
61+
.. include:: /includes/steps/local-keyfile.rst
62+
63+
.. seealso::
64+
65+
- :ref:`List of field level encryption shell methods <fle-methods-mongosh>`
66+
- :manual:`Client-side field level encryption reference
67+
</core/security-client-side-encryption>`

‎source/includes/fact-getkey-options.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
If successful, :method:`createKey() <KeyVault.createKey()>` returns
2+
the :abbr:`UUID (Universally unique identifier)` of the new data
3+
encryption key. To retrieve the new data encryption key document from
4+
the key vault, either:
5+
6+
- Use :method:`getKey() <KeyVault.getKey()>` to retrieve the created
7+
key by its :abbr:`UUID (Universally unique identifier)`, or
8+
- Use :method:`getKeyByAltName() <KeyVault.getKeyByAltName()>` to
9+
retrieve the key by its alternate name, if specified.

‎source/includes/steps-aws-kms.yaml

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: "Launch the ``mongosh`` Shell."
3+
ref: launch-mongosh-shell
4+
level: 4
5+
content: |
6+
7+
Create a ``mongosh`` session without connecting to a running database
8+
by using the :option:`--nodb` option:
9+
10+
.. code-block:: javascript
11+
12+
mongosh --nodb
13+
14+
---
15+
title: "Create the Encryption Configuration."
16+
ref: create-encryption-configuration
17+
level: 4
18+
content: |
19+
20+
Configuring client-side field level encryption for the AWS KMS
21+
requires an AWS Access Key ID and its associated Secret Access Key.
22+
The AWS Access Key must correspond to an IAM user with all *List* and
23+
*Read* permissions for the KMS service.
24+
25+
In ``mongosh``, create a new
26+
:ref:`ClientSideFieldLevelEncryptionOptions` variable for storing the
27+
client-side field level encryption configuration, which contains these
28+
credentials:
29+
30+
.. code-block:: javascript
31+
32+
var ClientSideFieldLevelEncryptionOptions = {
33+
"keyVaultNamespace" : "encryption.__dataKeys",
34+
"kmsProviders" : {
35+
"aws" : {
36+
"accessKeyId" : "YOUR_AWS_ACCESS_KEY_ID",
37+
"secretAccessKey" : "YOUR_AWS_SECRET_ACCESS_KEY"
38+
}
39+
}
40+
}
41+
42+
Fill in the values for ``YOUR_AWS_ACCESS_KEY_ID`` and
43+
``YOUR_AWS_SECRET_ACCESS_KEY`` as appropriate.
44+
45+
---
46+
title: "Connect with Encryption Support."
47+
ref: connect-with-encryption
48+
level: 4
49+
content: |
50+
51+
In ``mongosh``, use the :method:`Mongo()<Mongo()>` constructor to
52+
establish a database connection to the target cluster. Specify the
53+
:ref:`ClientSideFieldLevelEncryptionOptions` document as the second
54+
parameter to the :method:`Mongo()<Mongo()>` constructor to configure
55+
the connection for client-side field level encryption:
56+
57+
.. code-block:: javascript
58+
59+
csfleDatabaseConnection = Mongo(
60+
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
61+
ClientSideFieldLevelEncryptionOptions
62+
)
63+
64+
Replace the ``replaceMe.example.net`` :ref:`URI <mongodb-uri>` with
65+
the connection string for the target cluster.
66+
67+
---
68+
title: "Create the Key Vault Object."
69+
ref: create-keyvault-object
70+
level: 4
71+
content: |
72+
73+
Create the ``keyVault`` object using the :method:`getKeyVault()
74+
<getKeyVault()>` shell method:
75+
76+
.. code-block:: javascript
77+
78+
keyVault = csfleDatabaseConnection.getKeyVault();
79+
---
80+
title: "Create the Encryption Key."
81+
ref: create-encryption-key
82+
level: 4
83+
content: |
84+
85+
Create the data encryption key using the
86+
:method:`createKey() <KeyVault.createKey()>` shell method:
87+
88+
.. code-block:: javascript
89+
90+
keyVault.createKey(
91+
"aws",
92+
{ region: "regionname", key: "awsarn" }
93+
)
94+
95+
Where:
96+
97+
- ``regionname`` is the AWS region you are connecting to, such as
98+
``us-west-2``
99+
- ``awsarn`` is the `Amazon Resource Name (ARN)
100+
<https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html>`__
101+
to the AWS customer master key (CMK).
102+
103+
.. include:: /includes/fact-getkey-options.rst
104+
...

‎source/includes/steps-azure-vault.yaml

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: "Launch the ``mongosh`` Shell."
3+
ref: launch-mongosh-shell
4+
level: 4
5+
content: |
6+
7+
Create a ``mongosh`` session without connecting to a running database
8+
by using the :option:`--nodb` option:
9+
10+
.. code-block:: javascript
11+
12+
mongosh --nodb
13+
14+
---
15+
title: "Create the Encryption Configuration."
16+
ref: create-encryption-configuration
17+
level: 4
18+
content: |
19+
20+
Configuring client-side field level encryption for Azure Key Vault
21+
requires a valid Tenant ID, Client ID, and Client Secret.
22+
23+
In ``mongosh``, create a new
24+
:ref:`ClientSideFieldLevelEncryptionOptions` variable for storing the
25+
client-side field level encryption configuration, which contains these
26+
credentials:
27+
28+
.. code-block:: javascript
29+
30+
var ClientSideFieldLevelEncryptionOptions = {
31+
"keyVaultNamespace" : "encryption.__dataKeys",
32+
"kmsProviders" : {
33+
"azure" : {
34+
"tenantId" : "YOUR_TENANT_ID",
35+
"clientId" : "YOUR_CLIENT_ID",
36+
"clientSecret" : "YOUR_CLIENT_SECRET"
37+
}
38+
}
39+
}
40+
41+
Fill in the values for ``YOUR_TENANT_ID``, ``YOUR_CLIENT_ID``, and
42+
``YOUR_CLIENT_SECRET`` as appropriate.
43+
44+
---
45+
title: "Connect with Encryption Support."
46+
ref: connect-with-encryption
47+
level: 4
48+
content: |
49+
50+
In ``mongosh``, use the :method:`Mongo()<Mongo()>` constructor to
51+
establish a database connection to the target cluster. Specify the
52+
:ref:`ClientSideFieldLevelEncryptionOptions` document as the second
53+
parameter to the :method:`Mongo()<Mongo()>` constructor to configure
54+
the connection for client-side field level encryption:
55+
56+
.. code-block:: javascript
57+
58+
csfleDatabaseConnection = Mongo(
59+
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
60+
ClientSideFieldLevelEncryptionOptions
61+
)
62+
63+
Replace the ``replaceMe.example.net`` :ref:`URI <mongodb-uri>` with
64+
the connection string for the target cluster.
65+
66+
---
67+
title: "Create the Key Vault Object."
68+
ref: create-keyvault-object
69+
level: 4
70+
content: |
71+
72+
Create the ``keyVault`` object using the :method:`getKeyVault()
73+
<getKeyVault()>` shell method:
74+
75+
.. code-block:: javascript
76+
77+
keyVault = csfleDatabaseConnection.getKeyVault();
78+
---
79+
title: "Create the Encryption Key."
80+
ref: create-encryption-key
81+
level: 4
82+
content: |
83+
84+
Create the data encryption key using the
85+
:method:`createKey() <KeyVault.createKey()>` shell method:
86+
87+
.. code-block:: javascript
88+
89+
keyVault.createKey(
90+
"azure",
91+
{ keyName: "keyvaultname", keyVaultEndpoint: "endpointname" }
92+
)
93+
94+
Where:
95+
96+
- ``keyvaultname`` is the name of your `Azure Key Vault
97+
<https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name>`__
98+
- ``endpointname`` is the name of the Key Vault Endpoint to use
99+
100+
.. include:: /includes/fact-getkey-options.rst
101+
...

0 commit comments

Comments
 (0)