Skip to content

Commit 4fced55

Browse files
mcmorisimcmorisi
committed
DOCSP-41508: TLS
1 parent 7c1c3ec commit 4fced55

File tree

3 files changed

+386
-3
lines changed

3 files changed

+386
-3
lines changed

‎source/connect.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,10 @@ Connect to MongoDB
2424

2525
/connect/stable-api
2626
/connect/connection-targets
27+
/connect/tls
2728

2829
.. /connect/mongoclient
2930
.. /connect/connection-options
30-
.. /connect/tls
3131
.. /connect/network-compression
3232
.. /connect/server-selection
3333
.. /connect/csot
@@ -111,8 +111,8 @@ The following tabs demonstrate how to enable TLS on a connection:
111111

112112
.. include:: /includes/connect/tls-tabs.rst
113113

114-
.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in
115-
.. the TLS configuration guide.
114+
To learn more about enabling TLS, see :ref:`tls-enable` in
115+
the TLS configuration guide.
116116

117117
Disable Hostname Verification
118118
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎source/connect/tls.txt

Lines changed: 340 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,340 @@
1+
.. _kotlin-sync-enable-tls:
2+
3+
==============================
4+
Enable TLS/SSL on a Connection
5+
==============================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, security, authentication
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to connect to MongoDB instances with the
24+
`TLS/SSL <https://en.wikipedia.org/wiki/Transport_Layer_Security>`__
25+
security protocol using the underlying TLS/SSL support in the JDK. To
26+
configure your connection to use TLS/SSL, enable the TLS/SSL settings in
27+
either the `ConnectionString <{+core-api+}/com/mongodb/ConnectionString.html>`__
28+
or `MongoClientSettings <{+core-api+}/com/mongodb/MongoClientSettings.html>`__.
29+
30+
.. note:: Debugging TLS/SSL
31+
32+
If you experience trouble setting up your TLS/SSL connection, you can
33+
use the ``-Djavax.net.debug=all`` system property to view more
34+
log statements. See `the Oracle guide to debugging TLS/SSL connections
35+
<https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html>`__
36+
for more information.
37+
38+
.. _tls-enable:
39+
40+
Enable TLS/SSL
41+
--------------
42+
43+
You can enable TLS/SSL for the connection to your MongoDB instance
44+
in two different ways: through a parameter in your connection string, or
45+
using a method in the ``MongoClientSettings.Builder`` class.
46+
47+
.. note:: DNS Seedlist Protocol Enables TLS
48+
49+
If you connect by using the DNS seedlist protocol, indicated by the
50+
``mongodb+srv`` prefix in your connection string, the driver
51+
automatically enables TLS/SSL. To disable it, set the ``tls``
52+
parameter value to ``false`` in your connection string, or set the
53+
``enabled`` property to ``false`` in the ``SslSettings.Builder``
54+
block when creating a ``MongoClientSettings`` instance.
55+
56+
To learn more about connection behavior when you use a DNS seedlist,
57+
see the :manual:`SRV Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`
58+
section in the Server manual.
59+
60+
.. tabs::
61+
62+
.. tab:: ConnectionString
63+
:tabid: connectionstring
64+
65+
To enable TLS/SSL on a connection with a `ConnectionString
66+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__, assign the connection string
67+
parameter ``tls`` a value of ``true`` in the connection string passed to
68+
``MongoClient.create()``:
69+
70+
.. literalinclude:: /includes/connect/tls.kt
71+
:start-after: start-tls-connection-string
72+
:end-before: end-tls-connection-string
73+
:language: kotlin
74+
:copyable:
75+
:dedent:
76+
77+
.. tab:: MongoClientSettings
78+
:tabid: mongoclientsettings
79+
80+
To configure your ``MongoClient``'s TLS/SSL connection options using the
81+
``MongoClientSettings.Builder`` class, call the
82+
`applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__
83+
method. Set the ``enabled`` property to ``true`` in the ``SslSettings.Builder``
84+
block to enable TLS/SSL:
85+
86+
.. literalinclude:: /includes/connect/tls.kt
87+
:start-after: start-tls-mongo-client-settings
88+
:end-before: end-tls-mongo-client-settings
89+
:language: kotlin
90+
:copyable:
91+
:dedent:
92+
93+
.. _tls_configure-certificates:
94+
95+
Configure Certificates
96+
----------------------
97+
98+
{+language+} applications that initiate TLS/SSL requests require access to
99+
cryptographic certificates that prove identity for the application
100+
itself and other applications with which the application
101+
interacts. You can configure access to these certificates in your application with
102+
the following mechanisms:
103+
104+
- The JVM trust store and JVM key store
105+
- A client-specific trust store and key store
106+
107+
.. note::
108+
109+
The following sections are based on the documentation for Oracle JDK,
110+
so some parts may be inapplicable to your JDK or to the custom TLS/SSL
111+
implementation you use.
112+
113+
.. _tls-configure-jvm-truststore:
114+
115+
Configure the JVM Trust Store
116+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117+
118+
.. note::
119+
120+
By default, the JRE includes many commonly used public certificates
121+
from signing authorities like `Let's Encrypt
122+
<https://letsencrypt.org/>`__. As a result, you can connect to
123+
instances of :atlas:`MongoDB Atlas </?jmp=docs_driver_kotlin>` (or any other
124+
server whose certificate is signed by an authority in the JRE's default
125+
certificate store) with TLS/SSL without configuring the trust store.
126+
127+
The JVM trust store saves certificates that securely identify other
128+
applications with which your {+language+} application interacts. Using these
129+
certificates, your application can prove that the connection to another
130+
application is genuine and secure from tampering by third parties.
131+
132+
If your MongoDB instance uses a certificate that is signed by an
133+
authority that is not present in the JRE's default certificate store,
134+
your application must configure two system properties to initiate
135+
SSL/TLS requests. These properties ensure that your application can
136+
validate the TLS/SSL certificate presented by a connected MongoDB instance.
137+
138+
- ``javax.net.ssl.trustStore``: the path to a trust store containing the
139+
certificate of the signing authority
140+
141+
- ``javax.net.ssl.trustStorePassword``: the password to access the trust
142+
store defined in ``javax.net.ssl.trustStore``
143+
144+
You can create a trust store with the `keytool
145+
<https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html>`__
146+
command line tool provided as part of the JDK:
147+
148+
.. code-block:: console
149+
150+
keytool -importcert -trustcacerts -file <path to certificate authority file>
151+
-keystore <path to trust store> -storepass <password>
152+
153+
Configure the JVM Key Store
154+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
155+
156+
.. note::
157+
158+
By default, MongoDB instances do not perform client certificate
159+
validation. You must configure the key store if you configured your MongoDB
160+
instance to validate client certificates.
161+
162+
The JVM key store saves certificates that securely identify your Kotlin
163+
application to other applications. Using these certificates, other
164+
applications can prove that the connection to your application is
165+
genuine and secure from tampering by third parties.
166+
167+
An application that initiates TLS/SSL requests needs to set two JVM system
168+
properties to ensure that the client presents a TLS/SSL certificate to
169+
the MongoDB server:
170+
171+
- ``javax.net.ssl.keyStore``: the path to a key store containing the client's
172+
TLS/SSL certificates
173+
174+
- ``javax.net.ssl.keyStorePassword``: the password to access the key store
175+
defined in ``javax.net.ssl.keyStore``
176+
177+
You can create a key store with the `keytool
178+
<https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html>`__
179+
or `openssl <https://www.openssl.org/docs/manmaster/man1/openssl.html>`__
180+
command line tool.
181+
182+
For more information on configuring a Kotlin application to use TLS/SSL,
183+
please see the `JSSE Reference Guide
184+
<https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html>`__.
185+
186+
.. _tls-disable-hostname-verification:
187+
188+
Configure a Client-Specific Trust Store and Key Store
189+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190+
191+
You can configure a client-specific trust store and key store using the
192+
``init()`` method of the ``SSLContext`` class.
193+
194+
You can find an example showing how to configure a client with an ``SSLContext``
195+
instance in the
196+
:ref:`Customize TLS/SSL Configuration with an SSLContext section of this guide <tls-custom-sslContext>`.
197+
198+
For more information on the ``SSLContext`` class, see the API
199+
documentation for `SSL Context <https://docs.oracle.com/en/java/javase/16/docs/api/java.base/javax/net/ssl/SSLContext.html>`__.
200+
201+
Disable Hostname Verification
202+
-----------------------------
203+
204+
By default, the driver ensures that the hostname included in the server's
205+
TLS/SSL certificates matches the hostnames provided when constructing
206+
a ``MongoClient``. To disable hostname verification for your
207+
application, you can explicitly disable this by setting the
208+
``invalidHostNameAllowed`` property of the builder to ``true`` in the
209+
``applytoSslSettings()`` builder lambda:
210+
211+
.. literalinclude:: /includes/connect/tls.kt
212+
:start-after: start-disable-hostname-verification
213+
:end-before: end-disable-hostname-verification
214+
:language: kotlin
215+
:copyable:
216+
:dedent:
217+
218+
.. warning::
219+
220+
Disabling hostname verification can make your configuration
221+
`insecure <https://tlseminar.github.io/docs/mostdangerous.pdf>`__.
222+
Disable hostname verification only for testing purposes or
223+
when there is no other alternative.
224+
225+
.. _tls-restrict-tls-1.2:
226+
227+
Restrict Connections to TLS 1.2 Only
228+
------------------------------------
229+
230+
To restrict your application to use only the TLS 1.2 protocol, set the
231+
``jdk.tls.client.protocols`` system property to "TLSv1.2".
232+
233+
.. note::
234+
235+
Java Runtime Environments (JREs) before Java 8 only enabled
236+
the TLS 1.2 protocol in update releases. If your JRE has not enabled
237+
the TLS 1.2 protocol, upgrade to a later release to connect by using
238+
TLS 1.2.
239+
240+
.. _tls-custom-sslContext:
241+
242+
Customize TLS/SSL Configuration through the Java SE SSLContext
243+
--------------------------------------------------------------
244+
245+
If your TLS/SSL configuration requires customization, you can
246+
set the ``sslContext`` property of your ``MongoClient`` by
247+
passing an `SSLContext
248+
<https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html>`__
249+
object to the builder in the ``applyToSslSettings()`` lambda:
250+
251+
.. literalinclude:: /includes/connect/tls.kt
252+
:start-after: start-ssl-context
253+
:end-before: end-ssl-context
254+
:language: kotlin
255+
:copyable:
256+
:dedent:
257+
258+
Online Certificate Status Protocol (OCSP)
259+
-----------------------------------------
260+
261+
OCSP is a standard used to check whether X.509 certificates have been
262+
revoked. A certificate authority can add an X.509 certificate to the
263+
Certificate Revocation List (CRL) before the expiry time to invalidate
264+
the certificate. When a client sends an X.509 certificate during the TLS
265+
handshake, the CA's revocation server checks the CRL and returns a status
266+
of "good", "revoked", or "unknown".
267+
268+
The driver supports the following variations of OCSP:
269+
270+
- **Client-Driven OCSP**
271+
- **OCSP Stapling**
272+
273+
The following sections describe the differences between them and how to enable
274+
them for your application.
275+
276+
.. note::
277+
278+
The {+driver-short+} uses the JVM arguments configured for the application
279+
and cannot be overridden for a specific ``MongoClient`` instance.
280+
281+
Client-Driven OCSP
282+
~~~~~~~~~~~~~~~~~~
283+
284+
In client-driven OCSP, the client sends the certificate in an OCSP request to
285+
an OCSP responder after receiving the certificate from the server. The OCSP
286+
responder checks the status of the certificate with a certificate
287+
authority (CA) and reports whether it's valid in a response sent to the
288+
client.
289+
290+
To enable client-driven OCSP for your application, set the following JVM
291+
system properties:
292+
293+
.. list-table::
294+
:header-rows: 1
295+
:widths: 35 65
296+
297+
* - Property
298+
- Value
299+
300+
* - ``com.sun.net.ssl.checkRevocation``
301+
- Set this property to ``true`` to enable revocation checking.
302+
303+
* - ``ocsp.enable``
304+
- Set this property to ``true`` to enable client-driven OCSP.
305+
306+
.. warning::
307+
308+
If the OCSP responder is unavailable, the TLS support provided by the
309+
JDK reports a "hard fail". This differs from the "soft fail" behavior of
310+
the MongoDB Shell and some other drivers.
311+
312+
OCSP Stapling
313+
~~~~~~~~~~~~~
314+
315+
OCSP stapling is a mechanism in which the server must obtain the signed
316+
certificate from the certificate authority (CA) and include it in a
317+
time-stamped OCSP response to the client.
318+
319+
To enable OCSP stapling for your application, set the following JVM system
320+
properties:
321+
322+
.. list-table::
323+
:header-rows: 1
324+
:widths: 50 50
325+
326+
* - Property
327+
- Description
328+
329+
* - ``com.sun.net.ssl.checkRevocation``
330+
- Set this property to ``true`` to enable revocation checking.
331+
332+
* - ``jdk.tls.client.enableStatusRequestExtension``
333+
- | Set this property to ``true`` to enable OCSP stapling.
334+
|
335+
| If unset or set to ``false``, the connection can proceed regardless of the presence or status of the certificate revocation response.
336+
337+
For more information about OCSP, check out the following resources:
338+
339+
- 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>`__
340+
- :rfc:`Official IETF specification for OCSP (RFC 6960) <6960>`

0 commit comments

Comments
 (0)