Skip to content

Commit cdf7feb

Browse files
amalhotra-mdbamalhotra-mdb
authored
(DOCSP-43059) Connect to MongoDB > Configure TLS (#51)
* Connect to MongoDB > Configure TLS * reveal new child page in dropdown tree * build error * tls page content * code block render fix + edits * fix build errors * text edits * add fleshed out code examples and ref as includes * change structure to 'object' * fix code snipping * new fleshed out code example for ca file * get rid of extra spacing * remove cleanup goto * typos * consistency * destroy uri var * review changes * review changes * fix typo * link fix * link * toc * review changes
1 parent f143a5d commit cdf7feb

File tree

3 files changed

+335
-1
lines changed

3 files changed

+335
-1
lines changed

‎source/connect.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Connect to MongoDB
2525
/connect/mongoclient
2626
/connect/stable-api
2727
/connect/connection-targets
28-
.. /connect/tls
28+
/connect/tls
2929
.. /connect/server-selection
3030

3131
.. TODO, the rest of this root page will be filled out in DOCSP-43745, after

‎source/connect/tls.txt

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
.. c-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 :wikipedia:`TLS <Transport_Layer_Security>`
24+
protocol to secure your connection to a MongoDB deployment.
25+
26+
When you enable TLS for a connection, the {+driver-short+} performs the following actions:
27+
28+
- Uses TLS to connect to the MongoDB deployment
29+
- Verifies the deployment's certificate
30+
- Ensures that the certificate certifies the deployment
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+
MongoDB Server manual.
35+
36+
.. note::
37+
38+
A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and
39+
Certificate Authorities (CAs) is beyond the scope of this document. This page assumes prior
40+
knowledge of TLS/SSL and access to valid certificates.
41+
42+
.. _c-enable-tls:
43+
44+
Enable TLS
45+
----------
46+
47+
You can enable TLS on a connection to your MongoDB instance
48+
in the following ways:
49+
50+
- Setting the ``tls`` parameter in your connection string
51+
- Using the ``mongoc_uri_set_option_as_bool()`` function to set the ``MONGOC_URI_TLS`` connection
52+
option to ``true``
53+
54+
.. tabs::
55+
56+
.. tab:: Connection String
57+
:tabid: connectionstring
58+
59+
.. literalinclude:: /includes/connect/tls.c
60+
:language: c
61+
:start-after: start-connect-str
62+
:end-before: end-connect-str
63+
:dedent:
64+
65+
.. tab:: MongoC URI Options
66+
:tabid: mongocurioptions
67+
68+
.. literalinclude:: /includes/connect/tls.c
69+
:language: c
70+
:start-after: start-connect-uri-opt
71+
:end-before: end-connect-uri-opt
72+
:dedent:
73+
74+
.. tip::
75+
76+
If your connection string includes the ``+srv`` modification, which specifies the
77+
SRV connection format, TLS is enabled on your connection by default.
78+
79+
To learn more about the SRV connection format, see
80+
:manual:`SRV Connection Format </reference/connection-string/#srv-connection-format>`
81+
in the {+mdb-server+} documentation.
82+
83+
.. _c-specify-ca-file:
84+
85+
Specify a CA File
86+
------------------
87+
88+
When you connect to a MongoDB deployment with TLS enabled, the deployment will by default require the client to provide
89+
a client certificate issued by a certificate authority, or an authority
90+
trusted by the native certificate store in use on the server.
91+
92+
You can provide the client certificate in the following ways:
93+
94+
- Setting the ``tlscertificatekeyfile`` parameter in your connection string to a `.pem` file containing the root certificate chain
95+
- Using the `mongoc_uri_set_option_as_utf8()` function to set the `MONGOC_URI_TLSCERTIFICATEKEYFILE` option
96+
to a `.pem` file containing the root certificate chain
97+
98+
.. tabs::
99+
100+
.. tab:: Connection String
101+
:tabid: connectionstring
102+
103+
.. literalinclude:: /includes/connect/tls.c
104+
:language: c
105+
:start-after: start-connect-ca-file-str
106+
:end-before: end-connect-ca-file-str
107+
:dedent:
108+
109+
.. tab:: MongoC URI Options
110+
:tabid: mongocurioptions
111+
112+
.. literalinclude:: /includes/connect/tls.c
113+
:language: c
114+
:start-after: start-connect-ca-file-uri
115+
:end-before: end-connect-ca-file-uri
116+
:dedent:
117+
118+
.. _c-certificate-revocation:
119+
120+
Server Certificate Verification
121+
-------------------------------
122+
123+
The MongoDB C Driver will automatically verify the validity of a server certificate issued
124+
by the configured Certificate Authority. The driver also performs hostname validation and revocation checking.
125+
126+
To overwrite this behavior, it is possible to disable hostname validation, OCSP endpoint revocation checking,
127+
all revocation checking, and allow invalid certificates.
128+
129+
This behavior is controlled using the ``tlsAllowInvalidHostnames``, ``tlsDisableOCSPEndpointCheck``,
130+
``tlsDisableCertificateRevocationCheck``, and ``tlsAllowInvalidCertificates`` options. By default,
131+
all are set to ``false``.
132+
133+
It is not recommended to change these defaults, since you might expose your client to the following security risks:
134+
135+
- `Man In The Middle attacks <https://en.wikipedia.org/wiki/Man-in-the-middle_attack>`_, when
136+
``tlsAllowInvalidHostnames`` is set
137+
- Invalid certificates, when ``tlsAllowInvalidCertificates`` is set
138+
- Potentially revoked certificates, when ``tlsDisableOCSPEndpointCheck`` or ``tlsDisableCertificateRevocationCheck`` are set
139+
140+
Supported Libraries
141+
-------------------
142+
143+
By default, libmongoc will attempt to find a supported TLS library and enable TLS support. This is controlled
144+
by the cmake flag ``ENABLE_SSL``, which is set to ``AUTO`` by default. This flag accepts the following values:
145+
146+
- ``AUTO``: Links to the system's native TLS library, or attempts to find OpenSSL. This is the default value.
147+
- ``OPENSSL``: Links to OpenSSL (libssl). An optional install path may be specified with ``OPENSSL_ROOT``.
148+
- ``LIBRESSL`` (Deprecated): Links to LibreSSL's libtls. You can link to LibreSSL's compatible libssl by setting ``OPENSSL``.
149+
- ``WINDOWS``: Links to Secure Channel, the native TLS library on Windows.
150+
- ``DARWIN``: Links to Secure Transport, the native TLS library on macOS.
151+
- ``OFF``: Disables TLS support.
152+
153+
OpenSSL
154+
~~~~~~~
155+
156+
The MongoDB C Driver uses OpenSSL on Linux and Unix platforms (besides macOS). Industry best practices
157+
and some regulations require the use of TLS 1.1 or newer, which requires at least OpenSSL 1.0.1. Use the following command
158+
to check your OpenSSL version:
159+
160+
.. code-block:: bash
161+
162+
openssl version
163+
164+
Ensure your system's OpenSSL is a recent version (at least 1.0.1), or use the following command to install a recent version in a
165+
non-system path and build against it:
166+
167+
.. code-block:: bash
168+
169+
cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/openssl
170+
171+
When compiled against OpenSSL, the driver will attempt to load the system default certificate store, as configured by the
172+
distribution. That can be overridden by setting the ``tlsCAFile`` URI option or with the fields ``ca_file`` and ``ca_dir``
173+
in the `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__.
174+
175+
The Online Certificate Status Protocol (OCSP) is fully supported
176+
when using OpenSSL 1.0.1+. However, when a ``crl_file`` is set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ and the ``crl_file`` revokes
177+
the server's certificate, the certificate is considered revoked, even if the certificate has a valid stapled OCSP response.
178+
179+
.. tip::
180+
181+
For more information about OCSP, see `RFC 6960 <https://tools.ietf.org/html/rfc6960>`__.
182+
183+
LibreSSL / libtls (Deprecated)
184+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
185+
186+
The MongoDB C Driver supports LibreSSL through the use of OpenSSL compatibility checks when configured to compile against
187+
``openssl``. It also supports the new ``libtls`` library when configured to build against ``libressl``.
188+
189+
When compiled with LibreSSL, the ``crl_file`` option of a `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ is not supported,
190+
and will issue an error if used. Setting ``tlsDisableOCSPEndpointCheck`` and ``tlsDisableCertificateRevocationCheck`` has no effect.
191+
192+
The Online Certificate Status Protocol (OCSP) is partially supported
193+
with the following notes:
194+
195+
- Must-Staple extension (see `RFC 7633 <https://tools.ietf.org/html/rfc7633>`__) is ignored
196+
- Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down
197+
- Connection will not continue if the client receives a revoked response from an OCSP responder
198+
199+
.. tip::
200+
201+
For more information about OCSP, see `RFC 6960 <https://tools.ietf.org/html/rfc6960>`__.
202+
203+
Native TLS Support on Windows (Secure Channel)
204+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205+
206+
The MongoDB C Driver supports the Windows native TLS library (Secure Channel, or SChannel) and its native crypto library
207+
(Cryptography API: Next Generation, or CNG).
208+
209+
When compiled against the Windows native libraries, the ``ca_dir`` option of a `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ is not supported
210+
and will issue an error if used.
211+
212+
Encrypted PEM files, set by using the ``tlsCertificateKeyPassword`` URI option, are also not supported and will result in error when
213+
attempting to load them.
214+
215+
When ``tlsCAFile`` is set, the driver will only allow server certificates issued by one or more authorities provided.
216+
When no ``tlsCAFile`` is set, the driver will look up the Certificate Authority using the ``System Local Machine Root``
217+
certificate store to confirm the provided certificate.
218+
219+
When ``crl_file`` is set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__, the driver will import the revocation list to the
220+
``System Local Machine Root`` certificate store.
221+
222+
Setting ``tlsDisableOCSPEndpointCheck`` has no effect.
223+
224+
The Online Certificate Status Protocol (OCSP) is partially supported
225+
with the following notes:
226+
227+
- Must-Staple extension (see `RFC 7633 <https://tools.ietf.org/html/rfc7633>`__) is ignored.
228+
- Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down.
229+
- Connection will not continue if the client receives a revoked response from an OCSP responder.
230+
- When a ``crl_file`` is set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__, and the ``crl_file`` revokes the server's certificate, the OCSP response
231+
takes precedence. For example, if the server presents a certificate with a valid stapled OCSP response, the certificate is considered
232+
valid even if the ``crl_file`` marks it as revoked.
233+
234+
.. tip::
235+
236+
For more information about OCSP, see `RFC 6960 <https://tools.ietf.org/html/rfc6960>`__.
237+
238+
.. _secure-transport:
239+
240+
Native TLS Support on macOS / Darwin (Secure Transport)
241+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
242+
243+
The MongoDB C Driver supports both the Darwin native TLS library and Common Crypto, its native crypto
244+
library.
245+
246+
When compiled against Secure Transport, the ``ca_dir`` and ``crl_file`` options of a `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ are not supported.
247+
An error is issued if either are used.
248+
249+
When ``tlsCAFile`` is set, the driver will only allow server certificates issued by the authority (or authorities) provided.
250+
When no ``tlsCAFile`` is set, the driver will use the Certificate Authorities in the unlocked keychains.
251+
252+
Setting ``tlsDisableOCSPEndpointCheck`` and ``tlsDisableCertificateRevocationCheck`` has no effect when compiling against secure transport.
253+
254+
The Online Certificate Status Protocol (OCSP) is partially supported
255+
with the following notes.
256+
257+
- Must-Staple extension (see `RFC 7633 <https://tools.ietf.org/html/rfc7633>`__) is ignored
258+
- Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down
259+
- Connection will not continue if the client receives a revoked response from an OCSP responder
260+
261+
.. tip::
262+
263+
For more information about OCSP, see `RFC 6960 <https://tools.ietf.org/html/rfc6960>`__.
264+
265+
API Documentation
266+
-----------------
267+
268+
For more information about the objects and functions mentioned in this guide, see
269+
the following API documentation:
270+
271+
- `mongoc_uri_t <https://mongoc.org/libmongoc/current/mongoc_uri_t.html>`__
272+
- `mongoc_uri_set_option_as_bool() <https://mongoc.org/libmongoc/current/mongoc_uri_set_option_as_bool.html>`__

‎source/includes/connect/tls.c

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#include <mongoc/mongoc.h>
2+
#include <bson/bson.h>
3+
4+
int main (void) {
5+
6+
mongoc_init ();
7+
8+
{
9+
// Set TLS using connection string
10+
// start-connect-str
11+
mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true");
12+
13+
// Do database work here
14+
15+
mongoc_client_destroy (client);
16+
// end-connect-str
17+
}
18+
19+
{
20+
// Set TLS using connection uri options
21+
// start-connect-uri-opt
22+
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017");
23+
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
24+
25+
mongoc_client_t *client = mongoc_client_new_from_uri (uri);
26+
27+
// Do database work here
28+
29+
mongoc_client_destroy (client);
30+
mongoc_uri_destroy (uri);
31+
// end-connect-uri-opt
32+
}
33+
34+
{
35+
// Set TLS and provide CA file using connection string
36+
// start-connect-ca-file-str
37+
mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true&tlscertificatekeyfile=/path/to/certs/client-certificate.pem");
38+
39+
// Do database work here
40+
41+
mongoc_client_destroy (client);
42+
// end-connect-ca-file-str
43+
}
44+
45+
{
46+
// Set TLS and provide CA file using uri options
47+
// start-connect-ca-file-uri
48+
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017");
49+
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
50+
mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "/path/to/client-certificate.pem");
51+
52+
mongoc_client_t *client = mongoc_client_new_from_uri (uri);
53+
54+
// Do database work here
55+
56+
mongoc_client_destroy (client);
57+
mongoc_uri_destroy (uri);
58+
// end-connect-ca-file-uri
59+
}
60+
61+
mongoc_cleanup ();
62+
}

0 commit comments

Comments
 (0)