Skip to content

Commit 6fbdc2c

Browse files
author
Dave Cuthbert
authored
DOCSP-28987 kmip-v1.0-support (#3012)
* DOCSP-28987 kmip-v1.0-support * Example * Review tweeks * Staging fixes * Staging fixes * Release notes * Release notes * Release notes * Review feedback * Review feedback * Server name
1 parent d91496d commit 6fbdc2c

File tree

11 files changed

+110
-50
lines changed

11 files changed

+110
-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
@@ -2869,13 +2869,7 @@ Key Management Configuration Options
28692869
which it can successfully establish a connection. KMIP server
28702870
selection occurs only at startup.
28712871

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

28802874
.. include:: /includes/extracts/4.2-changes-SAN-matching.rst
28812875

@@ -3050,6 +3044,29 @@ Key Management Configuration Options
30503044

30513045
To disable disable polling, set the value to ``-1``.
30523046

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

30543071
.. _security.sasl.options:
30553072

source/reference/program/mongod.txt

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

30933093
.. include:: /includes/fact-enterprise-only-admonition.rst
3094-
3094+
30953095

30963096

30973097
.. option:: --kmipKeyIdentifier <string>
@@ -3297,10 +3297,19 @@ Encryption Key Management Options
32973297

32983298
.. versionadded:: 5.3
32993299

3300-
Frequency in seconds at which mongod polls the KMIP server for active keys.
3300+
Frequency in seconds at which ``mongod`` polls the KMIP server for
3301+
active keys.
33013302

33023303
To disable disable polling, set the value to ``-1``.
33033304

3305+
.. option:: --kmipUseLegacyProtocol <boolean>
3306+
3307+
*Default*: false
3308+
3309+
.. versionadded:: 7.0 (and 6.0.6)
3310+
3311+
.. include:: /includes/reference/fact-kmip-description.rst
3312+
33043313
.. option:: --eseDatabaseKeyRollover
33053314

33063315
.. versionadded:: 4.2

source/release-notes/7.0.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,10 @@ New Parameters
4141
MongoDB 7.0 adds the :parameter:`balancerMigrationsThrottlingMs`
4242
parameter which allows you to throttle the balancing rate.
4343

44+
Security
45+
~~~~~~~~
46+
47+
MongoDB 7.0 (and 6.0.6) adds the :setting:`useLegacyProtocol
48+
<security.kmip.useLegacyProtocol>` setting. This setting allows MongoDB
49+
servers to connect to KMIP servers that use KMIP protocol version 1.0 or
50+
1.1.

0 commit comments

Comments
 (0)