DOCSP-10175 online x509 certificate rotation

source/core/security-transport-encryption.txt

@@ -241,6 +241,12 @@ MongoDB also provides the following OCSP-related parameters:
 You can set these parameters at startup using the
 :setting:`setParameter` configuration file setting or the
 :option:`--setParameter <mongod --setParameter>` command line option.
+
+.. note::
+
+   Starting in MongoDB 5.0, the :dbcommand:`rotateCertificates` command
+   and :method:`db.rotateCertificates()` method will also refresh any
+   stapled OCSP responses.
 
 Identity Verification
 ---------------------

source/includes/access-rotate-certificates.rst

@@ -0,0 +1,4 @@
+You must have the :authaction:`rotateCertificates` :ref:`action
+<security-user-actions>` in order to use the |rotate-op|. The
+:authaction:`rotateCertificates` action is part of the
+:authrole:`hostManager` role.

source/includes/fact-cannot-rotate-with-thumbprint.rst

@@ -0,0 +1,7 @@
+.. note::
+
+   You cannot use the :dbcommand:`rotateCertificates` command or the
+   :method:`db.rotateCertificates()` shell method when using
+   :setting:`net.tls.certificateSelector` or
+   :option:`--tlsCertificateSelector <mongod --tlsCertificateSelector>`
+   set to ``thumbprint``

source/reference/built-in-roles.txt

@@ -550,6 +550,7 @@ Cluster Administration Roles
       - :authaction:`killop`
       - :authaction:`logRotate`
       - :authaction:`resync`
+      - :authaction:`rotateCertificates` (New in version 5.0)
       - :authaction:`setParameter`
       - :authaction:`shutdown`
       - :authaction:`touch`

source/reference/command.txt

@@ -697,6 +697,10 @@ Administration Commands
 
      - Changes the name of an existing collection.
 
+   * - :dbcommand:`rotateCertificates`
+
+     - Performs online TLS certificate rotation.
+
    * - :dbcommand:`setFeatureCompatibilityVersion`
 
      - Enables or disables features that persist data that are backwards-incompatible.

source/reference/command/nav-administration.txt

@@ -123,6 +123,10 @@ Administration Commands
 
      - Changes the name of an existing collection.
 
+   * - :dbcommand:`rotateCertificates`
+
+     - Performs online TLS certificate rotation.
+
    * - :dbcommand:`setFeatureCompatibilityVersion`
 
      - Enables or disables features that persist data that are backwards-incompatible.
@@ -180,6 +184,7 @@ Administration Commands
    /reference/command/logRotate
    /reference/command/reIndex
    /reference/command/renameCollection
+   /reference/command/rotateCertificates
    /reference/command/setFeatureCompatibilityVersion
    /reference/command/setIndexCommitQuorum
    /reference/command/setParameter

source/reference/command/rotateCertificates.txt

