Skip to content

Commit 434eb62

Browse files
norareidynorareidy
committed
DOCSP-42150: CSFLE standardization (#102)
* DOCSP-42150: CSFLE standardization * edits * code * edits * edits * fix build errors * SA feedback * remove * KA feedback * link * KA feedback 2 (cherry picked from commit f8fbbf5) (cherry picked from commit 43afbb1)
1 parent 941e5e2 commit 434eb62

File tree

5 files changed

+178
-167
lines changed

5 files changed

+178
-167
lines changed

‎config/redirects

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ raw: /docs/languages/cxx -> /docs/languages/cpp
2727

2828
(v3.10-master]: ${prefix}/${version}/installation/ -> ${base}/${version}/get-started/
2929
(v3.10-master]: ${prefix}/${version}/configuration/ -> ${base}/${version}/security/
30-
(v3.10-master]: ${prefix}/${version}/client-side-encryption/ -> ${base}/${version}/security/client-side-encryption/
30+
(v3.10-master]: ${prefix}/${version}/client-side-encryption/ -> ${base}/${version}/security/in-use-encryption/
3131
(v3.10-master]: ${prefix}/${version}/tutorial/ -> ${base}/${version}/
3232
(v3.10-master]: ${prefix}/${version}/connection-pools/ -> ${base}/${version}/connect/connection-pools/
3333
(v3.10-master]: ${prefix}/${version}/working-with-bson/ -> ${base}/${version}/data-formats/working-with-bson/

‎source/includes/csfle.cpp

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// start-auto-encrypt
2+
auto mongocryptd_options = make_document(kvp("mongocryptdBypassSpawn", true));
3+
4+
options::auto_encryption auto_encrypt_opts{};
5+
auto_encrypt_opts.extra_options({mongocryptd_options.view()});
6+
7+
options::client client_opts;
8+
client_opts.auto_encryption_opts(std::move(auto_encrypt_opts));
9+
10+
// Create and use your client here
11+
// end-auto-encrypt
12+
13+
// start-json-schema
14+
auto data_key_id = client_encryption.create_data_key("local");
15+
auto json_schema = document{} << "properties" << open_document << "encryptedFieldName" << open_document << "encrypt"
16+
<< open_document << "keyId" << open_array << data_key_id << close_array << "bsonType"
17+
<< "string"
18+
<< "algorithm"
19+
<< "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" << close_document << close_document
20+
<< close_document << "bsonType"
21+
<< "object" << finalize;
22+
// end-json-schema
23+
24+
// start-explicit-encrypt
25+
// Configure your MongoDB client's encryption options here
26+
27+
class client_encryption client_encryption(std::move(client_encryption_opts));
28+
29+
auto data_key_id = client_encryption.create_data_key("local");
30+
options::encrypt encrypt_opts{};
31+
encrypt_opts.key_id(data_key_id.view());
32+
encrypt_opts.algorithm(options::encrypt::encryption_algorithm::k_deterministic);
33+
34+
// Explicitly encrypts a BSON value
35+
auto to_encrypt = bsoncxx::types::bson_value::make_value("secret message");
36+
auto encrypted_message = client_encryption.encrypt(to_encrypt, encrypt_opts);
37+
38+
// Explicitly decrypts a BSON value
39+
auto decrypted_message = client_encryption.decrypt(encrypted_message);
40+
41+
// Inserts the encrypted value into the database
42+
coll.insert_one(make_document(kvp("encryptedField", encrypted_message)));
43+
// end-explicit-encrypt
44+
45+
// start-auto-decrypt
46+
options::auto_encryption auto_encrypt_opts{};
47+
auto_encrypt_opts.bypass_auto_encryption(true);
48+
49+
options::client client_opts{};
50+
client_opts.auto_encryption_opts(std::move(auto_encrypt_opts));
51+
class client client_encrypted {uri{}, std::move(client_opts)};
52+
// end-auto-decrypt

‎source/security.txt

-1
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ Secure Your Data
2525
Authentication </security/authentication>
2626
Enterprise Authentication </security/enterprise-authentication>
2727
In-Use Encryption </security/in-use-encryption>
28-
Client-Side Encryption </security/client-side-encryption>
2928

3029
Overview
3130
--------

‎source/security/client-side-encryption.txt

-162
This file was deleted.

‎source/security/in-use-encryption.txt

+125-3
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ In-Use Encryption
77
.. contents:: On this page
88
:local:
99
:backlinks: none
10-
:depth: 1
10+
:depth: 2
1111
:class: singlecol
1212

1313
.. facet::
@@ -97,5 +97,127 @@ low cardinality is susceptible to code breaking by frequency analysis.
9797
- :wikipedia:`Cardinality <w/index.php?title=Cardinality_(data_modeling)&oldid=1182661589>`
9898
- :wikipedia:`Frequency Analysis <w/index.php?title=Frequency_analysis&oldid=1182536787>`
9999

100-
To learn more about CSFLE, see the :ref:`cpp-client-side-encryption` guide and
101-
:manual:`CSFLE </core/csfle/>` in the Server manual.
100+
This section shows how to configure CSFLE by using the following
101+
mechanisms:
102+
103+
- :ref:`Automatic Encryption <cpp-csfle-automatic>`
104+
- :ref:`Explicit Encryption <cpp-csfle-explicit>`
105+
106+
.. _cpp-csfle-automatic:
107+
108+
Configure Automatic Encryption
109+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
110+
111+
Automatic encryption allows you to perform encrypted read and write operations
112+
without specifying how to encrypt fields. To enable automatic encryption, use
113+
one of the following:
114+
115+
- ``crypt_shared`` *(Recommended)*: A dynamic library that reads the encryption schema
116+
to determine which fields to encrypt and decrypt. When using this library, you do not
117+
need to spawn a separate process to perform automatic encryption.
118+
119+
- ``mongocryptd``: A binary pre-packaged with MongoDB Enterprise Server that uses
120+
specified automatic encryption rules to mark fields for encryption. ``mongocryptd``
121+
spawns automatically when you create a CSFLE-enabled client, but you can explicitly start
122+
the binary in an ``options::auto_encryption`` instance.
123+
124+
.. important::
125+
126+
``mongocryptd`` requires MongoDB Enterprise Server v4.2 or later.
127+
128+
To learn more about configuring automatic encryption, see
129+
:manual:`Install and Configure a CSFLE Library </core/csfle/reference/install-library/>`
130+
in the {+mdb-server+} manual.
131+
132+
Set an Encryption Schema
133+
````````````````````````
134+
135+
You can use the ``schema_map`` option to specify an automatic encryption schema.
136+
Encryption schemas contain user-specified rules that identify which
137+
fields must be encrypted and how to encrypt those fields.
138+
139+
Set the ``schema_map`` option to a JSON document that aligns
140+
with the `JSON Schema Draft 4 <https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04>`__
141+
standard syntax. This document must include the field names to encrypt
142+
and a nested ``encrypt`` object under each field name, which sets the
143+
encryption options to use.
144+
145+
.. tip::
146+
147+
To learn more about encryption schemas, see
148+
:manual:`CSFLE Encryption Schemas </core/csfle/reference/encryption-schemas/>`
149+
in the {+mdb-server+} manual.
150+
151+
The following code shows the syntax for specifying a JSON schema document:
152+
153+
.. literalinclude:: /includes/csfle.cpp
154+
:language: cpp
155+
:copyable: true
156+
:start-after: // start-json-schema
157+
:end-before: // end-json-schema
158+
159+
To view a full example that uses the preceding ``json_schema`` document to
160+
configure an automatic encryption schema, see the :github:`Automatic CSFLE
161+
<mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/automatic_client_side_field_level_encryption.cpp>`
162+
example in the driver source code.
163+
164+
.. tip::
165+
166+
You can also specify an automatic encryption schema for
167+
server-side field level encryption. To view a full example,
168+
see the :github:`Server-Side Field Level Encryption Enforcement <mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/server_side_field_level_encryption_enforcement.cpp>`
169+
example in the driver source code.
170+
171+
.. _cpp-csfle-explicit:
172+
173+
Configure Explicit Encryption
174+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175+
176+
Explicit encryption allows you to perform encrypted operations
177+
by using the driver's encryption library. To use explicit encryption,
178+
you must specify the encryption logic throughout your application.
179+
180+
The following example configures explicit encryption
181+
for an insert operation, which inserts an encrypted message
182+
into the database:
183+
184+
.. literalinclude:: /includes/csfle.cpp
185+
:language: cpp
186+
:copyable: true
187+
:start-after: // start-explicit-encrypt
188+
:end-before: // end-explicit-encrypt
189+
190+
To view a full example that configures explicit encryption,
191+
see the :github:`Explicit Encryption <mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/explicit_encryption.cpp>`
192+
example in the driver source code.
193+
194+
Explicit Encryption with Automatic Decryption
195+
`````````````````````````````````````````````
196+
197+
You can configure explicit encryption and automatic decryption,
198+
which is supported for all users. To configure automatic decryption
199+
without automatic encryption, create an ``options::auto_encryption``
200+
instance and set its ``bypass_auto_encryption`` field to ``true``.
201+
Then, apply these options to your client.
202+
203+
The following example creates an ``options::auto_encryption`` instance
204+
to configure explicit encryption with automatic decryption,
205+
then passes this options instance to the ``auto_encryption_opts`` field
206+
of an ``options::client``. This creates a client configured to
207+
use automatic decryption:
208+
209+
.. literalinclude:: /includes/csfle.cpp
210+
:language: cpp
211+
:copyable: true
212+
:start-after: // start-auto-decrypt
213+
:end-before: // end-auto-decrypt
214+
215+
To view a full example that configures explicit encryption
216+
with automatic decryption, see the :github:`Explicit Encryption Auto Decryption
217+
<mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/explicit_encryption_auto_decryption.cpp>`
218+
example in the driver source code.
219+
220+
Additional Information
221+
----------------------
222+
223+
To learn more about CSFLE, see :manual:`CSFLE </core/csfle/>` in the {+mdb-server+} manual.

0 commit comments

Comments
 (0)