Skip to content

Commit 1ac6625

Browse files
rustagirrustagir
committed
DOCSP-30527: tls guide (#96)
(cherry picked from commit dca5c09)
1 parent 4334f1b commit 1ac6625

File tree

4 files changed

+249
-5
lines changed

4 files changed

+249
-5
lines changed

‎source/fundamentals/connections.txt

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ Connections
99
/fundamentals/connections/connection-guide
1010
/fundamentals/connections/connection-options
1111
/fundamentals/connections/network-compression
12+
/fundamentals/connections/tls
1213

1314
..
14-
/fundamentals/connections/tls
1515
Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
1616

1717
.. contents:: On this page
@@ -29,11 +29,11 @@ connection to a MongoDB deployment in the following sections:
2929
- :ref:`Connection Guide <rust-connect-to-mongodb>`
3030
- :ref:`Connection Options <rust-connection-options>`
3131
- :ref:`Enable Network Compression <rust-network-compression>`
32+
- :ref:`Enable and Configure TLS <rust-connect-tls>`
3233

33-
.. - :ref:`Enable TLS on a Connection <rust-connect-tls>`
3434
.. - :atlas:`Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
3535

36-
.. To learn how to authenticate to MongoDB, see the following pages:
36+
To learn how to authenticate to MongoDB, see the following guides:
3737

38-
.. - :ref:`rust-authentication-mechanisms`
39-
.. - :ref:`rust-enterprise-authentication-mechanisms`
38+
- :ref:`rust-authentication`
39+
- :ref:`rust-enterprise-auth`

‎source/fundamentals/connections/network-compression.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,6 +197,9 @@ documentation:
197197
API Documentation
198198
~~~~~~~~~~~~~~~~~
199199

200+
To learn more about any of the methods or types mentioned in this
201+
guide, see the following API documentation:
202+
200203
- `Client <{+api+}/struct.Client.html>`__
201204
- `with_uri_str() <{+api+}/struct.Client.html#method.with_uri_str>`__
202205
- `parse() <{+api+}/options/struct.ClientOptions.html#method.parse>`__

‎source/fundamentals/connections/tls.txt

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
.. _rust-connect-tls:
2+
3+
========================
4+
Enable and Configure TLS
5+
========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, security, connection options
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 **TLS protocol** to secure
24+
your connection to a MongoDB deployment. TLS is a cryptographic protocol
25+
that secures communication between your application and MongoDB. To
26+
configure your connection to use TLS, enable the TLS option and provide
27+
your certificates for validation when creating a client.
28+
29+
This guide includes the following sections:
30+
31+
- :ref:`Enable TLS <rust-enable-tls>` describes ways to enable TLS on
32+
your connection
33+
34+
- :ref:`Configure Certificates <rust-configure-tls-certificates>`
35+
describes the certificates required to configure TLS
36+
37+
- :ref:`Reference Certificates in a Client <rust-client-tls-connect>`
38+
provides an example of how to create a ``TlsOptions`` struct to configure your
39+
TLS options
40+
41+
- :ref:`Additional Information <rust-tls-addtl-info>`
42+
provides links to resources and API documentation for types
43+
and methods mentioned in this guide
44+
45+
.. tip::
46+
47+
To learn more about TLS, see the Wikipedia entry on
48+
:wikipedia:`Transport Layer Security <w/index.php?title=Transport_Layer_Security&oldid=1184063676>`.
49+
50+
.. _rust-enable-tls:
51+
52+
Enable TLS
53+
----------
54+
55+
You can enable TLS on a connection to your MongoDB instance
56+
in one of the following ways:
57+
58+
- Setting the ``tls`` option to ``true`` in your connection string
59+
- Setting the ``tls`` field of a ``ClientOptions`` instance to
60+
the ``Tls::Enabled`` variant with an empty ``TlsOptions`` struct and
61+
instantiating a ``Client`` with those options
62+
63+
Select from the following :guilabel:`Connection String` and
64+
:guilabel:`ClientOptions` tabs to see a corresponding code sample:
65+
66+
.. tabs::
67+
68+
.. tab:: Connection String
69+
:tabid: connection string tls true
70+
71+
.. code-block:: rust
72+
:emphasize-lines: 1
73+
74+
let uri = "mongodb://<hostname>:<port>?tls=true"
75+
let client = Client::with_uri_str(uri).await?;
76+
77+
.. tab:: ClientOptions
78+
:tabid: clientoptions tls true
79+
80+
.. code-block:: rust
81+
:emphasize-lines: 4-5
82+
83+
let uri = "<connection string>"
84+
let mut client_options = ClientOptions::parse(uri).await?;
85+
86+
let tls_opts = TlsOptions::builder().build();
87+
client_options.tls = Some(Tls::Enabled(tls_opts));
88+
89+
let client = Client::with_options(client_options)?;
90+
91+
.. note::
92+
93+
If your connection string uses a DNS SRV record by including
94+
the ``mongodb+srv`` prefix, TLS is enabled on your connection by
95+
default.
96+
97+
For a full list of client options, see the
98+
:ref:`rust-connection-options` guide.
99+
100+
.. _rust-configure-tls-certificates:
101+
102+
Configure Certificates
103+
----------------------
104+
105+
To successfully initiate a TLS request, your application must present
106+
cryptographic certificates to prove its identity. Your application's
107+
certificates must be stored as Privacy Enhanced Mail (PEM) files to
108+
enable TLS when connecting to a MongoDB deployment. The PEM file format
109+
is a container format for cryptographic certificates.
110+
111+
.. important::
112+
113+
For production use, we recommend that your MongoDB deployment use valid
114+
certificates generated and signed by the same certificate authority.
115+
For testing, your deployment can use self-signed certificates.
116+
117+
The following list describes the components that your client must
118+
present to establish a TLS-enabled connection:
119+
120+
.. list-table::
121+
:header-rows: 1
122+
:widths: 30 70
123+
124+
* - TLS Component
125+
- Description
126+
127+
* - Certificate Authority (CA)
128+
- One or more certificate authorities to
129+
trust when making a TLS connection
130+
131+
* - Client Certificate
132+
- A digital certificate that allows the server to verify the identity
133+
of your application to establish an encrypted network connection
134+
135+
* - Certificate Key
136+
- The client certificate private key file, often
137+
included within the certificate file itself
138+
139+
* - Passphrase
140+
- The password to decrypt the private client key if it is encrypted
141+
142+
.. _rust-client-tls-connect:
143+
144+
Reference Certificates in a Client
145+
----------------------------------
146+
147+
You must reference your certificates in your ``TlsOptions``
148+
struct so that the server can validate them before the client connects.
149+
150+
You must first convert your certificate filepaths to
151+
``PathBuf`` types, so you must import this type from the ``std::path``
152+
module. Then, call the ``TlsOptions`` struct's builder functions
153+
to set the ``ca_file_path`` and ``cert_key_file_path`` fields to the
154+
certificate filepaths.
155+
156+
Within your ``TlsOptions`` instance, you can set optional
157+
fields to configure TLS on your connection. For **testing purposes**,
158+
you can set the ``allow_invalid_certificates`` and
159+
``allow_invalid_hostnames`` fields.
160+
161+
Setting the ``allow_invalid_certificates`` option to ``true`` disables
162+
hostname verification, and setting the
163+
``allow_invalid_hostnames`` to ``true`` disables certificate
164+
validation.
165+
166+
.. warning::
167+
168+
Specifying either of these options in a production environment makes
169+
your application insecure and potentially vulnerable to expired
170+
certificates and to foreign processes posing as valid client
171+
instances.
172+
173+
.. _rust-tls-full-example:
174+
175+
Example
176+
~~~~~~~
177+
178+
This example performs the following actions to create a ``TlsOptions``
179+
instance and a ``Client`` instance that is configured for TLS:
180+
181+
1. Creates variables to reference the certificate filepaths in
182+
``PathBuf`` instances.
183+
184+
#. Instantiates a ``TlsOptions`` struct and sets the ``ca_file_path`` and
185+
``cert_key_file_path`` fields to the relevant filepaths.
186+
187+
#. Passes the ``TlsOptions`` instance to the ``Enabled`` variant of the
188+
``Tls`` enum.
189+
190+
#. Sets the ``tls`` field of the ``ClientOptions`` struct to the
191+
``Tls::Enabled`` variant containing the ``TlsOptions`` instance.
192+
193+
#. Creates a ``Client`` instance with these options.
194+
195+
.. literalinclude:: /includes/fundamentals/code-snippets/tls.rs
196+
:language: rust
197+
198+
.. _rust-tls-addtl-info:
199+
200+
Additional Information
201+
----------------------
202+
203+
To learn more about enabling TLS on a connection, see the
204+
following Server manual documentation:
205+
206+
- :manual:`TLS/SSL (Transport Encryption) </core/security-transport-encryption/>`
207+
- :manual:`TLS/SSL Configuration for Clients </tutorial/configure-ssl-clients/>`
208+
209+
API Documentation
210+
~~~~~~~~~~~~~~~~~
211+
212+
To learn more about any of the methods or types mentioned in this
213+
guide, see the following API documentation:
214+
215+
- `ClientOptions <{+api+}/options/struct.ClientOptions.html>`__
216+
- `Client <{+api+}/struct.Client.html>`__
217+
- `Tls <{+api+}/options/enum.Tls.html>`__
218+
- `TlsOptions <{+api+}/options/struct.TlsOptions.html>`__
219+
- `PathBuf <https://doc.rust-lang.org/nightly/std/path/struct.PathBuf.html>`__

‎source/includes/fundamentals/code-snippets/tls.rs

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
use std::path::PathBuf;
2+
use mongodb::{ options::{ ClientOptions, TlsOptions, Tls }, Client };
3+
4+
#[tokio::main]
5+
async fn main() -> mongodb::error::Result<()> {
6+
let uri = "<connection string>";
7+
8+
let mut client_options = ClientOptions::parse(uri).await?;
9+
10+
let ca_file = PathBuf::from(r"<path to CA certificate>");
11+
let key_file = PathBuf::from(r"<path to client certificate>");
12+
13+
let tls_opts = TlsOptions::builder()
14+
.ca_file_path(ca_file)
15+
.cert_key_file_path(key_file)
16+
.build();
17+
18+
client_options.tls = Some(Tls::Enabled(tls_opts));
19+
let _client = Client::with_options(client_options)?;
20+
21+
Ok(())
22+
}

0 commit comments

Comments
 (0)