DOSCP-17549 Update x.509 client certificate requirements (#660)

* Initial updates to x509

* fixing inline literals

* fixing more inline literals

* fixing bugs

* more updates

* small tweaks, trying to fix errors

* Fixing spacing issue

* Another shot at fixing spacing

* Another shot at fixing spacing

* Another shot at fixing spacing

* Another shot at fixing spacing

* Incorporating internal review comments

* Incorporating internal review comments

Co-authored-by: Ashley Brown <[email protected]>
Co-authored-by: Ashley Brown <[email protected]>

Author: 3 people

source/core/security-x.509.txt

@@ -44,14 +44,15 @@ Client Certificate Requirements
 MongoDB User and ``$external`` Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To authenticate with a client certificate, you must first add the value
-of the ``subject`` from the client certificate as a MongoDB user. Each
-unique x.509 client certificate corresponds to a single MongoDB user.
+To authenticate with a client certificate, you must first add the client 
+certificate's ``subject`` as a MongoDB user in the ``$external`` database. 
+The ``$external`` database is the :ref:`authentication-database` for the user.
+
+Each unique x.509 client certificate is for one MongoDB user.
 You cannot use a single client certificate to authenticate more than one
 MongoDB user.
 
-Add the user in the ``$external`` database. The ``$external`` database
-is the :ref:`authentication-database` for the user.
+
 
 .. include:: /includes/extracts/sessions-external-username-limit.rst
 
@@ -64,8 +65,8 @@ Member x.509 Certificates
 -------------------------
 
 For internal authentication between members of sharded clusters and
-replica sets you can use x.509 certificates instead of keyfiles, which
-use the :doc:`/core/security-scram` authentication mechanism.
+replica sets, you can use x.509 certificates instead of :doc:`keyfiles 
+</tutorial/deploy-sharded-cluster-with-keyfile-access-control>`.
 
 .. _x509-member-certificate-requirements:
 

source/includes/extracts-sessions.yaml

@@ -102,7 +102,7 @@ ref: sessions-external-username-limit
 content: |
 
    To use :ref:`sessions` with ``$external`` authentication users
-   (Kerberos, LDAP, or x.509 users), the usernames cannot be greater
+   (Kerberos, LDAP, or x.509 users), usernames cannot be greater
    than 10k bytes.
 
 ---

source/includes/extracts-x509-certificate.yaml

@@ -1,10 +1,18 @@
 ref: x509-certificate-client
 content: |
 
-   Client certificates must have the following properties:
+   Client certificate requirements:
 
    - A single Certificate Authority (CA) must issue the certificates
      for both the client and the server.
+     
+   - Each unique MongoDB user must have a unique certificate.
+
+   - The x.509 certificate must *not* be expired.
+
+     .. note:: 
+
+        .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst
 
    - Client certificates must contain the following fields:
 
@@ -13,44 +21,55 @@ content: |
         keyUsage = digitalSignature
         extendedKeyUsage = clientAuth
 
-   - Each unique MongoDB user must have a unique certificate.
+   - At least one of the following client certificate attributes must be **different** 
+     than the attributes in both the :setting:`net.tls.clusterFile` and 
+     :setting:`net.tls.certificateKeyFile` server certificates:  
+    
+     - Organization (``O``)
+     - Organizational Unit (``OU``)
+     - Domain Component (``DC``)
+
+   - The ``subject`` of a client x.509 certificate, which contains the 
+     Distinguished Name (``DN``), must be **different** than the ``subject``\s 
+     of :ref:`member x.509 certificates <x509-member-certificate>`.
+
+     .. important::  
+    
+        If a client x.509 certificate's subject matches the ``O``, ``OU``, and 
+        ``DC`` attributes of the :ref:`x509-member-certificate` (or
+        :parameter:`tlsX509ClusterAuthDNOverride`, if set) exactly, the client 
+        connection is accepted, full permissions are granted, and a warning 
+        message appears in the log. 
+        
+        Only :ref:`cluster member x509 certificates <x509-member-certificate>` 
+        should use the same ``O``, ``OU``, and ``DC`` attribute combinations.
+
+
+     .. versionadded:: 4.2
+
+        If the MongoDB deployment has :parameter:`tlsX509ClusterAuthDNOverride` 
+        set, the client x.509 certificate's subject must not match that value.
 
-   - A client x.509 certificate's subject, which contains the
-     Distinguished Name (``DN``), must **differ** from the subjects of
-     :ref:`member x.509 certificates <x509-member-certificate>`.
-
-     At least one of the Organization (``O``), Organizational Unit
-     (``OU``), or Domain Component (``DC``) attributes in the client
-     certificate must differ from those in the
-     :setting:`net.tls.clusterFile` and
-     :setting:`net.tls.certificateKeyFile` server certificates. If a
-     client x.509 certificate's subject has the same ``O``, ``OU``, and
-     ``DC`` combination as the :ref:`x509-member-certificate` (or
-     :parameter:`tlsX509ClusterAuthDNOverride` if set), the client
-     connection is rejected. Only :ref:`cluster member x509 certificates
-     <x509-member-certificate>` should use same ``O``, ``OU``, and
-     ``DC`` combinations as this grants full permissions.
-
-     If the MongoDB deployment has
-     :parameter:`tlsX509ClusterAuthDNOverride` set (*available starting
-     in MongoDB 4.2*), the client x.509 certificate's subject must also
-     differ from that value.
 
-   - The x.509 certificate must *not* be expired.
 
-     .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst
 ---
 ref: x509-certificate-member
 content: |
 
-   Member certificates which you use to verify membership to a sharded
-   cluster or a replica set (:setting:`net.tls.clusterFile`, if
-   specified, and :setting:`net.tls.certificateKeyFile`), must have the
-   following properties:
+   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:
 
-   - A single Certificate Authority (CA) must issue all the x.509
+   - 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:
@@ -59,44 +78,37 @@ content: |
      - the Organizational Unit (``OU``)
      - the Domain Component (``DC``)
 
-   - The Organization attributes (``O``\'s), the Organizational Unit
-     attributes (``OU``\'s), and the Domain Components (``DC``\'s) must
-     match those from both the :setting:`net.tls.clusterFile` and
-     :setting:`net.tls.certificateKeyFile` certificates for the other
-     cluster members (or the :parameter:`tlsX509ClusterAuthDNOverride`
-     value, if set).
+   - 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.
 
-     To match, the certificate must match all specifications of these
-     attributes, even the non-specification of these attributes. The
-     order of the attributes does not matter.
-
-     In the following example, the two ``DN``\'s contain matching
-     specifications for ``O``, ``OU`` as well as the non-specification
-     of the ``DC`` attribute.
+     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
 
-     However, the following two ``DN``\'s contain a mismatch for the
-     ``OU`` attribute since one contains two ``OU`` specifications and
-     the other, only one specification.
+     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
 
    - Either the Common Name (``CN``) or one of the Subject Alternative
-     Name (``SAN``) entries must match the hostname of the server, used
-     by the other members of the cluster. Starting in MongoDB 4.2, when
-     performing comparison of SAN, MongoDB supports comparison of DNS
-     names or IP addresses. In previous versions, MongoDB only supports
-     comparisons of DNS names.
+     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 subjects:
+     following ``subject``\s:
 
      .. code-block:: bash
 
@@ -112,9 +124,7 @@ content: |
 
         extendedKeyUsage = clientAuth
 
-   - The x.509 certificate must *not* be expired.
 
-     .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst
 ---
 ref: x509-member-auth-configuration
 content: |
@@ -133,17 +143,15 @@ content: |
      <mongod --clusterAuthMode>` (*available starting in MongoDB 4.2*)
 
    :binary:`~bin.mongod` and :option:`mongos <mongos
-   --tlsCertificateKeyFile>` instances use their certificate key file to
-   prove their identity to clients, but it can also be used for
+   --tlsCertificateKeyFile>` instances use their certificate key files to
+   prove their identity to clients, but certificate key files can also be used for
    membership authentication. If you do not specify a cluster file,
-   members use their certificate key file for membership authentication.
-   The certificate key file is the file you specify with
-   :setting:`net.tls.certificateKeyFile` or
+   members use their certificate key files for membership authentication.
+   Specify the certificate key file with :setting:`net.tls.certificateKeyFile` or
    :option:`--tlsCertificateKeyFile <mongod --tlsCertificateKeyFile>`
    (*available starting in MongoDB 4.2*).
 
-   To use the :setting:`certificate key file
-   <net.tls.certificateKeyFile>` for both client authentication and
+   To use the certificate key file for both client authentication and
    membership authentication, the certificate must either:
 
    - Omit ``extendedKeyUsage`` or

source/includes/fact-5.0-x509-certificate-client-warning.rst

@@ -10,6 +10,6 @@ The following platforms do not support common name validation:
 
 Clients using these platforms will not
 :ref:`authenticate <x509-client-authentication>` to 
-MongoDB servers which use X.509 certificate whose hostnames are 
+MongoDB servers that use x.509 certificates whose hostnames are 
 :ref:`specified by CommonName attributes 
 <KMIP-subject-alternative-name-CN>`.