Skip to content

Commit fa4331d

Browse files
biniona-mongodbbiniona-mongodb
authored
(DOCSP-24937) KMIP Tutorial (#1747)
* kmip qe reader update * formatting * init * build errors rst * add missing code snippets * convo with cynthia - use kmip-compliant key provider rather than kmip kms or kmip provider * terminology update * tweak * proofread * broken links * tweak * tweak
1 parent f1f66c8 commit fa4331d

File tree

42 files changed

+1041
-59
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1041
-59
lines changed

‎snooty.toml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -264,8 +264,9 @@ manual-enc = "explicit encryption"
264264
manual-enc-title = "Explicit Encryption"
265265
manual-enc-first = "Explicit encryption"
266266
kmip-hover = ":abbr:`KMIP (Key Management Interoperability Protocol)`"
267-
kmip-kms-no-hover = "KMIP-compliant Key Management System"
268-
kmip-kms = "{+kmip-hover+}-compliant {+kms-abbr+}"
267+
kmip-kms-no-hover = "KMIP-compliant key provider"
268+
kmip-kms = "{+kmip-hover+}-compliant key provider"
269+
kmip-kms-title = "KMIP-Compliant Key Provider"
269270
csfle-code-snippets-gen-keys = "https://github.com/mongodb/docs/tree/master/source/includes/quick-start/generate-master-key"
270271
libmongocrypt-version = "1.5"
271272
sample-app-url-csfle = "https://github.com/mongodb-university/docs-in-use-encryption-examples/tree/main/csfle"

‎source/core/csfle/tutorials/kmip/kmip-automatic.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Overview
1717

1818
This guide shows you how to build a {+csfle+} ({+csfle-abbrev+})-enabled
1919
application using a Key Management Interoperability Protocol
20-
(KMIP)-compliant **{+kms-long+}** (KMS).
20+
(KMIP)-compliant key provider.
2121

2222
After you complete the steps in this guide, you should have:
2323

‎source/core/queryable-encryption/features.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ The process and mechanisms that makes this possible within the
6767
- AWS Key Management Service (AWS KMS)
6868
- Google Cloud KMS
6969
- Azure Key Vault
70-
- Any KMIP-enabled provider
70+
- Any {+kmip-kms+}
7171

7272
3. The driver submits the query to the MongoDB server with the encrypted
7373
fields rendered as ciphertext.

‎source/core/queryable-encryption/tutorials.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ Read the following pages to learn how to use {+qe+} with your preferred
3030

3131
- :ref:`qe-tutorial-automatic-gcp`
3232

33+
- Any {+kmip-kms-title+}
34+
35+
- :ref:`qe-tutorial-automatic-kmip`
36+
3337
To learn how to use {+manual-enc+} with {+qe+}, read
3438
:ref:`<qe-tutorials-manual-encryption>`.
3539

@@ -39,4 +43,5 @@ To learn how to use {+manual-enc+} with {+qe+}, read
3943
/core/queryable-encryption/tutorials/aws/aws-automatic
4044
/core/queryable-encryption/tutorials/azure/azure-automatic
4145
/core/queryable-encryption/tutorials/gcp/gcp-automatic
46+
/core/queryable-encryption/tutorials/kmip/kmip-automatic
4247
/core/queryable-encryption/tutorials/explicit-encryption

‎source/core/queryable-encryption/tutorials/kmip/kmip-automatic.txt

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
.. _qe-tutorial-automatic-kmip:
2+
3+
===========================================================
4+
Use Automatic {+qe+} with KMIP
5+
===========================================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
This guide shows you how to build a {+qe+} ({+qe-abbr+})-enabled
19+
application using a Key Management Interoperability Protocol
20+
(KMIP)-compliant key provider.
21+
22+
After you complete the steps in this guide, you should have:
23+
24+
- A {+cmk-long+} hosted on a {+kmip-kms+}.
25+
- A working client application that inserts encrypted documents
26+
using your {+cmk-long+}.
27+
28+
Before You Get Started
29+
----------------------
30+
31+
.. include:: /includes/queryable-encryption/set-up-section.rst
32+
33+
.. include:: /includes/fact-csfle-placeholder.rst
34+
35+
.. include:: /includes/select-your-language.rst
36+
37+
.. see:: Full Application
38+
39+
To view the complete runnable application code for this tutorial, go to the
40+
following link:
41+
42+
.. tabs-drivers::
43+
44+
.. tab:: Java
45+
:tabid: java-sync
46+
47+
`Complete Java Application <{+sample-app-url-qe+}/java/kmip/reader/>`__
48+
49+
.. tab:: Node.js
50+
:tabid: nodejs
51+
52+
`Complete Node.js Application <{+sample-app-url-qe+}/node/kmip/reader/>`__
53+
54+
.. tab:: Python
55+
:tabid: python
56+
57+
`Complete Python Application <{+sample-app-url-qe+}/python/kmip/reader/>`__
58+
59+
.. tab:: C#
60+
:tabid: csharp
61+
62+
`Complete C# Application <{+sample-app-url-qe+}/dotnet/kmip/reader/QueryableEncryption/>`__
63+
64+
.. tab:: Go
65+
:tabid: go
66+
67+
`Complete Go Application <{+sample-app-url-qe+}/go/kmip/reader/>`__
68+
69+
.. tabs-selector:: drivers
70+
71+
Set Up the KMS
72+
--------------
73+
74+
.. include:: /includes/tutorials/language-id.rst
75+
76+
.. procedure::
77+
:style: normal
78+
79+
.. step:: Configure your {+kmip-kms-title+}
80+
81+
.. include:: /includes/queryable-encryption/tutorials/automatic/kmip/configure.rst
82+
83+
.. step:: Specify your Certificates
84+
85+
.. include:: /includes/queryable-encryption/tutorials/automatic/kmip/certificates.rst
86+
87+
Create the Application
88+
----------------------
89+
90+
Select the tab that corresponds to the MongoDB driver you are using in
91+
your application to see relevant code samples.
92+
93+
.. procedure::
94+
:style: normal
95+
96+
.. step:: Create a Unique Index on Your Key Vault Collection
97+
98+
.. include:: /includes/queryable-encryption/tutorials/automatic/kmip/key-vault-index.rst
99+
100+
.. step:: Create a {+dek-long+}
101+
102+
.. include:: /includes/queryable-encryption/tutorials/automatic/kmip/dek.rst
103+
104+
.. see:: Complete Code
105+
106+
.. tabs-drivers::
107+
108+
.. tab::
109+
:tabid: java-sync
110+
111+
To view the complete code for making a {+dek-long+}, see
112+
`our Github repository <{+sample-app-url-qe+}/java/kmip/reader/src/main/java/com/mongodb/qe/MakeDataKey.java>`__.
113+
114+
.. tab::
115+
:tabid: nodejs
116+
117+
To view the complete code for making a {+dek-long+}, see
118+
`our Github repository <{+sample-app-url-qe+}/node/kmip/reader/make_data_key.js>`__.
119+
120+
.. tab::
121+
:tabid: python
122+
123+
To view the complete code for making a {+dek-long+}, see
124+
`our Github repository <{+sample-app-url-qe+}/python/kmip/reader/make_data_key.py>`__.
125+
126+
.. tab::
127+
:tabid: csharp
128+
129+
To view the complete code for making a {+dek-long+}, see
130+
`our Github repository <{+sample-app-url-qe+}/dotnet/kmip/reader/QueryableEncryption/MakeDataKey.cs>`__.
131+
132+
.. tab::
133+
:tabid: go
134+
135+
To view the complete code for making a {+dek-long+}, see
136+
`our Github repository <{+sample-app-url-qe+}/go/kmip/reader/make-data-key.go>`__.
137+
138+
.. step:: Configure the MongoClient
139+
140+
.. include:: /includes/queryable-encryption/tutorials/automatic/kmip/client.rst
141+
142+
.. step:: Insert a Document with Encrypted Fields
143+
144+
.. include:: /includes/queryable-encryption/tutorials/automatic/kmip/insert.rst
145+
146+
.. see:: Complete Code
147+
148+
.. tabs-drivers::
149+
150+
.. tab::
151+
:tabid: java-sync
152+
153+
To view the complete code for inserting an encrypted document, see
154+
`our Github repository <{+sample-app-url-qe+}/java/kmip/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
155+
156+
.. tab::
157+
:tabid: nodejs
158+
159+
To view the complete code for inserting an encrypted document, see
160+
`our Github repository <{+sample-app-url-qe+}/node/kmip/reader/insert_encrypted_document.js>`__.
161+
162+
.. tab::
163+
:tabid: python
164+
165+
To view the complete code for inserting an encrypted document, see
166+
`our Github repository <{+sample-app-url-qe+}/python/kmip/reader/insert_encrypted_document.py>`__.
167+
168+
.. tab::
169+
:tabid: csharp
170+
171+
To view the complete code for inserting an encrypted document, see
172+
`our Github repository <{+sample-app-url-qe+}/dotnet/kmip/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__
173+
174+
.. tab::
175+
:tabid: go
176+
177+
To view the complete code for inserting an encrypted document, see
178+
`our Github repository <{+sample-app-url-qe+}/go/kmip/reader/insert-encrypted-document.go>`__.
179+
180+
.. step:: Retrieve Your Encrypted Document
181+
182+
.. include:: /includes/queryable-encryption/tutorials/automatic/kmip/find.rst
183+
184+
.. see:: Complete Code
185+
186+
.. tabs-drivers::
187+
188+
.. tab::
189+
:tabid: java-sync
190+
191+
To view the complete code for inserting an encrypted document, see
192+
`our Github repository <{+sample-app-url-qe+}/java/kmip/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
193+
194+
.. tab::
195+
:tabid: nodejs
196+
197+
To view the complete code for inserting an encrypted document, see
198+
`our Github repository <{+sample-app-url-qe+}/node/kmip/reader/insert_encrypted_document.js>`__.
199+
200+
.. tab::
201+
:tabid: python
202+
203+
To view the complete code for inserting an encrypted document, see
204+
`our Github repository <{+sample-app-url-qe+}/python/kmip/reader/insert_encrypted_document.py>`__.
205+
206+
.. tab::
207+
:tabid: csharp
208+
209+
To view the complete code for inserting an encrypted document, see
210+
`our Github repository <{+sample-app-url-qe+}/dotnet/kmip/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__
211+
212+
.. tab::
213+
:tabid: go
214+
215+
To view the complete code for inserting an encrypted document, see
216+
`our Github repository <{+sample-app-url-qe+}/go/kmip/reader/insert-encrypted-document.go>`__.
217+
218+
Learn More
219+
----------
220+
221+
To learn more about the topics mentioned in this guide, see the
222+
following links:
223+
224+
- :ref:`<qe-reference-keys-key-vaults>`
225+
- :ref:`<qe-fundamentals-kms-providers>`

‎source/includes/generated/in-use-encryption/csfle/dotnet/kmip/reader/CSFLE/InsertEncryptedDocument.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ public static void Insert()
2626
var provider = "kmip";
2727
var kmipKmsOptions = new Dictionary<string, object>
2828
{
29-
{ "endpoint", "<endpoint for your KMIP KMS>" },
29+
{ "endpoint", "<endpoint for your KMIP-compliant key provider>" },
3030
};
3131
kmsProviders.Add(provider, kmipKmsOptions);
3232
// end-kmsproviders

‎source/includes/generated/in-use-encryption/csfle/dotnet/kmip/reader/CSFLE/MakeDataKey.cs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,14 @@ public static void MakeKey()
2222
var provider = "kmip";
2323
var kmipKmsOptions = new Dictionary<string, object>
2424
{
25-
{ "endpoint", "<endpoint for your KMIP KMS>" },
25+
{ "endpoint", "<endpoint for your KMIP-compliant key provider>" },
2626
};
2727
kmsProviders.Add(provider, kmipKmsOptions);
2828
// end-kmsproviders
2929

3030
// start-datakeyopts
3131
var dataKeyOptions = new DataKeyOptions(
32-
masterKey: new BsonDocument { } // an empty key object prompts your KMIP provider to generate a new Customer Master Key
32+
masterKey: new BsonDocument { } // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key
3333
);
3434
// end-datakeyopts
3535
// start-create-index

‎source/includes/generated/in-use-encryption/csfle/go/kmip/reader/insert-encrypted-document.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ func Insert() error {
2424
provider := "kmip"
2525
kmsProviders := map[string]map[string]interface{}{
2626
provider: {
27-
"endpoint": "<endpoint for your KMIP KMS>",
27+
"endpoint": "<endpoint for your KMIP-compliant key provider>",
2828
},
2929
}
3030
// end-kmsproviders

‎source/includes/generated/in-use-encryption/csfle/go/kmip/reader/make-data-key.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@ func MakeKey() error {
1919
provider := "kmip"
2020
kmsProviders := map[string]map[string]interface{}{
2121
provider: {
22-
"endpoint": "<endpoint for your KMIP KMS>",
22+
"endpoint": "<endpoint for your KMIP-compliant key provider>",
2323
},
2424
}
2525
// end-kmsproviders
2626

2727
// start-datakeyopts
28-
masterKey := map[string]interface{}{} // an empty key object prompts your KMIP provider to generate a new Customer Master Key
28+
masterKey := map[string]interface{}{} // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key
2929
// end-datakeyopts
3030

3131
// start-create-index

‎source/includes/generated/in-use-encryption/csfle/java/kmip/reader/src/main/java/com/mongodb/csfle/InsertEncryptedDocument.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ public static void main(String[] args) throws Exception {
6060
String kmsProvider = "kmip";
6161
Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
6262
Map<String, Object> providerDetails = new HashMap<>();
63-
providerDetails.put("endpoint", "<endpoint for your KMIP KMS>");
63+
providerDetails.put("endpoint", "<endpoint for your KMIP-compliant key provider>");
6464
kmsProviders.put(kmsProvider, providerDetails);
6565
// end-kmsproviders
6666

‎source/includes/generated/in-use-encryption/csfle/java/kmip/reader/src/main/java/com/mongodb/csfle/MakeDataKey.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,12 +53,12 @@ public static void main(String[] args) throws Exception {
5353
String kmsProvider = "kmip";
5454
Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
5555
Map<String, Object> providerDetails = new HashMap<>();
56-
providerDetails.put("endpoint", "<endpoint for your KMIP KMS>");
56+
providerDetails.put("endpoint", "<endpoint for your KMIP-compliant key provider>");
5757
kmsProviders.put(kmsProvider, providerDetails);
5858
// end-kmsproviders
5959

6060
// start-datakeyopts
61-
BsonDocument masterKeyProperties = new BsonDocument(); // an empty key object prompts your KMIP provider to generate a new Customer Master Key
61+
BsonDocument masterKeyProperties = new BsonDocument(); // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key
6262
// end-datakeyopts
6363

6464
// start-create-index

‎source/includes/generated/in-use-encryption/csfle/node/kmip/reader/insert_encrypted_document.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ var namespace = `${db}.${coll}`;
99
const provider = "kmip";
1010
const kmsProviders = {
1111
kmip: {
12-
endpoint: "<endpoint for your KMIP KMS>",
12+
endpoint: "<endpoint for your KMIP-compliant key provider>",
1313
},
1414
};
1515
// end-kmsproviders

‎source/includes/generated/in-use-encryption/csfle/node/kmip/reader/make_data_key.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,13 @@ const { MongoClient, Binary } = mongodb;
66
const provider = "kmip";
77
const kmsProviders = {
88
kmip: {
9-
endpoint: "<endpoint for your KMIP KMS>",
9+
endpoint: "<endpoint for your KMIP-compliant key provider>",
1010
},
1111
};
1212
// end-kmsproviders
1313

1414
// start-datakeyopts
15-
const masterKey = {}; // an empty key object prompts your KMIP provider to generate a new Customer Master Key
15+
const masterKey = {}; // an empty key object prompts your KMIP-compliant key provider to generate a new Customer Master Key
1616
// end-datakeyopts
1717

1818
async function main() {

‎source/includes/generated/in-use-encryption/csfle/python/kmip/reader/insert_encrypted_document.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,9 @@
1515

1616
# start-kmsproviders
1717
provider = "kmip"
18-
kms_providers = {provider: {"endpoint": "<endpoint for your KMIP KMS>"}}
18+
kms_providers = {
19+
provider: {"endpoint": "<endpoint for your KMIP-compliant key provider>"}
20+
}
1921
# end-kmsproviders
2022

2123
# start-schema

0 commit comments

Comments
 (0)