DOCS-11689: x509 and invalid Certificates

Author: kay-kim

source/includes/extracts-mongo-ssl-options-base.yaml

@@ -0,0 +1,68 @@
+ref: ssl-facts-x509-invalid-certificate
+content: |
+
+   Starting in MongoDB 3.2.21, if you specify
+   ``--sslAllowInvalidCertificates`` or ``ssl.allowInvalidCertificates:
+   true`` when using x.509 authentication, an invalid certificate is
+   only sufficient to establish a TLS/SSL connection but is
+   *insufficient* for authentication.
+---
+ref: ssl-facts-x509-ca-file
+content: |
+
+   If using x.509 authentication, ``--sslCAFile`` or ``ssl.CAFile``
+   must be specified.
+---
+ref: ssl-facts-see-more
+content: |
+   For more information about TLS/SSL and MongoDB, see
+   :doc:`/tutorial/configure-ssl` and
+   :doc:`/tutorial/configure-ssl-clients` .
+---
+# This is separate from the mongod/mongos ca file extract since the version is different.
+ref: ssl-facts-mongo-shell-ca
+content: |
+
+   Starting in version 3.2.6, if ``--sslCAFile`` or ``ssl.CAFile`` is
+   not specified, the system-wide CA certificate store will be used
+   when connecting to an TLS/SSL-enabled server. In previous versions
+   of MongoDB, the :binary:`~bin.mongo` shell exited with an error that
+   it could not validate the certificate.
+   
+   .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst
+---
+ref: ssl-facts-invalid-cert-warning-clients
+content: |
+
+   .. warning::
+      
+      For TLS/SSL connections to :binary:`~bin.mongod` and
+      :binary:`~bin.mongos`, avoid using
+      ``--sslAllowInvalidCertificates`` if possible and only use
+      ``--sslAllowInvalidCertificates`` on systems where intrusion is
+      not possible.
+
+      If the :binary:`~bin.mongo` shell (and other
+      :ref:`mongodb-tools-support-ssl`) runs with the
+      ``--sslAllowInvalidCertificates`` option, the
+      :binary:`~bin.mongo` shell (and other
+      :ref:`mongodb-tools-support-ssl`) will not attempt to validate
+      the server certificates. This creates a vulnerability to expired
+      :binary:`~bin.mongod` and :binary:`~bin.mongos` certificates as
+      well as to foreign processes posing as valid
+      :binary:`~bin.mongod` or :binary:`~bin.mongos` instances.
+
+---
+ref: ssl-facts-mongo-ssl-options-configure
+content: |
+
+   To connect to a :binary:`~bin.mongod` or :binary:`~bin.mongos` that
+   uses TLS/SSL, you must also specify the ``--host`` option for the
+   :binary:`~bin.mongo` shell if you haven't specified a connect
+   string. The :binary:`~bin.mongo` shell verifies that the hostname of
+   the :binary:`~bin.mongod` or :binary:`~bin.mongos` matches the CN or
+   SAN of ``--sslPEMKeyFile`` certificate presented by the
+   :binary:`~bin.mongod` or :binary:`~bin.mongos`. If the hostname does
+   not match the CN/SAN, :binary:`~bin.mongo` will fail to connect.
+   
+...

source/includes/extracts-mongo-ssl-options.yaml

@@ -686,6 +686,7 @@ directive: setting
 replacement:
   program: ":binary:`~bin.mongos` or :binary:`~bin.mongod`"
   verb: "Enable or disable"
+  setting: "``allowInvalidCertificates: true``"
 inherit:
   name: sslAllowInvalidCertificates
   program: mongod
@@ -1568,7 +1569,7 @@ description: |
   MongoDB instances if the hostname their certificates do not match the
   specified hostname.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 replacement:
   program: ":binary:`~bin.mongod`"

source/includes/extracts-ssl-facts.yaml

@@ -213,12 +213,14 @@ args: null
 directive: option
 description: |
 
+  .. versionchanged:: 3.2.6
+
   Enables connection to a :binary:`~bin.mongod` or :binary:`~bin.mongos` that has
   TLS/SSL support enabled.
 
-  .. include:: /includes/extracts/mongo-ssl-options-mongo.rst
+  .. include:: /includes/extracts/ssl-facts-mongo-shell-ca.rst
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 ---
 program: mongo
@@ -236,7 +238,7 @@ description: |
   :setting:`~net.ssl.CAFile` enabled *without*
   :setting:`~net.ssl.allowConnectionsWithoutCertificates`.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 ---
 program: mongo
