Skip to content

Commit 44a0a72

Browse files
jordan-smith721jordan-smith721
authored
Kmip csfle tutorials (#1735)
* adding kmip tutorials * update insert * missed file rename * feedback
1 parent 2340325 commit 44a0a72

File tree

7 files changed

+833
-85
lines changed

7 files changed

+833
-85
lines changed

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

Lines changed: 154 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,6 @@ Use Automatic {+csfle+} with KMIP
1212
:depth: 2
1313
:class: singlecol
1414

15-
.. tabs-selector:: drivers
16-
1715
Overview
1816
--------
1917

@@ -27,29 +25,54 @@ After you complete the steps in this guide, you should have:
2725
- A working client application that inserts encrypted documents
2826
using your {+cmk-long+}.
2927

30-
.. note:: Limited Coverage
31-
32-
This tutorial contains code snippets for Java only, however,
33-
the following language drivers support performing {+csfle-abbrev+}
34-
with a {+kmip-kms+}:
35-
36-
- C#
37-
- Python
38-
- Go
39-
- Node.js
40-
41-
We plan to add these languages to this guide soon.
42-
4328
Before You Get Started
4429
----------------------
4530

4631
.. include:: /includes/set-up-section.rst
4732

4833
.. include:: /includes/fact-csfle-placeholder.rst
4934

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-csfle+}/java/kmip/reader/>`__
48+
49+
.. tab:: Node.js
50+
:tabid: nodejs
51+
52+
`Complete Node.js Application <{+sample-app-url-csfle+}/node/kmip/reader/>`__
53+
54+
.. tab:: Python
55+
:tabid: python
56+
57+
`Complete Python Application <{+sample-app-url-csfle+}/python/kmip/reader/>`__
58+
59+
.. tab:: C#
60+
:tabid: csharp
61+
62+
`Complete C# Application <{+sample-app-url-csfle+}/dotnet/kmip/reader/CSFLE/>`__
63+
64+
.. tab:: Go
65+
:tabid: go
66+
67+
`Complete Go Application <{+sample-app-url-csfle+}/go/kmip/reader/>`__
68+
69+
.. tabs-selector:: drivers
70+
5071
Set Up the KMS
5172
--------------
5273

74+
.. include:: /includes/tutorials/language-id.rst
75+
5376
.. procedure::
5477
:style: normal
5578

@@ -64,13 +87,54 @@ Set Up the KMS
6487
Create the Application
6588
----------------------
6689

90+
Select the tab that corresponds to the MongoDB driver you are using in
91+
your application to see relevant code samples.
92+
6793
.. procedure::
6894
:style: normal
6995

70-
.. step:: Generate your {+dek-long+}
96+
.. step:: Create a Unique Index on Your Key Vault Collection
97+
98+
.. include:: /includes/tutorials/automatic/kmip/key-vault-index.rst
99+
100+
.. step:: Create a {+dek-long+}
71101

