Skip to content

DOCSP-13723,DOCS-14308 clarify csfle support and mongocrpytd startup #5201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 13, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 20 additions & 18 deletions source/core/security-automatic-client-side-encryption.txt
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,10 @@ Automatic Client-Side Field Level Encryption
Overview
--------

Official MongoDB 4.2-compatible drivers and the MongoDB 4.2
Official MongoDB 4.2+ compatible drivers and the MongoDB 4.2 or later
:binary:`~bin.mongo` shell support automatically encrypting fields in
read and write operations. For a complete list of official
4.2-compatible drivers with support for client-side field level
4.2+ compatible drivers with support for client-side field level
encryption, see :ref:`field-level-encryption-drivers`.

Applications must create a database connection object (e.g.
Expand All @@ -33,10 +33,11 @@ code associated with constructing the read/write operation. See
:ref:`field-level-encryption-json-schema` for complete documentation on
automatic encryption rules.

The official MongoDB 4.2-compatible drivers and 4.2 :binary:`~bin.mongo`
shell use the Enterprise-only :ref:`field-level-encryption-mongocryptd`
process to parse the automatic encryption rules and apply the encryption
rules when reading or writing documents:
The official MongoDB 4.2+ compatible drivers and 4.2 or later
:binary:`~bin.mongo` shell use the Enterprise-only
:ref:`field-level-encryption-mongocryptd` process to parse the automatic
encryption rules and apply the encryption rules when reading or writing
documents:

- For write operations, the driver/shell encrypts field values *prior*
to writing to the MongoDB database.
Expand All @@ -53,9 +54,9 @@ rules when reading or writing documents:
Enabling Automatic Client-Side Field Level Encryption
-----------------------------------------------------

Each official MongoDB 4.2-compatible driver introduces new functionality
for supporting automatic encryption and data encryption key management.
Defer to your preferred :ref:`driver's documentation
Each official MongoDB 4.2+ compatible driver introduces new
functionality for supporting automatic encryption and data encryption
key management. Defer to your preferred :ref:`driver's documentation
<field-level-encryption-drivers>` for language-specific instructions on
implementing automatic client-side field level encryption.

Expand All @@ -68,9 +69,9 @@ For a complete example, see
Automatic client-side field level encryption requires access to the
:ref:`mongocryptd` process on the client host machine. See
:ref:`mongocryptd` for complete documentation on installation. The
official MongoDB 4.2-compatible drivers have additional options for
managing the ``mongocryptd`` process. Generally, the 4.2-compatible
drivers and 4.2 :binary:`~bin.mongo` shell can access the
official MongoDB 4.2+ compatible drivers have additional options for
managing the ``mongocryptd`` process. Generally, the 4.2+ compatible
drivers and 4.2 or later :binary:`~bin.mongo` shell can access the
``mongocryptd`` process if it is in the system ``PATH``.

Applications must specify the following components when instantiating
Expand All @@ -87,9 +88,9 @@ encryption:
specified CMK *prior* to storing them in the key vault, leaving only
metadata unencrypted.

4.2-compatible drivers and the 4.2 :binary:`~bin.mongo` shell need
access to the KMS to encrypt and decrypt protected fields *or* to
create new data encryption keys.
4.2+ compatible drivers and the 4.2 or later :binary:`~bin.mongo`
shell need access to the KMS to encrypt and decrypt protected fields
*or* to create new data encryption keys.

- Per-field automatic encryption rules using
:ref:`JSON schema syntax <field-level-encryption-json-schema>`.
Expand All @@ -99,9 +100,10 @@ encryption:
Server-Side Field Level Encryption Enforcement
----------------------------------------------

The MongoDB 4.2 server supports using :doc:`schema validation
</core/schema-validation>` to enforce encryption of specific fields in a
collection. Clients performing :ref:`automatic client-side field level
Starting in MongoDB 4.2, the server supports using
:doc:`schema validation </core/schema-validation>` to enforce encryption
of specific fields in a collection. Clients performing
:ref:`automatic client-side field level
encryption <field-level-encryption-json-schema>` have specific behavior
depending on the :ref:`database connection configuration
<mongo-connection-automatic-client-side-encryption-enabled>`:
Expand Down
57 changes: 30 additions & 27 deletions source/core/security-client-side-encryption.txt
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Client-Side Field Level Encryption

.. versionadded:: 4.2

The :ref:`official MongoDB 4.2-compatible drivers
The :ref:`official MongoDB 4.2+ compatible drivers
<field-level-encryption-drivers>` provide a client-side field level
encryption framework. Applications can encrypt fields in documents
*prior* to transmitting data over the wire to the server. Only
Expand Down Expand Up @@ -82,24 +82,24 @@ and ``phone``. Encrypted fields are stored as
"ssn" : BinData(6,"AaloEw285E3AnfjP+r8ph2YCvMI1+rWzpZK97tV6iz0jx")
}

For a complete list of official 4.2-compatible drivers with support
For a complete list of official 4.2+ compatible drivers with support
for client-side field level encryption, see
:ref:`field-level-encryption-drivers`.

For an end-to-end procedure for configuring field level encryption using
select MongoDB 4.2-compatible drivers, see the
:ecosystem:`Client Side Field Level Encryption Guide
</use-cases/client-side-field-level-encryption-guide/>`.
select MongoDB 4.2+ compatible drivers, see the
:driver:`Client Side Field Level Encryption Guide
</security/client-side-field-level-encryption-guide>`.

Supported Encryption Methods
----------------------------

MongoDB supports two methods of client-side field level encryption using
the official MongoDB 4.2-compatible drivers:
the official MongoDB 4.2+ compatible drivers:

Explicit (manual) encryption of fields
Official :ref:`MongoDB 4.2-compatible drivers
<field-level-encryption-drivers>` and the MongoDB 4.2
Official :ref:`MongoDB 4.2+ compatible drivers
<field-level-encryption-drivers>` and the MongoDB 4.2 or later
:binary:`~bin.mongo` shell support explicitly encrypting or decrypting
fields with a specific data encryption key and encryption algorithm.

Expand All @@ -115,8 +115,8 @@ Explicit (manual) encryption of fields
Automatic encryption of fields
.. include:: /includes/extracts/csfle-enterprise-atlas-only.rst

Official :ref:`MongoDB 4.2-compatible drivers
<field-level-encryption-drivers>` and the MongoDB 4.2
Official :ref:`MongoDB 4.2+ compatible drivers
<field-level-encryption-drivers>` and the MongoDB 4.2 or later
:binary:`~bin.mongo` shell support automatically encrypting fields in
read and write operations.

Expand All @@ -133,10 +133,11 @@ Automatic encryption of fields
For more information, see
:doc:`/core/security-automatic-client-side-encryption`.

MongoDB 4.2-compatible drivers and the 4.2 :binary:`~bin.mongo` shell
automatically decrypt :bsontype:`Binary` subtype 6 objects created using
client-side field level encryption. For more information on automatic
decryption, see :ref:`field-level-encryption-automatic-decryption`.
MongoDB 4.2+ compatible drivers and the 4.2 or later
:binary:`~bin.mongo` shell automatically decrypt :bsontype:`Binary`
subtype 6 objects created using client-side field level encryption. For
more information on automatic decryption, see
:ref:`field-level-encryption-automatic-decryption`.

.. important::

Expand All @@ -158,11 +159,11 @@ driver and each encryption component:

- ``libmongocrypt`` is the `Apache-licensed open-source
<https://github.com/mongodb/libmongocrypt>`__ core cryptography
library used by the official MongoDB 4.2-compatible drivers and the
:binary:`~bin.mongo` shell for powering client-side field level
encryption. Some drivers may require specific integration steps to
install or link the library. Defer to driver documentation for more
complete information.
library used by the official MongoDB 4.2+ compatible drivers and the
MongoDB 4.2 or later :binary:`~bin.mongo` shell for powering
client-side field level encryption. Some drivers may require specific
integration steps to install or link the library. Defer to driver
documentation for more complete information.

- :ref:`mongocryptd` supports :ref:`field-level-encryption-automatic`
and is only available with MongoDB Enterprise. ``mongocryptd`` does
Expand Down Expand Up @@ -251,9 +252,10 @@ Automatic Field Decryption

The :bsontype:`BinData <Binary>` blob metadata includes the data
encryption key ``_id`` and encryption algorithm used to encrypt the
binary data. The 4.2-compatible drivers and 4.2 :binary:`~bin.mongo`
shell use this metadata to attempt automatic decryption ``BinData`` type
6 values. The automatic decryption process works as follows:
binary data. The 4.2+ compatible drivers and 4.2 or later
:binary:`~bin.mongo` shell use this metadata to attempt automatic
decryption of :bsontype:`BinData <Binary>` subtype 6 objects. The
automatic decryption process works as follows:

1. Check the :bsontype:`BinData <Binary>` blob metadata for the
data encryption key and encryption algorithm used to encrypt the
Expand Down Expand Up @@ -294,9 +296,10 @@ client construction method.
Enforce Field Level Encryption Schema
-------------------------------------

The MongoDB 4.2 server supports using :doc:`schema validation
</core/schema-validation>` to enforce encryption of specific fields in a
collection. Use the :ref:`automatic encryption rule keywords
Starting with MongoDB 4.2, the server supports using
:doc:`schema validation </core/schema-validation>` to enforce encryption
of specific fields in a collection. Use the
:ref:`automatic encryption rule keywords
<field-level-encryption-json-schema>` with the
:query:`$jsonSchema` validation object to indicate which fields require
encryption. The server rejects any write operations to that collection
Expand Down Expand Up @@ -359,7 +362,7 @@ on the :ref:`database connection configuration
.. container::

*Automatic client-side field level encryption is available with
MongoDB 4.2 Enterprise only.*
MongoDB Enterprise 4.2 or later only.*

- If the connection :ref:`ClientSideFieldLevelEncryptionOptions`
``schemaMap`` object contains a key for the specified collection, the
Expand Down Expand Up @@ -403,7 +406,7 @@ Driver Compatibility Table
--------------------------

MongoDB 4.2 client-side field level encryption is only available with
the following official 4.2-compatible driver versions:
the following official 4.2+ compatible driver versions:

.. list-table::
:widths: 20 20 60
Expand Down
31 changes: 16 additions & 15 deletions source/core/security-explicit-client-side-encryption.txt
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ Explicit (Manual) Client-Side Field Level Encryption
Overview
--------

MongoDB 4.2-compatible drivers and the 4.2 :binary:`~bin.mongo` shell
support explicitly encrypting or decrypting fields with a specific
data encryption key and encryption algorithm.
MongoDB 4.2+ compatible drivers and the 4.2 or later
:binary:`~bin.mongo` shell support explicitly encrypting or decrypting
fields with a specific data encryption key and encryption algorithm.

Applications must modify any code associated with constructing read and
write operations to include encryption/decryption logic via the driver
Expand All @@ -30,10 +30,10 @@ performing explicit encryption and decryption:
- :method:`ClientEncryption.encrypt()`
- :method:`ClientEncryption.decrypt()`

MongoDB 4.2-compatible drivers have specific syntax for performing
MongoDB 4.2+ compatible drivers have specific syntax for performing
explicit client-side field level encryption. See
:ref:`field-level-encryption-drivers` for a complete list of
4.2-compatible drivers with support for client-side field
4.2+ compatible drivers with support for client-side field
level encryption. Defer to the documentation for your preferred
driver for specific instructions on performing client-side field
level encryption.
Expand Down Expand Up @@ -85,14 +85,15 @@ to protect those values.
Enabling Explicit Client-Side Field Level Encryption
----------------------------------------------------

Each official MongoDB 4.2-compatible driver introduces new functionality
for supporting client-side field level encryption and data encryption
key management. Defer to your preferred :ref:`driver's documentation
<field-level-encryption-drivers>` for language-specific instructions on
implementing explicit client-side field level encryption.
Each official MongoDB 4.2+ compatible driver introduces new
functionality for supporting client-side field level encryption and data
encryption key management. Defer to your preferred
:ref:`driver's documentation <field-level-encryption-drivers>` for
language-specific instructions on implementing explicit client-side
field level encryption.

The MongoDB 4.2 :binary:`~bin.mongo` shell adds an additional option
to the :method:`Mongo()` method for instantiating a database
The MongoDB 4.2 or later :binary:`~bin.mongo` shell adds an additional
option to the :method:`Mongo()` method for instantiating a database
connection with explicit client-side field level encryption.
For a complete example, see
:ref:`mongo-connection-client-side-encryption-enabled`.
Expand All @@ -111,9 +112,9 @@ encryption:
specified CMK *prior* to storing them in the key vault, leaving only
metadata unencrypted.

4.2-compatible drivers and the 4.2 :binary:`~bin.mongo` shell need
access to the KMS to encrypt and decrypt protected fields *or* to
create new data encryption keys.
4.2+ compatible drivers and the 4.2 or later :binary:`~bin.mongo`
shell need access to the KMS to encrypt and decrypt protected fields
*or* to create new data encryption keys.

Server-Side Field Level Encryption Enforcement
----------------------------------------------
Expand Down
10 changes: 5 additions & 5 deletions source/includes/extracts-4.2-changes.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -636,8 +636,8 @@ content: |
* - :binary:`~bin.mongodump`

- Use Extended JSON v2.0 (Canonical mode) format for the
metadata. Requires :binary:`~bin.mongorestore` version 4.2+
that supports Extended JSON v2.0 (Canonical mode or
metadata. Requires :binary:`~bin.mongorestore` version 4.2 or
later that supports Extended JSON v2.0 (Canonical mode or
Relaxed) format.

.. tip::
Expand Down Expand Up @@ -714,10 +714,10 @@ content: |
the correct default state of :urioption:`retryWrites` for your
specific driver and version.

The official MongoDB 4.2-compatible drivers enable :ref:`retryable-writes` by
default. Applications upgrading to the 4.2-compatible drivers that require
The official MongoDB 4.2+ compatible drivers enable :ref:`retryable-writes` by
default. Applications upgrading to the 4.2+ compatible drivers that require
retryable writes may omit the :urioption:`retryWrites=true <retryWrites>`
option. Applications upgrading to the 4.2-compatible drivers that require
option. Applications upgrading to the 4.2+ compatible drivers that require
*disabling* retryable writes must include
:urioption:`retryWrites=false <retryWrites>` in the connection string.
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,8 @@ content: |
.. admonition:: Enterprise Feature

The automatic feature of field level encryption is only available
in MongoDB 4.2 Enterprise and MongoDB Atlas 4.2 clusters.
in MongoDB Enterprise 4.2 or later, and MongoDB Atlas 4.2 or later
clusters.
---
ref: csfle-aws-kms-4.2.0-4.2.1-broken
content: |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ can detect the loss of the primary and automatically
:ref:`retry certain write operations <retryable-writes>` a single time,
providing additional built-in handling of automatic failovers and elections:

- MongoDB 4.2-compatible drivers enable retryable writes by default
- MongoDB 4.2+ compatible drivers enable retryable writes by default

- MongoDB 4.0 and 3.6-compatible drivers must explicitly enable
retryable writes by including :urioption:`retryWrites=true <retryWrites>` in the :ref:`connection string <mongodb-uri>`.
6 changes: 3 additions & 3 deletions source/reference/connection-string.txt
Original file line number Diff line number Diff line change
Expand Up @@ -334,8 +334,8 @@ Connection options are pairs in the following form: ``name=value``.

- The option ``name`` is case insensitive when using a driver.

- The option ``name`` is case insensitive when using a version 4.2+
:binary:`~bin.mongo` shell.
- The option ``name`` is case insensitive when using a version 4.2 or
later :binary:`~bin.mongo` shell.

- The option ``name`` is case sensitive when using a version 4.0 and
earlier :binary:`~bin.mongo` shell.
Expand Down Expand Up @@ -1190,7 +1190,7 @@ Miscellaneous Configuration

- ``true``. Enables retryable writes for the connection.

Official MongoDB 4.2-compatible drivers default to ``true``.
Official MongoDB 4.2+ compatible drivers default to ``true``.

- ``false``. Disables retryable writes for the connection.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ Client-Side Field Level Encryption Methods

The following methods are for the MongoDB :binary:`~bin.mongo` shell
*only*. For instructions on implementing client-side field level
encryption using a MongoDB 4.2-compatible driver, defer to the
encryption using a MongoDB 4.2+ compatible driver, defer to the
driver documentation. See :ref:`field-level-encryption-drivers` for
a complete list of 4.2-compatible drivers with support for
a complete list of 4.2+ compatible drivers with support for
client-side field level encryption.

.. list-table::
Expand Down
Loading