Skip to content

Commit 626ef2e

Browse files
mcmorisimcmorisi
authored
DOCSP-41508: TLS (mongodb#37)
1 parent d45f795 commit 626ef2e

File tree

3 files changed

+377
-4
lines changed

3 files changed

+377
-4
lines changed

‎source/connect.txt

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ Connect to MongoDB
2525
/connect/mongoclient
2626
/connect/connection-targets
2727
/connect/connection-options
28+
/connect/tls
2829
/connect/stable-api
2930

30-
.. /connect/tls
3131
.. /connect/network-compression
3232
.. /connect/server-selection
3333
.. /connect/csot
@@ -102,7 +102,8 @@ Transport Layer Security (TLS)
102102
------------------------------
103103

104104
The following sections describe how to connect to MongoDB
105-
while enabling the TLS protocol.
105+
while enabling the TLS protocol. To learn more about using TLS with the {+driver-short+},
106+
see :ref:`kotlin-sync-tls`.
106107

107108
Enable TLS
108109
~~~~~~~~~~
@@ -111,8 +112,8 @@ The following tabs demonstrate how to enable TLS on a connection:
111112

112113
.. include:: /includes/connect/tls-tabs.rst
113114

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

117118
Disable Hostname Verification
118119
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎source/connect/tls.txt

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

0 commit comments

Comments
 (0)