DOCSP-31793 Clarify X509 config (#4203)

* Clarify TLS Certificate Requirements

* Apply suggestions from tech review

* apply tech review feedback (2)

* Changed upstream rebuild

* Merged 10gen master rebuild

* Renamed and cleaned up includes and extracts

* Rebuild

* Merge fixes

---------

Co-authored-by: David Hou <[email protected]>

Author: nvillahermosa-mdb

source/includes/extracts-x509-certificate.yaml

@@ -57,87 +57,16 @@ ref: x509-certificate-member
 content: |
 
    Use member certificates to verify membership to a sharded 
-   cluster or a replica set. Member certificates are stored in 
-   :setting:`net.tls.clusterFile` and :setting:`net.tls.certificateKeyFile`. 
-   Member certificate requirements:
+   cluster or a replica set. Member certificate file paths are
+   configured with the :setting:`net.tls.clusterFile` and
+   :setting:`net.tls.certificateKeyFile` options. Members have the 
+   following configuration requirements:
 
-   - A single Certificate Authority (CA) must issue all x.509
-     certificates for the members of a sharded cluster or a replica set.
-
-   - The x.509 certificate must *not* be expired.
-
-     .. note:: 
-
-        .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst
-
-   - The Distinguished Name (``DN``), found in the member certificate's
-     ``subject``, must specify a non-empty value for *at least one* of
-     the following attributes:
-
-     - the Organization (``O``)
-     - the Organizational Unit (``OU``)
-     - the Domain Component (``DC``)
-
-   - Each cluster member certificate must have identical ``O``\s, ``OU``\s, 
-     and ``DC``\s in their :setting:`net.tls.clusterFile` and
-     :setting:`net.tls.certificateKeyFile` certificates. This also applies to 
-     the :parameter:`tlsX509ClusterAuthDNOverride` value, if set. Attribute 
-     order doesn't matter.
-
-     Here's an example. The two ``DN``\s below have matching
-     specifications for ``O`` and ``OU``, and ``DC`` is not specified.
-
-     .. code-block:: none
-
-        CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US
-        C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2
-
-     The following example is incorrect, because the ``DN``\s don't match. One 
-     ``DN`` has two ``OU`` specifications and the other has only one ``OU``
-     specification.
-
-     .. code-block:: none
-
-        CN=host1,OU=Dept1,OU=Sales,O=MongoDB
-        CN=host2,OU=Dept1,O=MongoDB
-
-     You can also specify a custom set of DN attributes and values in the configuration file using the 
-     :setting:`net.tls.clusterAuthX509.attributes` setting.  This is useful 
-     when you wish to configure X.509 authentication with member certificates that do not have DC, O, or OU attributes in their subject DNs.
-
-     For more information, see :ref:`x509-rotate-member-certs`.
-
-   - Either the Common Name (``CN``) or one of the Subject Alternative
-     Name (``SAN``) entries must match the server hostname for other cluster
-     members. Starting in MongoDB 4.2, when comparing ``SAN``\s, MongoDB can 
-     compare either DNS names or IP addresses. In previous versions, MongoDB 
-     only compares DNS names.
-
-     For example, the certificates for a cluster could have the
-     following ``subject``\s:
-
-     .. code-block:: bash
-
-        subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US
-        subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US
-        subject= CN=<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US
-
-   - If the certificate used as the ``certificateKeyFile`` includes 
-     ``extendedKeyUsage``, the value must include both
-     ``clientAuth`` ("TLS Web Client Authentication") and ``serverAuth``
-     ("TLS Web Server Authentication").
-
-     .. code-block:: none
-
-        extendedKeyUsage = clientAuth, serverAuth
-
-   - If the certificate used as the ``clusterFile`` includes 
-     ``extendedKeyUsage``, the value must include ``clientAuth``.
-
-     .. code-block:: none
-
-        extendedKeyUsage = clientAuth
+   .. include:: /includes/list-cluster-x509-requirements.rst
 
+   The certificates have the following requirements:
+   
+   .. include:: /includes/list-tls-certificate-requirements.rst
 
 ---
 ref: x509-member-auth-configuration

source/includes/list-cluster-x509-requirements.rst

@@ -0,0 +1,22 @@
+- Cluster member configuration must specify a non-empty value for 
+  at least one of the attributes used for authentication. By default, MongoDB accepts:
+
+  - the Organization (``O``)
+  - the Organizational Unit (``OU``)
+  - the Domain Component (``DC``)
+
+  You can specify alternative attributes to use for authentication by
+  setting :setting:`net.tls.clusterAuthX509.extensionValue`.
+
+- Cluster member configuration must include the same
+  :setting:`net.tls.clusterAuthX509.attributes` and use matching values.
+  Attribute order doesn't matter. The following example sets ``O`` and
+  ``OU``, but not ``DC``:
+
+  .. code-block:: yaml
+
+      net:
+        tls:
+          clusterAuthX509:
+            attributes: O=MongoDB, OU=MongoDB Server
+

source/includes/list-tls-certificate-requirements.rst

@@ -0,0 +1,25 @@
+- A single Certificate Authority (CA) must issue all x.509 certificates 
+  for the members of a sharded cluster or a replica set.
+
+- At least one of the Subject Alternative Name (``SAN``) entries must
+  match the server hostname used by other cluster members. When
+  comparing ``SAN``\s, MongoDB can compare either DNS names or IP addresses.
+
+  If you don't specify ``subjectAltName``, MongoDB compares the Common
+  Name (CN) instead. However, this usage of CN is deprecated per `RFC2818 <https://datatracker.ietf.org/doc/html/rfc2818>`_
+
+- If the certificate used as the ``certificateKeyFile`` includes 
+  ``extendedKeyUsage``, the value must include both
+  ``clientAuth`` ("TLS Web Client Authentication") and ``serverAuth``
+  ("TLS Web Server Authentication").
+
+  .. code-block:: none
+
+     extendedKeyUsage = clientAuth, serverAuth
+
+- If the certificate used as the ``clusterFile`` includes 
+  ``extendedKeyUsage``, the value must include ``clientAuth``.
+
+  .. code-block:: none
+
+     extendedKeyUsage = clientAuth

source/tutorial/configure-ssl.txt

@@ -46,6 +46,11 @@ Certificate Authorities
 
 .. include:: /includes/fact-ssl-certificate-authorities.rst
 
+Member Certificate Requirements
+```````````````````````````````
+
+.. include:: /includes/extracts/x509-certificate-member.rst
+
 ``mongod`` and ``mongos`` Certificate Key File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~