Skip to content

Commit b904e85

Browse files
author
Dave Cuthbert
authored
DOCSP-28987 BACKPORT (#3090)
1 parent fc602ac commit b904e85

File tree

10 files changed

+103
-50
lines changed

10 files changed

+103
-50
lines changed

source/core/csfle/fundamentals/manage-keys.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ Supported Key Management Services
6262
- Any KMIP Compliant {+kms-long+}
6363
- Local Key Provider *(for testing only)*
6464

65+
.. include:: /includes/reference/fact-kmip-version.rst
66+
6567
To learn more about these providers, including diagrams that show how
6668
your application uses them to perform {+csfle+}, see
6769
:ref:`csfle-reference-kms-providers`.

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,15 @@ Before You Get Started
7171
Set Up the KMS
7272
--------------
7373

74+
.. note::
75+
76+
``mongod`` reads the KMIP configuration at startup. By default, the
77+
server uses KMIP protocol version 1.2.
78+
79+
To connect to a version 1.0 or 1.1 KMIP server, use the
80+
:setting:`useLegacyProtocol <security.kmip.useLegacyProtocol>`
81+
setting.
82+
7483
.. include:: /includes/tutorials/language-id.rst
7584

7685
.. procedure::

source/core/security-encryption-at-rest.txt

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -111,13 +111,13 @@ transport encryption.
111111

112112
For details, see :ref:`rotate-encryption-keys`.
113113

114+
.. _security-encryption-at-rest-audit-log:
115+
114116
Audit Log
115117
~~~~~~~~~
116118

117119
Available in MongoDB Enterprise only.
118120

119-
.. _security-encryption-at-rest-audit-log:
120-
121121
Use KMIP Server to Manage Keys for Encrypting the MongoDB Audit Log
122122
```````````````````````````````````````````````````````````````````
123123

@@ -128,6 +128,8 @@ Interoperability Protocol (KMIP) server.
128128
KMIP simplifies the management of cryptographic keys and eliminates the
129129
use of non-standard key management processes.
130130

131+
.. include:: /includes/reference/fact-kmip-version.rst
132+
131133
To use a KMIP server with audit log encryption, configure these settings
132134
and parameters:
133135

@@ -165,10 +167,9 @@ information to log files as a part of normal operations, depending on
165167
the configured :ref:`log verbosity <log-messages-configure-verbosity>`.
166168

167169
Use the :setting:`security.redactClientLogData` setting to prevent
168-
potentially sensitive information from entering the
169-
:binary:`~bin.mongod` process log.
170-
:setting:`~security.redactClientLogData` reduces detail in the log and
171-
may complicate log diagnostics.
170+
potentially sensitive information from entering the ``mongod`` process
171+
log. Setting :setting:`~security.redactClientLogData` reduces detail in
172+
the log and may complicate log diagnostics.
172173

173174
See the :ref:`log redaction <monitoring-log-redaction>` manual entry for
174175
more information.
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
To connect to a version 1.0 or 1.1 KMIP server, use the
2+
:option:`--kmipUseLegacyProtocol <mongod --kmipUseLegacyProtocol>`
3+
option.
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
``mongod`` verifies the connection to the KMIP server on startup.
2+
3+
The server name specified in :option:`--kmipServerName
4+
<mongod --kmipServerName>` must match either the Subject Alternative
5+
Name ``SAN`` or the Common Name ``CN`` on the certificate presented by
6+
the KMIP server. ``SAN`` can be a system name or an IP address.
7+
8+
If ``SAN`` is present, ``mongod`` does not try to match against ``CN``.
9+
10+
If the hostname or IP address of the KMIP server does does not match
11+
either ``SAN`` or ``CN``, ``mongod`` does not start.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
When ``true``, ``mongod`` uses KMIP protocol version 1.0 or 1.1 instead
2+
of the default version. The default KMIP protocol is version 1.2.
3+
4+
To use :ref:`audit log encryption <security-encryption-at-rest-audit-log>`
5+
with KMIP version 1.0 or 1.1, you must specify
6+
:parameter:`auditEncryptKeyWithKMIPGet` at startup.
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
The default KMIP protocol version is 1.2. You can configure MongoDB to
2+
use KMIP version 1.0 or 1.1 in the MongoDB server :ref:`configuration
3+
file <configuration-options>`.

source/reference/configuration-options.txt

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2872,13 +2872,7 @@ Key Management Configuration Options
28722872
which it can successfully establish a connection. KMIP server
28732873
selection occurs only at startup.
28742874

2875-
When connecting to a KMIP server, the :binary:`~bin.mongod`
2876-
verifies that the specified :setting:`security.kmip.serverName`
2877-
matches the Subject Alternative Name ``SAN`` (or, if ``SAN`` is not
2878-
present, the Common Name ``CN``) in the certificate presented by the
2879-
KMIP server. If ``SAN`` is present, :binary:`~bin.mongod` does not
2880-
match against the ``CN``. If the hostname does not match the ``SAN``
2881-
(or ``CN``), the :binary:`~bin.mongod` will fail to connect.
2875+
.. include:: /includes/reference/fact-connection-check.rst
28822876

28832877
.. include:: /includes/extracts/4.2-changes-SAN-matching.rst
28842878

@@ -3053,6 +3047,29 @@ Key Management Configuration Options
30533047

30543048
To disable disable polling, set the value to ``-1``.
30553049

3050+
.. setting:: security.kmip.useLegacyProtocol
3051+
3052+
*Type*: boolean
3053+
3054+
*Default*: false
3055+
3056+
.. versionadded:: 7.0 (and 6.0.6)
3057+
3058+
.. include:: /includes/reference/fact-kmip-description.rst
3059+
3060+
To use KMIP protocol version 1.0 or 1.1, substitute your local values
3061+
and add an entry like this to your ``mongod`` configuration file:
3062+
3063+
.. code:: bash
3064+
:emphasize-lines: 7
3065+
3066+
security:
3067+
enableEncryption: true
3068+
kmip:
3069+
serverName: "mdbhost.somecompany.com"
3070+
serverCAFile: "security/libs/trusted-ca.pem"
3071+
clientCertificateFile: "security/libs/trusted-client.pem"
3072+
useLegacyProtocol: true
30563073

30573074
.. _security.sasl.options:
30583075

source/reference/program/mongod.txt

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3108,7 +3108,7 @@ Encryption Key Management Options
31083108
Requires :option:`--enableEncryption`.
31093109

31103110
.. include:: /includes/fact-enterprise-only-admonition.rst
3111-
3111+
31123112

31133113

31143114
.. option:: --kmipKeyIdentifier <string>
@@ -3314,10 +3314,19 @@ Encryption Key Management Options
33143314

33153315
.. versionadded:: 5.3
33163316

3317-
Frequency in seconds at which mongod polls the KMIP server for active keys.
3317+
Frequency in seconds at which ``mongod`` polls the KMIP server for
3318+
active keys.
33183319

33193320
To disable disable polling, set the value to ``-1``.
33203321

3322+
.. option:: --kmipUseLegacyProtocol <boolean>
3323+
3324+
*Default*: false
3325+
3326+
.. versionadded:: 7.0 (and 6.0.6)
3327+
3328+
.. include:: /includes/reference/fact-kmip-description.rst
3329+
33213330
.. option:: --eseDatabaseKeyRollover
33223331

33233332
.. versionadded:: 4.2

source/tutorial/configure-encryption.txt

Lines changed: 27 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,6 @@ stored in the key manager.
5252

5353
MongoDB Enterprise supports secure transfer of keys with Key Management
5454
Interoperability Protocol (KMIP) compliant key management appliances.
55-
Any appliance vendor that provides support for KMIP is expected
56-
to be compatible.
5755

5856
.. include:: /includes/partners-security.rst
5957

@@ -68,6 +66,8 @@ Prerequisites
6866

6967
- Your key manager must support the KMIP communication protocol.
7068

69+
.. include:: /includes/reference/fact-kmip-version.rst
70+
7171
- To authenticate MongoDB to a KMIP server, you must have a valid
7272
certificate issued by the key management appliance.
7373

@@ -80,34 +80,32 @@ Prerequisites
8080
Encrypt Using a New Key
8181
~~~~~~~~~~~~~~~~~~~~~~~
8282

83-
To create a new key, connect :binary:`~bin.mongod` to the key manager by starting
84-
:binary:`~bin.mongod` with the following options:
83+
To create a new key when you connect to the key manager, use the
84+
following options to start ``mongod``:
8585

8686
- :option:`--enableEncryption <mongod --enableEncryption>`
8787
- :option:`--kmipServerName <mongod --kmipServerName>`
8888
- :option:`--kmipPort <mongod --kmipPort>`
8989
- :option:`--kmipServerCAFile <mongod --kmipServerCAFile>`
9090
- :option:`--kmipClientCertificateFile <mongod --kmipClientCertificateFile>`
9191

92+
.. include:: /includes/reference/fact-add-v1-flag.rst
93+
9294
.. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst
9395

94-
The following operation creates a new master key in your key manager which
95-
:binary:`~bin.mongod` uses to encrypt the keys :binary:`~bin.mongod` generates
96-
for each database.
96+
The following operation creates a new master key in your key manager.
97+
``mongod`` uses the master key to encrypt the keys that ``mongod``
98+
generates for each database.
9799

98100
.. code-block:: bash
99101

100-
mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
101-
--kmipPort <KMIP server port> --kmipServerCAFile ca.pem \
102-
--kmipClientCertificateFile client.pem
102+
mongod --enableEncryption \
103+
--kmipServerName <KMIP Server HostName> \
104+
--kmipPort <KMIP server port> \
105+
--kmipServerCAFile ca.pem \
106+
--kmipClientCertificateFile client.pem
103107

104-
When connecting to the KMIP server, the :binary:`~bin.mongod` verifies
105-
that the specified :option:`--kmipServerName <mongod --kmipServerName>`
106-
matches the Subject Alternative Name ``SAN`` (or, if ``SAN`` is not
107-
present, the Common Name ``CN``) in the certificate presented by the
108-
KMIP server. [#san]_ If ``SAN`` is present, :binary:`~bin.mongod` does
109-
not match against the ``CN``. If the hostname does not match the
110-
``SAN`` (or ``CN``), the :binary:`~bin.mongod` will fail to connect.
108+
.. include:: /includes/reference/fact-connection-check.rst
111109

112110
To verify that the key creation and usage was successful, check the log
113111
file. If successful, the process will log the following messages:
@@ -126,9 +124,9 @@ file. If successful, the process will log the following messages:
126124
Encrypt Using an Existing Key
127125
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128126

129-
You can use an existing master key your KMIP server created and
130-
manages. To use an existing key, connect :binary:`~bin.mongod` to the
131-
key manager by starting :binary:`~bin.mongod` with the following options:
127+
You can use an existing master key that your KMIP server already
128+
manages. To use an existing key, use these options when you start
129+
``mongod`` to connect ``mongod`` to the key manager:
132130

133131
- :option:`--enableEncryption <mongod --enableEncryption>`
134132
- :option:`--kmipServerName <mongod --kmipServerName>`
@@ -137,31 +135,25 @@ key manager by starting :binary:`~bin.mongod` with the following options:
137135
- :option:`--kmipClientCertificateFile <mongod --kmipClientCertificateFile>`
138136
- :option:`--kmipKeyIdentifier <mongod --kmipKeyIdentifier>`
139137

140-
.. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst
138+
.. include:: /includes/reference/fact-add-v1-flag.rst
141139

140+
.. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst
142141

143142
.. code-block:: bash
144143

145-
mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
146-
--kmipPort <KMIP server port> --kmipServerCAFile ca.pem \
147-
--kmipClientCertificateFile client.pem --kmipKeyIdentifier <UID>
144+
mongod --enableEncryption \
145+
--kmipServerName <KMIP Server HostName> \
146+
--kmipPort <KMIP server port> \
147+
--kmipServerCAFile ca.pem \
148+
--kmipClientCertificateFile client.pem \
149+
--kmipKeyIdentifier <UID>
148150

149-
When connecting to the KMIP server, the :binary:`~bin.mongod` verifies
150-
that the specified :option:`--kmipServerName <mongod --kmipServerName>`
151-
matches the Subject Alternative Name ``SAN`` (or, if ``SAN`` is not
152-
present, the Common Name ``CN``) in the certificate presented by the
153-
KMIP server. [#san]_ If ``SAN`` is present, :binary:`~bin.mongod` does not
154-
match against the ``CN``. If the hostname does not match the ``SAN``
155-
(or ``CN``), the :binary:`~bin.mongod` will fail to connect.
151+
.. include:: /includes/reference/fact-connection-check.rst
156152

157153
.. seealso::
158154

159155
:ref:`encryption-key-management-options`
160156

161-
.. [#san]
162-
163-
.. include:: /includes/extracts/4.2-changes-SAN-matching.rst
164-
165157
.. _encrypt-local-key-mgmt:
166158

167159
Local Key Management

0 commit comments

Comments
 (0)