Skip to content

Commit 3e5c439

Browse files
rachel-mackrachel-mack
authored
[C++] Content formatting (#4)
* add content
1 parent e83b6bc commit 3e5c439

22 files changed

+3026
-7
lines changed

‎snooty.toml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ intersphinx = [
88
]
99

1010
toc_landing_pages = [
11-
"/installation",
12-
"/contributing"
11+
"/installation"
1312
]
1413

1514
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -19,4 +18,5 @@ driver = "cpp"
1918
driver-long = "MongoDB C++ Driver"
2019
driver-short = "C++ driver"
2120
version = "3.10"
21+
full-version = "{+version+}.0"
2222
api = "https://mongocxx.org/api/current"

‎source/api-abi-versioning.txt

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
.. _cpp-api-abi-versioning:
2+
3+
======================
4+
API and ABI Versioning
5+
======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
API Versioning
18+
--------------
19+
20+
- We use `semantic versioning <http://semver.org/>`__.
21+
- bsoncxx and mongocxx both define corresponding CMake variables for MAJOR, MINOR, and PATCH.
22+
23+
ABI Versioning
24+
--------------
25+
26+
- Both bsoncxx and mongocxx both have a single scalar ABI version.
27+
- Only bump ABI version on **incompatible** ABI change (not for ABI additions).
28+
- **We stay on ABI version \_noabi (without bumping for incompatible changes) until ABI is stable.**
29+
30+
Parallel Header Installation
31+
----------------------------
32+
33+
- For mongocxx, install all headers to ``$PREFIX/mongocxx/v$ABI/``.
34+
- For bsoncxx, install all headers to ``$PREFIX/bsoncxx/v$ABI/``.
35+
- We install a pkg-config file to shield consumers from this complexity.
36+
37+
Sonames and Symlinks
38+
--------------------
39+
40+
.. note::
41+
42+
- Below examples are given for libmongocxx, but also apply to libbsoncxx
43+
44+
- DSO refers to Dynamic Shared Object, to use Ulrich Drepper’s terminology
45+
46+
Windows (MSVC only)
47+
~~~~~~~~~~~~~~~~~~~
48+
49+
Since version 3.10.0, the physical filename for CXX Driver libraries is different
50+
from other platforms when built with the MSVC toolchain on Windows
51+
(even when the CMake generator is not Visual Studio).
52+
To restore prior behavior, which is similar to other platforms, set ``ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFF``.
53+
54+
- Physical filename for a DSO is ``mongocxx-$ABI-$TAG.dll``
55+
- Physical filename for a static library is ``mongocxx-static-$TAG.lib``
56+
57+
Where ``$TAG`` is a triplet of letters indicating:
58+
59+
- Build Type
60+
- mongoc Link Type
61+
- Polyfill Library
62+
63+
This is followed by a suffix describing the toolset and runtime library used to build the library.
64+
65+
Some examples of common DSO filenames expected to be generated include:
66+
67+
- ``mongocxx-v_noabi-rhs-x64-v142-md.dll`` (release build configuration)
68+
- ``mongocxx-v_noabi-dhs-x64-v142-mdd.dll`` (debug build configuration)
69+
- ``mongocxx-v_noabi-rts-x64-v142-md.dll`` (link with mongoc statically)
70+
- ``mongocxx-v_noabi-rhi-x64-v142-md.dll`` (bsoncxx polyfill library)
71+
- ``mongocxx-v_noabi-rhm-x64-v142-md.dll`` (mnmlstc/core polyfill library)
72+
- ``mongocxx-v_noabi-rhb-x64-v142-md.dll`` (Boost polyfill library)
73+
74+
This allows libraries built with different build configurations (and different runtime library requirements) to be built and installed without conflicting with each other.
75+
76+
See references to ``ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES`` and related code in the CMake configuration for more details.
77+
78+
Other Platforms (Linux, MacOS)
79+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80+
81+
- Physical filename for a DSO is ``libmongocxx.so.$MAJOR.$MINOR.$PATCH``
82+
83+
.. note::
84+
85+
The physical filename is disconnected from ABI version/soname. This looks a bit strange, but allows multiple versions of the library with the same ABI version to be installed on the same system.
86+
87+
- soname for a DSO is ``libmongocxx.$ABI``
88+
89+
We provide a soname symlink that links to the physical DSO. We also
90+
provide a dev symlink that links to the soname symlink of the highest ABI
91+
version of the library installed.
92+
93+
Inline Namespaces
94+
-----------------
95+
96+
- We provide inline namespace macros for both mongocxx and bsoncxx.
97+
- This allows multiple, ABI incompatible versions of the library to be linked into the same application.
98+
- The name of the namespace is ``v$ABI``. We create them from ABI version to maintain forwards compatibibility.
99+
100+
Deprecation
101+
-----------
102+
103+
Occasionally we will phase features out of use in the driver.
104+
In the release that marks a feature as deprecated we offer several transition options:
105+
106+
1. The original method, marked with ``MONGOCXX_DEPRECATED``. This will raise deprecation warnings when compiled.
107+
#. A variant of the feature suffixed with ``_deprecated``. This will require
108+
only small code changes and will not raise deprecation warnings.
109+
#. A new feature that provides alternate functionality. The new feature may not
110+
be a drop-in replacement for the deprecated feature and switching to it may
111+
require code changes. In the rare case where we remove a feature without replacing it, this third option will not be available.
112+
113+
In the following release, the original feature marked with ``MONGOCXX_DEPRECATED`` and its
114+
suffixed ``_deprecated`` equivalent will be removed.
115+
116+
.. code-block:: cpp
117+
118+
// release 1 with a supported feature
119+
void do_thing();
120+
121+
// release 2 where the feature is deprecated in favor of a new feature
122+
MONGOCXX_DEPRECATED void do_thing();
123+
void do_thing_deprecated();
124+
void do_new_thing();
125+
126+
// release 3 where the original feature is removed
127+
void do_new_thing();
128+
129+
In the case of a feature rename we do not offer a suffixed ``_deprecated`` variant,
130+
as one can simply switch to using the new name with the same amount of effort.
131+
132+
.. code-block:: cpp
133+
134+
// release 1 with a supported feature
135+
void do_thing();
136+
137+
// release 2 where the feature name is renamed
138+
MONGOCXX_DEPRECATED void do_thing();
139+
void do_stuff();
140+
141+
// release 3 where the original feature name is removed
142+
void do_stuff();

‎source/client-side-encryption.txt

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
.. _cpp-client-side-encryption:
2+
3+
===================================
4+
Client-Side Field Level Encryption
5+
===================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
Client-Side Field Level Encryption
18+
----------------------------------
19+
20+
New in MongoDB 4.2 `Client-Side Field Level Encryption (CSFLE) <https://www.mongodb.com/docs/drivers/use-cases/client-side-field-level-encryption-guide>`__ allows administrators and developers to encrypt specific data fields in addition to other MongoDB encryption features.
21+
22+
With CSFLE, developers can encrypt fields client side without any server-side configuration or directives. Client-Side Field Level Encryption supports workloads where applications must guarantee that unauthorized parties, including server administrators, cannot read the encrypted data.
23+
24+
For an overview of CSFLE, please read :manual:`the official MongoDB documentation in the manual </core/security-client-side-encryption/>`.
25+
26+
Installation
27+
------------
28+
29+
``libmongocrypt``
30+
~~~~~~~~~~~~~~~~~
31+
32+
Client-Side Field Level Encryption relies on a C library called ``libmongocrypt`` to do the heavy lifting encryption work. This dependency is managed by the C driver. As long as the C driver installation is 1.16.0 or higher, and has been compiled with Client-Side Field Level Encryption support, this dependency should be managed internally. See the C driver's `Using Client-Side Field Level Encryption <https://mongoc.org/libmongoc/current/client-side-field-level-encryption.html>`__ for more information.
33+
34+
``mongocryptd``
35+
~~~~~~~~~~~~~~~
36+
37+
Automatic CSFLE relies upon a new binary called ``mongocryptd`` running as a daemon while the driver operates. This binary is only available with MongoDB Enterprise.
38+
39+
``mongocryptd`` can either be started separately from the driver, or left to spawn automatically when encryption is used.
40+
41+
To run mongocryptd separately, pass the ``mongocryptdBypassSpawn`` flag to the client's auto encryption options:
42+
43+
.. code-block:: cpp
44+
45+
auto mongocryptd_options = make_document(kvp("mongocryptdBypassSpawn", true));
46+
47+
options::auto_encryption auto_encrypt_opts{};
48+
auto_encrypt_opts.extra_options({mongocryptd_options.view()});
49+
50+
If the mongocryptd binary is on the current path, the driver will be able to spawn it without any custom flags. However, if the mongocryptd binary is on a different path, set the path with the ``mongocryptdSpawnPath`` option:
51+
52+
.. code-block:: cpp
53+
54+
auto mongocryptd_options = make_document(kvp("mongocryptdSpawnPath", "path/to/mongocryptd"));
55+
56+
options::auto_encryption auto_encrypt_opts{};
57+
auto_encrypt_opts.extra_options({mongocryptd_options.view()});
58+
59+
Examples
60+
--------
61+
62+
Automatic Client-Side Field Level Encryption
63+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64+
65+
Automatic Client-Side Field Level Encryption is enabled by creating a ``mongocxx::client`` with the ``auto_encryption_opts`` option set to an instance of ``mongocxx::options::auto_encryption``. The following examples show how to set up automatic client-side field level encryption using the ``mongocxx::client_encryption`` class to create a new encryption data key.
66+
67+
.. note::
68+
69+
Automatic client-side field level encryption requires MongoDB 4.2 enterprise or a MongoDB 4.2 Atlas cluster. The community version of the server supports automatic decryption as well as explicit client-side field level encryption.
70+
71+
Providing Local Automatic Encryption Rules
72+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73+
74+
The following example shows how to specify automatic encryption rules via the
75+
schema_map option. The automatic encryption rules are expressed using a `strict
76+
subset of the JSON Schema syntax
77+
<https://www.mongodb.com/docs/manual/reference/security-client-side-automatic-json-schema/>`__.
78+
79+
Supplying a ``schema_map`` provides more security than relying on JSON Schemas obtained from the server. It protects against a malicious server advertising a false JSON Schema, which could trick the client into sending unencrypted data that should be encrypted.
80+
81+
JSON Schemas supplied in the ``schema_map`` only apply to configuring automatic client-side field level encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.
82+
83+
.. code-block:: cpp
84+
85+
//
86+
// The schema map has the following form:
87+
//
88+
// {
89+
// "test.coll" : {
90+
// "bsonType" : "object",
91+
// "properties" : {
92+
// "encryptedFieldName" : {
93+
// "encrypt" : {
94+
// "keyId" : [ <datakey as UUID> ],
95+
// "bsonType" : "string",
96+
// "algorithm" : <algorithm>
97+
// }
98+
// }
99+
// }
100+
// }
101+
// }
102+
//
103+
104+
Please see `examples/mongocxx/automatic_client_side_field_level_encryption.cpp <https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/automatic_client_side_field_level_encryption.cpp>`__ for a full example of how to set a json schema for automatic encryption.
105+
106+
Server-Side Field Level Encryption Enforcement
107+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108+
109+
The MongoDB 4.2 server supports using schema validation to enforce encryption of specific fields in a collection. This schema validation will prevent an application from inserting unencrypted values for any fields marked with the ``"encrypt"`` JSON schema keyword.
110+
111+
It is possible to set up automatic client-side field level encryption using the ``mongocxx::client_encryption`` to create a new encryption data key and create a collection with the :manual:`Automatic Encryption JSON Schema Syntax </reference/security-client-side-automatic-json-schema/>`.
112+
113+
.. code-block:: cpp
114+
115+
// Please see the linked example below for full json_schema construction.
116+
bsoncxx::document::value json_schema{};
117+
118+
// Create the collection with the encryption JSON Schema.
119+
auto cmd = document{} << "create"
120+
<< "coll"
121+
<< "validator" << open_document
122+
<< "$jsonSchema" << json_schema.view()
123+
<< close_document << finalize;
124+
125+
db.run_command(cmd.view());
126+
127+
Please see `examples/mongocxx/server_side_field_level_encryption_enforcement.cpp <https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/server_side_field_level_encryption_enforcement.cpp>`__ for a full example of setting encryption enforcement on the server.
128+
129+
Explicit Encryption
130+
~~~~~~~~~~~~~~~~~~~
131+
132+
Explicit encryption is a MongoDB community feature and does not use the ``mongocryptd`` process. Explicit encryption is provided by the ``mongocxx::client_encryption`` class.
133+
134+
.. code-block:: cpp
135+
136+
// Explicitly encrypt a BSON value.
137+
auto to_encrypt = bsoncxx::types::bson_value::make_value("secret message");
138+
auto encrypted_message = client_encryption.encrypt(to_encrypt, encrypt_opts);
139+
140+
// Explicitly decrypt a BSON value.
141+
auto decrypted_message = client_encryption.decrypt(encrypted_message);
142+
143+
Please see `examples/mongocxx/explicit_encryption.cpp <https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/explicit_encryption.cpp>`__ for a full example of using explicit encryption and decryption.
144+
145+
Explicit Encryption with Automatic Decryption
146+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
147+
148+
Although automatic encryption requires MongoDB 4.2 enterprise or a MongoDB 4.2 Atlas cluster, automatic decryption is supported for all users. To configure automatic decryption without automatic encryption, set ``bypass_auto_encryption=True`` in the ``options::auto_encryption`` class.
149+
150+
.. code-block:: cpp
151+
152+
options::auto_encryption auto_encrypt_opts{};
153+
auto_encrypt_opts.bypass_auto_encryption(true);
154+
// Please see full example for complete options construction.
155+
156+
// Create a client with automatic decryption enabled, but automatic encryption bypassed.
157+
options::client client_opts{};
158+
client_opts.auto_encryption_opts(std::move(auto_encrypt_opts));
159+
class client client_encrypted {uri{}, std::move(client_opts)};
160+
161+
Please see `examples/mongocxx/explicit_encryption_auto_decryption.cpp <https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/explicit_encryption_auto_decryption.cpp>`__ for an example of using explicit encryption with automatic decryption.
162+

0 commit comments

Comments
 (0)