DOCSP-28987 kmip-v1.0-support (#3012)

Dave Cuthbert · web-flow · commit 6fbdc2c261c4 · 2023-05-09T12:08:45.000-04:00
* 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
diff --git a/source/core/csfle/fundamentals/manage-keys.txt b/source/core/csfle/fundamentals/manage-keys.txt
@@ -62,6 +62,8 @@ Supported Key Management Services
 - Any KMIP Compliant {+kms-long+}
 - Local Key Provider *(for testing only)*
 
+.. include:: /includes/reference/fact-kmip-version.rst
+
 To learn more about these providers, including diagrams that show how
 your application uses them to perform {+csfle+}, see
 :ref:`csfle-reference-kms-providers`.
diff --git a/source/core/csfle/tutorials/kmip/kmip-automatic.txt b/source/core/csfle/tutorials/kmip/kmip-automatic.txt
@@ -71,6 +71,15 @@ Before You Get Started
 Set Up the KMS
 --------------
 
+.. note::
+
+   ``mongod`` reads the KMIP configuration at startup. By default, the
+   server uses KMIP protocol version 1.2.
+
+   To connect to a version 1.0 or 1.1 KMIP server, use the 
+   :setting:`useLegacyProtocol <security.kmip.useLegacyProtocol>`
+   setting.
+
 .. include:: /includes/tutorials/language-id.rst
 
 .. procedure::
diff --git a/source/core/security-encryption-at-rest.txt b/source/core/security-encryption-at-rest.txt
@@ -111,13 +111,13 @@ transport encryption.
 
 For details, see :ref:`rotate-encryption-keys`.
 
+.. _security-encryption-at-rest-audit-log:
+
 Audit Log
 ~~~~~~~~~
 
 Available in MongoDB Enterprise only.
 
-.. _security-encryption-at-rest-audit-log:
-
 Use KMIP Server to Manage Keys for Encrypting the MongoDB Audit Log
 ```````````````````````````````````````````````````````````````````
 
@@ -128,6 +128,8 @@ Interoperability Protocol (KMIP) server.
 KMIP simplifies the management of cryptographic keys and eliminates the
 use of non-standard key management processes.
 
+.. include:: /includes/reference/fact-kmip-version.rst
+
 To use a KMIP server with audit log encryption, configure these settings
 and parameters:
 
@@ -165,10 +167,9 @@ information to log files as a part of normal operations, depending on
 the configured :ref:`log verbosity <log-messages-configure-verbosity>`.
 
 Use the :setting:`security.redactClientLogData` setting to prevent
-potentially sensitive information from entering the
-:binary:`~bin.mongod` process log.
-:setting:`~security.redactClientLogData` reduces detail in the log and
-may complicate log diagnostics.
+potentially sensitive information from entering the ``mongod`` process
+log. Setting :setting:`~security.redactClientLogData` reduces detail in
+the log and may complicate log diagnostics.
 
 See the :ref:`log redaction <monitoring-log-redaction>` manual entry for
 more information.
diff --git a/source/includes/reference/fact-add-v1-flag.rst b/source/includes/reference/fact-add-v1-flag.rst
@@ -0,0 +1,3 @@
+To connect to a version 1.0 or 1.1 KMIP server, use the
+:option:`--kmipUseLegacyProtocol <mongod --kmipUseLegacyProtocol>`
+option.
diff --git a/source/includes/reference/fact-connection-check.rst b/source/includes/reference/fact-connection-check.rst
@@ -0,0 +1,11 @@
+``mongod`` verifies the connection to the KMIP server on startup.
+
+The server name specified in :option:`--kmipServerName
+<mongod --kmipServerName>` must match either the Subject Alternative
+Name ``SAN`` or the Common Name ``CN`` on the certificate presented by
+the KMIP server. ``SAN`` can be a system name or an IP address. 
+
+If ``SAN`` is present, ``mongod`` does not try to match against ``CN``.
+
+If the hostname or IP address of the KMIP server does does not match
+either ``SAN`` or ``CN``, ``mongod`` does not start.
diff --git a/source/includes/reference/fact-kmip-description.rst b/source/includes/reference/fact-kmip-description.rst
@@ -0,0 +1,6 @@
+When ``true``, ``mongod`` uses KMIP protocol version 1.0 or 1.1 instead
+of the default version. The default KMIP protocol is version 1.2.
+
+To use :ref:`audit log encryption <security-encryption-at-rest-audit-log>`
+with KMIP version 1.0 or 1.1, you must specify
+:parameter:`auditEncryptKeyWithKMIPGet` at startup.
diff --git a/source/includes/reference/fact-kmip-version.rst b/source/includes/reference/fact-kmip-version.rst
@@ -0,0 +1,3 @@
+The default KMIP protocol version is 1.2. You can configure MongoDB to
+use KMIP version 1.0 or 1.1 in the MongoDB server :ref:`configuration
+file <configuration-options>`.
diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt
@@ -2869,13 +2869,7 @@ Key Management Configuration Options
    which it can successfully establish a connection. KMIP server
    selection occurs only at startup.
 
-   When connecting to a KMIP server, the :binary:`~bin.mongod`
-   verifies that the specified :setting:`security.kmip.serverName`
-   matches the Subject Alternative Name ``SAN`` (or, if ``SAN`` is not
-   present, the Common Name ``CN``) in the certificate presented by the
-   KMIP server. If ``SAN`` is present, :binary:`~bin.mongod` does not
-   match against the ``CN``. If the hostname does not match the ``SAN``
-   (or ``CN``), the :binary:`~bin.mongod` will fail to connect.
+   .. include:: /includes/reference/fact-connection-check.rst
 
    .. include:: /includes/extracts/4.2-changes-SAN-matching.rst
 
@@ -3050,6 +3044,29 @@ Key Management Configuration Options
 
    To disable disable polling, set the value to ``-1``. 
 
+.. setting:: security.kmip.useLegacyProtocol
+
+   *Type*: boolean
+
+   *Default*: false
+
+   .. versionadded:: 7.0 (and 6.0.6)
+
+   .. include:: /includes/reference/fact-kmip-description.rst
+
+   To use KMIP protocol version 1.0 or 1.1, substitute your local values
+   and add an entry like this to your ``mongod`` configuration file:
+
+   .. code:: bash
+      :emphasize-lines: 7
+
+      security:
+        enableEncryption: true
+        kmip:
+          serverName: "mdbhost.somecompany.com"
+          serverCAFile: "security/libs/trusted-ca.pem"
+          clientCertificateFile: "security/libs/trusted-client.pem"
+          useLegacyProtocol: true
 
 .. _security.sasl.options:
 
diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt
@@ -3091,7 +3091,7 @@ Encryption Key Management Options
    Requires :option:`--enableEncryption`.
    
    .. include:: /includes/fact-enterprise-only-admonition.rst
-   
+
 
 
 .. option:: --kmipKeyIdentifier <string>
@@ -3297,10 +3297,19 @@ Encryption Key Management Options
    
    .. versionadded:: 5.3
 
-   Frequency in seconds at which mongod polls the KMIP server for active keys. 
+   Frequency in seconds at which ``mongod`` polls the KMIP server for
+   active keys. 
 
    To disable disable polling, set the value to ``-1``.
 
+.. option:: --kmipUseLegacyProtocol <boolean>
+
+   *Default*: false 
+
+   .. versionadded:: 7.0 (and 6.0.6)
+
+   .. include:: /includes/reference/fact-kmip-description.rst
+
 .. option:: --eseDatabaseKeyRollover
 
    .. versionadded:: 4.2
diff --git a/source/release-notes/7.0.txt b/source/release-notes/7.0.txt
@@ -41,3 +41,10 @@ New Parameters
 MongoDB 7.0 adds the :parameter:`balancerMigrationsThrottlingMs`
 parameter which allows you to throttle the balancing rate.
 
+Security
+~~~~~~~~
+
+MongoDB 7.0 (and 6.0.6) adds the :setting:`useLegacyProtocol
+<security.kmip.useLegacyProtocol>` setting. This setting allows MongoDB
+servers to connect to KMIP servers that use KMIP protocol version 1.0 or
+1.1.
diff --git a/source/tutorial/configure-encryption.txt b/source/tutorial/configure-encryption.txt
@@ -52,8 +52,6 @@ stored in the key manager.
 
 MongoDB Enterprise supports secure transfer of keys with Key Management
 Interoperability Protocol (KMIP) compliant key management appliances.
-Any appliance vendor that provides support for KMIP is expected
-to be compatible.
 
 .. include:: /includes/partners-security.rst
 
@@ -68,6 +66,8 @@ Prerequisites
 
 - Your key manager must support the KMIP communication protocol.
 
+  .. include:: /includes/reference/fact-kmip-version.rst
+
 - To authenticate MongoDB to a KMIP server, you must have a valid
   certificate issued by the key management appliance.
 
@@ -80,34 +80,32 @@ Prerequisites
 Encrypt Using a New Key
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-To create a new key, connect :binary:`~bin.mongod` to the key manager by starting
-:binary:`~bin.mongod` with the following options:
+To create a new key when you connect to the key manager, use the
+following options to start ``mongod``:
 
 - :option:`--enableEncryption <mongod --enableEncryption>`
 - :option:`--kmipServerName <mongod --kmipServerName>`
 - :option:`--kmipPort <mongod --kmipPort>`
 - :option:`--kmipServerCAFile <mongod --kmipServerCAFile>`
 - :option:`--kmipClientCertificateFile <mongod --kmipClientCertificateFile>`
 
+.. include:: /includes/reference/fact-add-v1-flag.rst
+
 .. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst
 
-The following  operation creates a new master key in your key manager which
-:binary:`~bin.mongod` uses to encrypt the keys :binary:`~bin.mongod` generates
-for each database.
+The following operation creates a new master key in your key manager.
+``mongod`` uses the master key to encrypt the keys that ``mongod``
+generates for each database.
 
 .. code-block:: bash
 
-   mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
-     --kmipPort <KMIP server port> --kmipServerCAFile ca.pem \
-     --kmipClientCertificateFile client.pem
+   mongod --enableEncryption \
+          --kmipServerName <KMIP Server HostName> \
+          --kmipPort <KMIP server port> \
+          --kmipServerCAFile ca.pem \
+          --kmipClientCertificateFile client.pem
 
-When connecting to the KMIP server, the :binary:`~bin.mongod` verifies
-that the specified :option:`--kmipServerName <mongod --kmipServerName>`
-matches the Subject Alternative Name ``SAN`` (or, if ``SAN`` is not
-present, the Common Name ``CN``) in the certificate presented by the
-KMIP server. [#san]_ If ``SAN`` is present, :binary:`~bin.mongod` does
-not match against the ``CN``. If the hostname does not match the
-``SAN`` (or ``CN``), the :binary:`~bin.mongod` will fail to connect.
+.. include:: /includes/reference/fact-connection-check.rst
 
 To verify that the key creation and usage was successful, check the log
 file. If successful, the process will log the following messages:
@@ -126,9 +124,9 @@ file. If successful, the process will log the following messages:
 Encrypt Using an Existing Key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can use an existing master key your KMIP server created and
-manages. To use an existing key, connect :binary:`~bin.mongod` to the
-key manager by starting :binary:`~bin.mongod` with the following options:
+You can use an existing master key that your KMIP server already
+manages. To use an existing key, use these options when you start 
+``mongod`` to connect ``mongod`` to the key manager:
 
 - :option:`--enableEncryption <mongod --enableEncryption>`
 - :option:`--kmipServerName <mongod --kmipServerName>`
@@ -137,31 +135,25 @@ key manager by starting :binary:`~bin.mongod` with the following options:
 - :option:`--kmipClientCertificateFile <mongod --kmipClientCertificateFile>`
 - :option:`--kmipKeyIdentifier <mongod --kmipKeyIdentifier>`
 
-.. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst
+.. include:: /includes/reference/fact-add-v1-flag.rst
 
+.. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst
 
 .. code-block:: bash
 
-   mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
-     --kmipPort <KMIP server port> --kmipServerCAFile ca.pem \
-     --kmipClientCertificateFile client.pem --kmipKeyIdentifier <UID>
+   mongod --enableEncryption \
+          --kmipServerName <KMIP Server HostName> \
+          --kmipPort <KMIP server port> \
+          --kmipServerCAFile ca.pem \
+          --kmipClientCertificateFile client.pem \
+          --kmipKeyIdentifier <UID>
 
-When connecting to the KMIP server, the :binary:`~bin.mongod` verifies
-that the specified :option:`--kmipServerName <mongod --kmipServerName>`
-matches the Subject Alternative Name ``SAN`` (or, if ``SAN`` is not
-present, the Common Name ``CN``) in the certificate presented by the
-KMIP server. [#san]_ If ``SAN`` is present, :binary:`~bin.mongod` does not
-match against the ``CN``. If the hostname does not match the ``SAN``
-(or ``CN``), the :binary:`~bin.mongod` will fail to connect.
+.. include:: /includes/reference/fact-connection-check.rst
 
 .. seealso::
 
    :ref:`encryption-key-management-options`
 
-.. [#san]
-
-   .. include:: /includes/extracts/4.2-changes-SAN-matching.rst
-
 .. _encrypt-local-key-mgmt:
 
 Local Key Management

Original file line number	Diff line number	Diff 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.`
Original file line number	Diff line number	Diff 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>`.