DOCSP-41508: TLS

source/connect.txt

@@ -24,10 +24,10 @@ Connect to MongoDB
 
    /connect/stable-api
    /connect/connection-targets
+   /connect/tls
 
 ..    /connect/mongoclient
 ..    /connect/connection-options
-..    /connect/tls
 ..    /connect/network-compression
 ..    /connect/server-selection
 ..    /connect/csot
@@ -111,8 +111,8 @@ The following tabs demonstrate how to enable TLS on a connection:
 
 .. include:: /includes/connect/tls-tabs.rst
 
-.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in
-.. the TLS configuration guide.
+To learn more about enabling TLS, see :ref:`tls-enable` in
+the TLS configuration guide.
 
 Disable Hostname Verification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/connect/tls.txt

@@ -0,0 +1,340 @@
+.. _kotlin-sync-enable-tls:
+
+==============================
+Enable TLS/SSL on a Connection
+==============================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, security, authentication
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to connect to MongoDB instances with the
+`TLS/SSL <https://en.wikipedia.org/wiki/Transport_Layer_Security>`__
+security protocol using the underlying TLS/SSL support in the JDK. To
+configure your connection to use TLS/SSL, enable the TLS/SSL settings in
+either the `ConnectionString <{+core-api+}/com/mongodb/ConnectionString.html>`__
+or `MongoClientSettings <{+core-api+}/com/mongodb/MongoClientSettings.html>`__.
+
+.. note:: Debugging TLS/SSL
+
+   If you experience trouble setting up your TLS/SSL connection, you can
+   use the ``-Djavax.net.debug=all`` system property to view more
+   log statements. See `the Oracle guide to debugging TLS/SSL connections
+   <https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html>`__
+   for more information.
+
+.. _tls-enable:
+
+Enable TLS/SSL
+--------------
+
+You can enable TLS/SSL for the connection to your MongoDB instance
+in two different ways: through a parameter in your connection string, or
+using a method in the ``MongoClientSettings.Builder`` class.
+
+.. note:: DNS Seedlist Protocol Enables TLS
+
+   If you connect by using the DNS seedlist protocol, indicated by the
+   ``mongodb+srv`` prefix in your connection string, the driver
+   automatically enables TLS/SSL. To disable it, set the ``tls``
+   parameter value to ``false`` in your connection string, or set the
+   ``enabled`` property to ``false`` in the ``SslSettings.Builder``
+   block when creating a ``MongoClientSettings`` instance.
+
+   To learn more about connection behavior when you use a DNS seedlist,
+   see the :manual:`SRV Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`
+   section in the Server manual.
+
+.. tabs::
+
+   .. tab:: ConnectionString
+      :tabid: connectionstring
+
+      To enable TLS/SSL on a connection with a `ConnectionString
+      <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__, assign the connection string
+      parameter ``tls`` a value of ``true`` in the connection string passed to
+      ``MongoClient.create()``:
+
+      .. literalinclude:: /includes/connect/tls.kt
+         :start-after: start-tls-connection-string
+         :end-before: end-tls-connection-string
+         :language: kotlin
+         :copyable:
+         :dedent:
+
+   .. tab:: MongoClientSettings
+      :tabid: mongoclientsettings
+
+      To configure your ``MongoClient``'s TLS/SSL connection options using the
+      ``MongoClientSettings.Builder`` class, call the
+      `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__
+      method. Set the ``enabled`` property to ``true`` in the ``SslSettings.Builder``
+      block to enable TLS/SSL:
+
+      .. literalinclude:: /includes/connect/tls.kt
+         :start-after: start-tls-mongo-client-settings
+         :end-before: end-tls-mongo-client-settings
+         :language: kotlin
+         :copyable:
+         :dedent:
+
+.. _tls_configure-certificates:
+
+Configure Certificates
+----------------------
+
+{+language+} applications that initiate TLS/SSL requests require access to
+cryptographic certificates that prove identity for the application
+itself and other applications with which the application
+interacts. You can configure access to these certificates in your application with
+the following mechanisms:
+
+- The JVM trust store and JVM key store
+- A client-specific trust store and key store
+
+.. note::
+
+   The following sections are based on the documentation for Oracle JDK,
+   so some parts may be inapplicable to your JDK or to the custom TLS/SSL
+   implementation you use.
+
+.. _tls-configure-jvm-truststore:
+
+Configure the JVM Trust Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+   By default, the JRE includes many commonly used public certificates
+   from signing authorities like `Let's Encrypt
+   <https://letsencrypt.org/>`__. As a result, you can connect to
+   instances of :atlas:`MongoDB Atlas </?jmp=docs_driver_kotlin>` (or any other
+   server whose certificate is signed by an authority in the JRE's default
+   certificate store) with TLS/SSL without configuring the trust store.
+
+The JVM trust store saves certificates that securely identify other
+applications with which your {+language+} application interacts. Using these
+certificates, your application can prove that the connection to another
+application is genuine and secure from tampering by third parties.
+
+If your MongoDB instance uses a certificate that is signed by an
+authority that is not present in the JRE's default certificate store,
+your application must configure two system properties to initiate
+SSL/TLS requests. These properties ensure that your application can
+validate the TLS/SSL certificate presented by a connected MongoDB instance.
+
+- ``javax.net.ssl.trustStore``: the path to a trust store containing the
+  certificate of the signing authority
+
+- ``javax.net.ssl.trustStorePassword``: the password to access the trust
+  store defined in ``javax.net.ssl.trustStore``
+
+You can create a trust store with the `keytool
+<https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html>`__
+command line tool provided as part of the JDK:
+
+.. code-block:: console
+
+   keytool -importcert -trustcacerts -file <path to certificate authority file>
+            -keystore <path to trust store> -storepass <password>
+
+Configure the JVM Key Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+   By default, MongoDB instances do not perform client certificate
+   validation. You must configure the key store if you configured your MongoDB
+   instance to validate client certificates.
+
+The JVM key store saves certificates that securely identify your {+language+}
+application to other applications. Using these certificates, other
+applications can prove that the connection to your application is
+genuine and secure from tampering by third parties.
+
+An application that initiates TLS/SSL requests needs to set two JVM system
+properties to ensure that the client presents a TLS/SSL certificate to
+the MongoDB server:
+
+- ``javax.net.ssl.keyStore``: the path to a key store containing the client's
+  TLS/SSL certificates
+
+- ``javax.net.ssl.keyStorePassword``: the password to access the key store
+  defined in ``javax.net.ssl.keyStore``
+
+You can create a key store with the `keytool
+<https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html>`__
+or `openssl <https://www.openssl.org/docs/manmaster/man1/openssl.html>`__
+command line tool.
+
+For more information on configuring a {+language+} application to use TLS/SSL,
+please see the `JSSE Reference Guide
+<https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html>`__.
+
+.. _tls-disable-hostname-verification:
+
+Configure a Client-Specific Trust Store and Key Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can configure a client-specific trust store and key store using the
+``init()`` method of the ``SSLContext`` class.
+
+You can find an example showing how to configure a client with an ``SSLContext``
+instance in the
+:ref:`Customize TLS/SSL Configuration with an SSLContext section of this guide <tls-custom-sslContext>`.
+
+For more information on the ``SSLContext`` class, see the API
+documentation for `SSL Context <https://docs.oracle.com/en/java/javase/16/docs/api/java.base/javax/net/ssl/SSLContext.html>`__.
+
+Disable Hostname Verification
+-----------------------------
+
+By default, the driver ensures that the hostname included in the server's
+TLS/SSL certificates matches the hostnames provided when constructing
+a ``MongoClient``. To disable hostname verification for your
+application, you can explicitly disable this by setting the
+``invalidHostNameAllowed`` property of the builder to ``true`` in the
+``applytoSslSettings()`` builder lambda:
+
+.. literalinclude:: /includes/connect/tls.kt
+   :start-after: start-disable-hostname-verification
+   :end-before: end-disable-hostname-verification
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. warning::
+
+   Disabling hostname verification can make your configuration
+   `insecure <https://tlseminar.github.io/docs/mostdangerous.pdf>`__.
+   Disable hostname verification only for testing purposes or
+   when there is no other alternative.
+
+.. _tls-restrict-tls-1.2:
+
+Restrict Connections to TLS 1.2 Only
+------------------------------------
+
+To restrict your application to use only the TLS 1.2 protocol, set the
+``jdk.tls.client.protocols`` system property to "TLSv1.2".
+
+.. note::
+
+   Java Runtime Environments (JREs) before Java 8 only enabled
+   the TLS 1.2 protocol in update releases. If your JRE has not enabled
+   the TLS 1.2 protocol, upgrade to a later release to connect by using
+   TLS 1.2.
+
+.. _tls-custom-sslContext:
+
+Customize TLS/SSL Configuration through the Java SE SSLContext
+--------------------------------------------------------------
+
+If your TLS/SSL configuration requires customization, you can
+set the ``sslContext`` property of your ``MongoClient`` by
+passing an `SSLContext
+<https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html>`__
+object to the builder in the ``applyToSslSettings()`` lambda:
+
+.. literalinclude:: /includes/connect/tls.kt
+   :start-after: start-ssl-context
+   :end-before: end-ssl-context
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Online Certificate Status Protocol (OCSP)
+-----------------------------------------
+
+OCSP is a standard used to check whether X.509 certificates have been
+revoked. A certificate authority can add an X.509 certificate to the
+Certificate Revocation List (CRL) before the expiry time to invalidate
+the certificate. When a client sends an X.509 certificate during the TLS
+handshake, the CA's revocation server checks the CRL and returns a status
+of "good", "revoked", or "unknown".
+
+The driver supports the following variations of OCSP:
+
+- **Client-Driven OCSP**
+- **OCSP Stapling**
+
+The following sections describe the differences between them and how to enable
+them for your application.
+
+.. note::
+
+   The {+driver-short+} uses the JVM arguments configured for the application
+   and cannot be overridden for a specific ``MongoClient`` instance.
+
+Client-Driven OCSP
+~~~~~~~~~~~~~~~~~~
+
+In client-driven OCSP, the client sends the certificate in an OCSP request to
+an OCSP responder after receiving the certificate from the server. The OCSP
+responder checks the status of the certificate with a certificate
+authority (CA) and reports whether it's valid in a response sent to the
+client.
+
+To enable client-driven OCSP for your application, set the following JVM
+system properties:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Property
+     - Value
+
+   * - ``com.sun.net.ssl.checkRevocation``
+     - Set this property to ``true`` to enable revocation checking.
+
+   * - ``ocsp.enable``
+     - Set this property to ``true`` to enable client-driven OCSP.
+
+.. warning::
+
+   If the OCSP responder is unavailable, the TLS support provided by the
+   JDK reports a "hard fail". This differs from the "soft fail" behavior of
+   the MongoDB Shell and some other drivers.
+
+OCSP Stapling
+~~~~~~~~~~~~~
+
+OCSP stapling is a mechanism in which the server must obtain the signed
+certificate from the certificate authority (CA) and include it in a
+time-stamped OCSP response to the client.
+
+To enable OCSP stapling for your application, set the following JVM system
+properties:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Property
+     - Description
+
+   * - ``com.sun.net.ssl.checkRevocation``
+     - Set this property to ``true`` to enable revocation checking.
+
+   * - ``jdk.tls.client.enableStatusRequestExtension``
+     - | Set this property to ``true`` to enable OCSP stapling.
+       |
+       | If unset or set to ``false``, the connection can proceed regardless of the presence or status of the certificate revocation response.
+
+For more information about OCSP, check out the following resources:
+
+- Oracle JDK 8 Documentation on `how to enable OCSP for an application <https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ocsp.html>`__
+- :rfc:`Official IETF specification for OCSP (RFC 6960) <6960>`