@@ -0,0 +1,181 @@
+==================
+rotateCertificates
+==================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. versionadded:: 5.0
+
+.. dbcommand:: rotateCertificates
+
+   Rotates the currently used :ref:`TLS certificates
+   <rotated-certs-command>` for a :binary:`~bin.mongod` or
+   :binary:`~bin.mongos` to use the updated values for these
+   certificates defined in the :doc:`configuration file
+   </reference/configuration-options>`.
+
+   The command takes the following form:
+
+   .. code-block:: javascript
+
+      { rotateCertificates: 1,
+        message: "<optional log message>" }
+
+   The :dbcommand:`rotateCertificates` command takes the following
+   optional argument:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 20 80
+
+      * - Parameter
+
+        - Type
+
+        - Description
+
+      * - ``message``
+
+        - string
+
+        - *optional* A message logged by the server to the log file and
+          audit file.
+
+Output
+------
+
+The :dbcommand:`rotateCertificates` command returns a document with
+the following field:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+
+   * - Field
+
+     - Type
+
+     - Description
+
+   * - ``ok``
+
+     - bool
+
+     - Contains the command's execution status. ``true`` on success, or
+       ``false`` if an error occurred. If ``false``, an ``errmsg`` field
+       is additionally provided with a detailed error message.      
+
+Behavior
+--------
+
+.. _rotated-certs-command:
+
+Rotation includes the following certificates:
+
+- :setting:`TLS Certificates <net.tls.certificateKeyFile>`
+- :setting:`CRL (Certificate Revocation List) files <net.tls.CRLFile>`
+  (on Linux and Windows platforms)
+- :setting:`CA (Certificate Authority) files <net.tls.CAFile>`
+
+To rotate one or more of these certificates:
+
+#. Replace the certificate or certificates you wish to rotate on the
+   filesystem, noting the following constraints:
+
+   - Each new certificate must have the *same filename* and
+     *same filepath* as the certificate it is replacing.
+
+   - If rotating an encrypted :setting:`TLS Certificate
+     <net.tls.certificateKeyFile>`, its password must be the same as
+     the password for the old certificate (as specified to the
+     :setting:`~net.tls.certificateKeyFilePassword` configuration file
+     setting). Certificate rotation does not support the interactive
+     password prompt.
+
+#. Connect :binary:`~bin.mongosh` to the :binary:`~bin.mongod` or
+   :binary:`~bin.mongos` instance that you wish to perform certificate
+   rotation on.
+
+#. Run the :dbcommand:`rotateCertificates` command to rotate the
+   certificates used by the the :binary:`~bin.mongod` or
+   :binary:`~bin.mongos` instance.
+
+When certificate rotation takes place:
+
+- Existing connections to the :binary:`~bin.mongod` or
+  :binary:`~bin.mongos` instance are not terminated, and will continue
+  to use the old certificates.
+
+- Any new connections will use the new certificates.
+
+If you have configured :parameter:`OCSP <ocspEnabled>` for your
+deployment, the :dbcommand:`rotateCertificates` command will also fetch
+stapled OCSP responses during rotation.
+
+The :dbcommand:`rotateCertificates` command may be run on a running
+:binary:`~bin.mongod` or :binary:`~bin.mongos` regardless of replication
+status.
+
+Only one instance of :method:`db.rotateCertificates()` or
+:dbcommand:`rotateCertificates` may run on each :binary:`~bin.mongod` or
+:binary:`~bin.mongos` process at a time. Attempting to initiate a second
+instance while one is already running will result in an error.
+
+Incorrect, expired, revoked, or missing certificate files will cause the
+certificate rotation to fail, but will not invalidate the existing
+TLS configuration or terminate the running :binary:`~bin.mongod` or
+:binary:`~bin.mongos` process.
+
+If the :binary:`~bin.mongod` or :binary:`~bin.mongos` is running with
+:option:`--tlsCertificateSelector <mongod --tlsCertificateSelector>` set
+to ``thumbprint``, :dbcommand:`rotateCertificates` will fail and write
+a warning message to the log file.
+
+Logging
+-------
+
+On successful rotation, the subject names, thumbprints, and the
+validity period of the server and cluster certificate thumbprints are
+logged to the configured :ref:`log destination
+<log-message-destinations>`. If :doc:`auditing </core/auditing>` is
+enabled, this information is also written to the audit log.
+
+On Linux and Windows platforms, if a :setting:`CRL file
+<net.tls.CRLFile>` is present, its thumbprint and validity period are
+also logged to these locations.
+
+Required Access
+---------------
+
+.. |rotate-op| replace:: :dbcommand:`rotateCertificates` command
+
+.. include:: /includes/access-rotate-certificates.rst
+
+Example
+-------
+
+The following operation rotates the certificates on a running
+:binary:`~bin.mongod` instance, after having made the appropriate
+updates to the configuration file to specify the updated certificate
+information:
+
+.. code-block:: javascript
+
+   db.adminCommand( { rotateCertificates: 1 } )
+
+The following performs the same as above, but also writes a custom log
+message at rotation time to the :ref:`log file
+<log-message-destinations>` and :doc:`audit file </core/auditing>`:
+
+.. code-block:: javascript
+
+   db.adminCommand( { rotateCertificates: 1, message: "Rotating certificates" } )

source/reference/configuration-options.txt

@@ -1298,6 +1298,8 @@ Core Options
    intermediate CA certificate, the secure certificate store must
    contain the intermedia CA certificate *and* the root CA certificate.
 
+   .. include:: /includes/fact-cannot-rotate-with-thumbprint.rst
+
 .. setting:: net.tls.clusterCertificateSelector
 
    *Type*: string

source/reference/method.txt

@@ -522,6 +522,11 @@ Database
 
      - *Removed in MongoDB 5.0.* Resets the last error status.
 
+   * - :method:`db.rotateCertificates()`
+
+     - Performs online TLS certificate rotation. Wraps
+       :dbcommand:`rotateCertificates`.
+
    * - :method:`db.runCommand()`
 
      - Runs a :doc:`database command </reference/command>`.