Skip to content

Commit e9ead1c

Browse files
lindseymoorelindseymoore
authoredJan 17, 2025
DOCSP-45179 Configure TLS (#129)
* Configure TLS * insecure tls * edits * monospace * 1/2 MW edits * last of MW revisions and table * table reformat * spacing edit * formatting edits * format * edit * MW last comments * small change * tech review
1 parent 76c5922 commit e9ead1c

File tree

3 files changed

+368
-0
lines changed

3 files changed

+368
-0
lines changed
 

‎source/connect.txt

+1
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,4 @@ Connect to MongoDB
2525
Create a Client </connect/mongoclient>
2626
Stable API </connect/stable-api>
2727
Choose a Connection Target </connect/connection-targets>
28+
Configure TLS </connect/tls>

‎source/connect/tls.txt

+326
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
.. _ruby-tls:
2+
3+
========================================
4+
Configure Transport Layer Security (TLS)
5+
========================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: security, authentication, transport layer security, encrypt
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the Transport Layer Security (TLS)
24+
protocol to secure your connection to a MongoDB deployment.
25+
26+
To connect to a MongoDB deployment using TLS, you must perform the following steps:
27+
28+
- Enable a TLS connection in ``Mongo::Client``.
29+
- Specify the client TLS certificate.
30+
- Specify the Certificate Authority (CA) certificate to verify the server's TLS certificate.
31+
32+
To learn how to configure your MongoDB deployment for TLS, see the
33+
:manual:`TLS configuration guide </tutorial/configure-ssl/>` in the
34+
{+mdb-server+} manual.
35+
36+
.. note::
37+
38+
This page assumes prior knowledge of TLS/SSL and access to valid certificates.
39+
A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and
40+
CAs is beyond the scope of this documentation. To learn more about TLS, see the
41+
Wikipedia entry for :wikipedia:`Transport Layer Security <Transport_Layer_Security>`.
42+
43+
.. _ruby-enable-tls:
44+
45+
Enable TLS
46+
----------
47+
48+
You can enable TLS for the connection to your MongoDB deployment in the following ways:
49+
50+
- Set the ``ssl`` option to ``true`` in a new ``Mongo:Client`` object.
51+
- Set the ``tls`` option to ``true`` in your connection string.
52+
53+
.. note:: SSL Naming Convention
54+
55+
All {+mdb-server+} versions supported by the {+driver-short+} v2.6 and later
56+
implement only TLS. 2.6 and do not use SSL.
57+
58+
For historical reasons, the Ruby driver prefixes TLS options with ``ssl``
59+
instead of ``tls``. {+driver-short+} version 3.0 and later will use the
60+
``tls`` prefix for Ruby option names.
61+
62+
.. tabs::
63+
64+
.. tab:: Mongo::Client
65+
:tabid: mongoclient
66+
67+
To configure certificates, you must specify the following options:
68+
69+
- ``ssl_cert``: The certificate file used to verify the connection to
70+
a MongoDB deployment.
71+
- ``ssl_key``: The private keyfile used to verify the connection to
72+
a MongoDB deployment.
73+
- ``ssl_ca_cert``: The file containing the concatenated CA certificates
74+
used to validate certificates passed from the MongoDB deployment to the
75+
client. If you don't specify a value for this option, the driver uses
76+
the default system root certificate store as the trust anchor.
77+
78+
In the following example, the TLS certificate and corresponding private key
79+
are provided in separate files:
80+
81+
.. literalinclude:: /includes/connect/tls.rb
82+
:language: ruby
83+
:dedent:
84+
:start-after: start-enable-tls-settings
85+
:end-before: end-enable-tls-settings
86+
87+
You can specify both the TLS certificate and private key in a single file, but
88+
both the certificate and private key options must still be specified. In the
89+
following example, the TLS certificate and the private key are both defined
90+
in the same ``client.pem`` file:
91+
92+
.. literalinclude:: /includes/connect/tls.rb
93+
:language: ruby
94+
:dedent:
95+
:start-after: start-enable-tls-settings-same-file
96+
:end-before: end-enable-tls-settings-same-file
97+
98+
.. tab:: Connection String
99+
:tabid: uri
100+
101+
To configure certificates, you must specify the following URI options:
102+
103+
- ``tlsCertificateKeyFile``: The file that contains the certificate and keyfile
104+
used to verify the connection to a MongoDB deployment.
105+
- ``tlsCAFile``: The file containing the concatenated CA certificates
106+
used to validate certificates passed from the MongoDB deployment to the
107+
client. If you don't specify a value for this option, the driver uses
108+
the default system root certificate store as the trust anchor.
109+
110+
.. literalinclude:: /includes/connect/tls.rb
111+
:language: ruby
112+
:dedent:
113+
:start-after: start-enable-tls-uri
114+
:end-before: end-enable-tls-uri
115+
116+
The file containing the certificate and key usually has a``.crt`` or ``.pem``
117+
extension.
118+
119+
URI option values must be percent-encoded. This applies, for example,
120+
to slashes (/) in the paths, which are encoded as ``%2f``.
121+
122+
Specify Client TLS Certificates
123+
-------------------------------
124+
125+
The {+driver-short+} provides multiple options for you to specify
126+
the TLS certificate, key, and CA certificate with different data or object types.
127+
128+
TLS Certificate
129+
~~~~~~~~~~~~~~~
130+
131+
You can provide one of the following options to specify the TLS certificate:
132+
133+
.. list-table::
134+
:header-rows: 1
135+
:widths: 20 30 50
136+
137+
* - Option Name
138+
- Data/Object Type Accepted
139+
- Description
140+
* - ``:ssl_cert``
141+
- ``String``
142+
- The certificate file path used to verify the connection to a MongoDB
143+
deployment.
144+
* - ``:ssl_cert_object``
145+
- ``OpenSSL::X509::Certificate``
146+
- The certificate object used to verify the connection to a MongoDB
147+
deployment.
148+
* - ``:ssl_cert_string``
149+
- ``String``
150+
- A string containing the PEM-encoded certificate used to verify the connection to
151+
a MongoDB deployment.
152+
153+
TLS Private Key
154+
~~~~~~~~~~~~~~~
155+
156+
You can provide one of the following options to specify the TLS private key:
157+
158+
.. list-table::
159+
:header-rows: 1
160+
:widths: 20 30 50
161+
162+
* - Option Name
163+
- Data/Object Type Accepted
164+
- Description
165+
* - ``:ssl_key``
166+
- ``String``
167+
- The private keyfile path used to verify the connection to a MongoDB
168+
deployment.
169+
* - ``:ssl_key_object``
170+
- ``OpenSSL::PKey``
171+
- The private key object used to verify the connection to a MongoDB
172+
deployment.
173+
* - ``:ssl_key_pass_phrase``
174+
- ``String``
175+
- A passphrase for the private key.
176+
* - ``:ssl_key_string``
177+
- ``String``
178+
- A string containing the PEM-encoded private key used to verify the
179+
connection to a MongoDB deployment.
180+
181+
TLS CA Certificate
182+
~~~~~~~~~~~~~~~~~~
183+
184+
You can provide one of the following options to specify the TLS CA certificate:
185+
186+
.. list-table::
187+
:header-rows: 1
188+
:widths: 20 30 50
189+
190+
* - Option Name
191+
- Data/Object Type Accepted
192+
- Description
193+
* - ``:ssl_ca_cert``
194+
- ``String``
195+
- The file path containing concatenated CA certificates used to validate certificates
196+
passed from the MongoDB deployment to the client.
197+
* - ``:ssl_ca_cert_object``
198+
- ``Array<OpenSSL::X509::Certificate>``
199+
- An array of objects representing the CA certificates used
200+
to validate certificates passed from the MongoDB deployment to the client.
201+
* - ``:ssl_ca_cert_string``
202+
- ``String``
203+
- A string containing one PEM-encoded CA certificate used to validate certificates
204+
passed from the MongoDB deployment to the client.
205+
206+
Modify the TLS Context
207+
----------------------
208+
209+
If your TLS configuration requires customization, you can set TLS context hooks
210+
by adding a native Ruby ``Proc`` object to the ``Mongo.tls_context_hooks``
211+
array. Add the ``Proc`` object to the array before you create any ``Mongo::Client``
212+
instances.
213+
214+
The following code example enables the AES256-SHA cipher as the only cipher
215+
to be used for TLS:
216+
217+
.. literalinclude:: /includes/connect/tls.rb
218+
:language: ruby
219+
:dedent:
220+
:start-after: start-modify-context
221+
:end-before: end-modify-context
222+
223+
The {+driver-short+} TLS context options are based on native Ruby handling of SSL. To
224+
learn more about the TLS context options available, see the Ruby
225+
documentation for
226+
`SSLContext <https://ruby-doc.org/3.2.6/exts/openssl/OpenSSL/SSL/SSLContext.html>`__.
227+
228+
OCSP Verification
229+
-----------------
230+
231+
If the certificate provided by the server contains an OCSP endpoint URI,
232+
the driver issues an Online Certificate Status Protocol (OCSP) request to
233+
the specified endpoint by default to verify the validity of the certificate.
234+
235+
To disable the OCSP endpoint check, set the ``:ssl_verify_ocsp_endpoint``
236+
Ruby option to ``false`` or set the ``tlsDisableOCSPEndpointCheck`` URI option
237+
to ``true`` when creating a client.
238+
239+
.. note:: JRuby Does Not Support OCSP Verification
240+
241+
Because JRuby does not correctly expose OCSP endpoint URIs,
242+
the driver does not check OCSP endpoints when the underlying
243+
application runs on JRuby.
244+
245+
Allow Insecure TLS
246+
------------------
247+
248+
When TLS is enabled, the {+driver-short+} automatically verifies the certificate that
249+
the server presents. When testing your code, you can disable this verification.
250+
This is known as **insecure TLS**.
251+
252+
When insecure TLS is enabled, the driver requires only that the server present an
253+
X.509 certificate. The driver accepts a certificate even if any of the following are
254+
true:
255+
256+
- The hostname of the server and the subject name (or subject alternative name)
257+
on the certificate don't match.
258+
- The certificate is expired or not yet valid.
259+
- The certificate doesn't have a trusted root certificate in the chain.
260+
- The certificate purpose isn't valid for server identification.
261+
262+
.. note::
263+
264+
Even when insecure TLS is enabled, communication between the client and server
265+
is encrypted with TLS.
266+
267+
To enable insecure TLS, set the ``sslVerify`` client option or the ``tlsInsecure``
268+
URI option to ``true``:
269+
270+
.. tabs::
271+
272+
.. tab:: Mongo::Client
273+
:tabid: mongoclient
274+
275+
.. literalinclude:: /includes/connect/tls.rb
276+
:language: ruby
277+
:dedent:
278+
:start-after: start-ssl-verify
279+
:end-before: end-ssl-verify
280+
281+
.. tab:: Connection String
282+
:tabid: uri
283+
284+
.. literalinclude:: /includes/connect/tls.rb
285+
:language: ruby
286+
:dedent:
287+
:start-after: start-tls-insecure
288+
:end-before: end-tls-insecure
289+
290+
You can similarly set the following options to disable verification for the
291+
certificate or hostname:
292+
293+
.. tabs::
294+
295+
.. tab:: Mongo::Client
296+
:tabid: mongoclient
297+
298+
- ``ssl_verify_certificate``: Disable certificate validation by setting the
299+
option to ``false``.
300+
- ``ssl_verify_hostname``: Disable hostname verification by setting the option
301+
to ``false``.
302+
303+
.. tab:: Connection String
304+
:tabid: uri
305+
306+
- ``tlsAllowInvalidCertificates``: Disable certificate validation by setting
307+
the option to ``true``.
308+
- ``tlsAllowInvalidHostnames``: Disable hostname validation by setting
309+
the option to ``true``.
310+
311+
.. warning:: Don't Use Insecure TLS in Production
312+
313+
Always disable insecure TLS in production.
314+
315+
Enabling insecure TLS in a production environment makes your application
316+
insecure and potentially vulnerable to expired certificates and foreign
317+
processes posing as valid client instances.
318+
319+
API Documentation
320+
-----------------
321+
322+
For more information about any of the types and methods discussed in this guide,
323+
see the following API documentation:
324+
325+
- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__
326+
- `tls_context_hooks <{+api-root+/Mongo.html#tls_context_hooks-class_method}>`__

‎source/includes/connect/tls.rb

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# start-enable-tls-settings
2+
client = Mongo::Client.new(["<hostname>:<port>"],
3+
ssl: true,
4+
ssl_cert: 'path/to/client.crt',
5+
ssl_key: 'path/to/client.key',
6+
ssl_ca_cert: 'path/to/ca.crt'
7+
)
8+
# end-enable-tls-settings
9+
10+
# start-enable-tls-settings-same-file
11+
client = Mongo::Client.new(["<hostname>:<port>"],
12+
ssl: true,
13+
ssl_cert: 'path/to/client.pem',
14+
ssl_key: 'path/to/client.pem',
15+
ssl_ca_cert: 'path/to/ca.crt',
16+
)
17+
# end-enable-tls-settings-same-file
18+
19+
# start-enable-tls-uri
20+
client = Mongo::Client.new(
21+
"mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=path%2fto%2fclient.pem&tlsCAFile=path%2fto%2fca.crt")
22+
# end-enable-tls-uri
23+
24+
# start-modify-context
25+
Mongo.tls_context_hooks.push(
26+
Proc.new { |context|
27+
context.ciphers = ["AES256-SHA"]
28+
}
29+
)
30+
# end-modify-context
31+
32+
# start-ssl-verify
33+
client = Mongo::Client.new(["<hostname>:<port>"],
34+
ssl: true,
35+
ssl_verify: false
36+
)
37+
# end-ssl-verify
38+
39+
# start-tls-insecure
40+
client = Mongo::Client.new('mongodb://<hostname>:<port>/?tls=true&tlsInsecure=true')
41+
# end-tls-insecure

0 commit comments

Comments
 (0)