72102
.. include:: /includes/tutorials/automatic/kmip/dek.rst
73103

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-csfle+}/java/kmip/reader/src/main/java/com/mongodb/csfle/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-csfle+}/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-csfle+}/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-csfle+}/dotnet/kmip/reader/CSFLE/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-csfle+}/go/kmip/reader/make-data-key.go>`__.
137+
74138
.. step:: Configure the MongoClient
75139

76140
.. include:: /includes/tutorials/automatic/kmip/client.rst
@@ -79,6 +143,78 @@ Create the Application
79143

80144
.. include:: /includes/tutorials/automatic/kmip/insert.rst
81145

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-csfle+}/java/kmip/reader/src/main/java/com/mongodb/csfle/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-csfle+}/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-csfle+}/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-csfle+}/dotnet/kmip/reader/CSFLE/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-csfle+}/go/kmip/reader/insert-encrypted-document.go>`__.
179+
180+
.. step:: Retrieve Your Encrypted Document
181+
182+
.. include:: /includes/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-csfle+}/java/kmip/reader/src/main/java/com/mongodb/csfle/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-csfle+}/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-csfle+}/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-csfle+}/dotnet/kmip/reader/CSFLE/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-csfle+}/go/kmip/reader/insert-encrypted-document.go>`__.
217+
82218
Learn More
83219
----------
84220

@@ -89,5 +225,5 @@ To learn more about the topics mentioned in this guide, see the
89225
following links:
90226

91227
- Learn more about CSFLE components on the :ref:`Reference <csfle-reference>` page.
92-
- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`<csfle-reference-keys-key-vaults>` page
93-
- See how KMS Providers manage your CSFLE keys on the :ref:`<csfle-reference-kms-providers>` page.
228+
- Learn how {+cmk-long+}s and {+dek-long+}s work on the :ref:`<csfle-reference-keys-key-vaults>` page.
229+
- See how KMS Providers manage your CSFLE keys on the :ref:`<csfle-reference-kms-providers>` page.

‎source/includes/tutorials/automatic/kmip/certificates.rst

Lines changed: 68 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,76 @@ a client certificate that your {+kmip-kms+} accepts:
33

44
.. tabs-drivers::
55

6-
.. tab::
7-
:tabid: java-sync
6+
.. tab::
7+
:tabid: java-sync
88

9-
Specify the following Java system properties to configure your client's
10-
TLS connection:
9+
Specify the following Java system properties to configure your client's
10+
TLS connection:
1111

12-
.. code-block:: shell
12+
.. code-block:: shell
1313
14-
-Djavax.net.ssl.keyStoreType=pkcs12
15-
-Djavax.net.ssl.keyStore=<path to pkcs12 KeyStore containing your client certificate>
16-
-Djavax.net.ssl.keyStorePassword=<KeyStore password>
14+
-Djavax.net.ssl.keyStoreType=pkcs12
15+
-Djavax.net.ssl.keyStore=<path to pkcs12 KeyStore containing your client certificate>
16+
-Djavax.net.ssl.keyStorePassword=<KeyStore password>
1717
18-
.. note:: Configure Client With SSLContext
18+
.. note:: Configure Client With SSLContext
1919

20-
If you would rather configure your client application using an SSL context, use the
21-
`kmsProviderSslContextMap <{+java-driver-api+}/mongodb-driver-core/com/mongodb/ClientEncryptionSettings.Builder.html#kmsProviderSslContextMap(java.util.Map)>`__
22-
method.
20+
If you would rather configure your client application using an SSL context, use the
21+
`kmsProviderSslContextMap <{+java-driver-api+}/mongodb-driver-core/com/mongodb/ClientEncryptionSettings.Builder.html#kmsProviderSslContextMap(java.util.Map)>`__
22+
method.
23+
24+
.. tab::
25+
:tabid: nodejs
26+
27+
.. literalinclude:: /includes/generated/in-use-encryption/csfle/node/kmip/reader/make_data_key.js
28+
:start-after: start-create-tls
29+
:end-before: end-create-tls
30+
:language: javascript
31+
:dedent:
32+
:caption: make_data_key.js
33+
34+
.. tab::
35+
:tabid: python
36+
37+
.. literalinclude:: /includes/generated/in-use-encryption/csfle/python/kmip/reader/make_data_key.py
38+
:start-after: start-create-tls
39+
:end-before: end-create-tls
40+
:language: python
41+
:dedent:
42+
:caption: make_data_key.py
43+
44+
.. tab::
45+
:tabid: csharp
46+
47+
.. literalinclude:: /includes/generated/in-use-encryption/csfle/dotnet/kmip/reader/CSFLE/MakeDataKey.cs
48+
:start-after: start-create-tls
49+
:end-before: end-create-tls
50+
:language: csharp
51+
:dedent:
52+
:caption: MakeDataKey.cs
53+
54+
.. important::
55+
56+
Your client certificate must be in pcks12 format. You can convert
57+
your certificate using openssl with the following command:
58+
59+
.. code-block:: shell
60+
61+
openssl pcks12 -export -out "<new pcks12 certificate>" -in "<certificate to convert>" \
62+
-name "<new certificate name>" -password "<new certificate password>"
63+
64+
.. tab::
65+
:tabid: go
66+
67+
.. literalinclude:: /includes/generated/in-use-encryption/csfle/go/kmip/reader/make-data-key.go
68+
:start-after: start-create-tls
69+
:end-before: end-create-tls
70+
:language: go
71+
:dedent:
72+
:caption: make-data-key.go
73+
74+
.. important::
75+
76+
You must use certificates with `ECDSA keys <https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm>`__
77+
when using the Go driver with PyKMIP.
78+

0 commit comments

Comments
 (0)