@@ -254,7 +256,7 @@ description: |
   specify the {{role}} option, the {{program}} will prompt for a
   passphrase. See :ref:`ssl-certificate-password`.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 ---
 program: mongo
@@ -266,11 +268,9 @@ description: |
   from the Certificate Authority. Specify the file name of the
   :file:`.pem` file using relative or absolute paths.
 
-  .. include:: /includes/extracts/mongo-ssl-options-mongo.rst
-
-  .. include:: /includes/extracts/mongo-warning-sslCAFile.rst
+  .. include:: /includes/extracts/ssl-facts-mongo-shell-ca.rst
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 optional: true
 ---
@@ -284,7 +284,7 @@ description: |
   List. Specify the file name of the :file:`.pem` file using relative or
   absolute paths.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 ---
 program: mongo
@@ -302,15 +302,18 @@ directive: option
 description: |
 
   Bypasses the validation checks for server certificates and allows
-  the use of invalid certificates. When using the
-  :setting:`~net.ssl.allowInvalidCertificates` setting, MongoDB logs as a
-  warning the use of the invalid certificate.
+  the use of invalid certificates to connect.
+
+  .. note::
+     
+     .. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst
 
-  .. include:: /includes/extracts/mongo-ssl-options-mongo.rst
+  .. include:: /includes/extracts/ssl-facts-invalid-cert-warning-clients.rst
 
-  .. include:: /includes/extracts/mongo-warning-sslCAFile.rst
+  When using the :setting:`~net.ssl.allowInvalidCertificates` setting,
+  MongoDB logs as a warning the use of the invalid certificate.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 ---
 program: mongo

source/includes/fact-ssl-supported.rst

@@ -598,7 +598,9 @@ description: |
        - Recommended. Send the x.509 certificate for authentication and
          accept only x.509 certificates.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst
+
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 ---
 program: mongod
@@ -1208,7 +1210,7 @@ description: |
   {{option}}. By default, {{role}} is
   disabled.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 replacement:
   verb: "Enables"
@@ -1251,7 +1253,9 @@ description: |
 
        - The server uses and accepts only TLS/SSL encrypted connections.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst
+
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 optional: true
 replacement:
@@ -1269,7 +1273,7 @@ description: |
 
   You must specify {{role}} when TLS/SSL is enabled.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 replacement:
   intro: "Specifies the"
@@ -1289,7 +1293,7 @@ description: |
      specify the {{role}} option, the {{program}} will prompt for a
      passphrase. See :ref:`ssl-certificate-password`.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 replacement:
   intro: "Specifies the"
@@ -1310,7 +1314,9 @@ description: |
   authentication, the cluster uses the ``.pem`` file specified in the
   {{pemKeyOption}} {{directive}}.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst
+
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 replacement:
   pemKeyOption: ":option:`--sslPEMKeyFile`"
@@ -1333,7 +1339,7 @@ description: |
   {{role}} option, the {{program}} will prompt for a passphrase. See
   :ref:`ssl-certificate-password`.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 replacement:
   intro: "Specifies the"
@@ -1348,9 +1354,9 @@ description: |
   from the Certificate Authority. Specify the file name of the
   :file:`.pem` file using relative or absolute paths.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 
-  .. include:: /includes/warning-x509-requires-sslCAfile.rst
 optional: true
 replacement:
   intro: "Specifies the"
@@ -1365,7 +1371,7 @@ description: |
   List. Specify the file name of the :file:`.pem` file using relative or
   absolute paths.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 replacement:
   intro: "Specifies the"
@@ -1376,14 +1382,19 @@ args: null
 directive: option
 description: |
 
-  {{verb}} the validation checks for TLS/SSL certificates on other servers
-  in the cluster and allows the use of invalid certificates.
+  {{verb}} the validation checks for TLS/SSL certificates on other
+  servers in the cluster and allows the use of invalid certificates to
+  connect.
+
+  .. note::
+
+     .. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst
 
   When using
   the {{role}} setting, MongoDB
   logs a warning regarding the use of the invalid certificate.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 replacement:
   verb: "Bypasses"
@@ -1406,7 +1417,7 @@ description: |
   Use the {{role}} option if you have a mixed deployment that includes
   clients that do not or cannot present certificates to the {{program}}.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 replacement:
   verb: "Disables"
   old_name: "``--sslWeakCertificateValidation``"
@@ -1426,7 +1437,7 @@ description: |
   to other members if the hostnames in their certificates do not match
   their configured hostname.
 
-  .. include:: /includes/fact-ssl-supported.rst
+  .. include:: /includes/extracts/ssl-facts-see-more.rst
 optional: true
 ---
 program: mongod