Enable and Configure TLS
On this page
Overview
In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment. TLS is a cryptographic protocol that secures communication between your application and MongoDB. To configure your connection to use TLS, enable the TLS option and provide your certificates for validation when creating a client.
This guide includes the following sections:
Enable TLS describes ways to enable TLS on your connection
Configure Certificates describes the certificates required to configure TLS
Reference Certificates in a Client provides an example of how to create a
TlsOptions
struct to configure your TLS optionsAdditional Information provides links to resources and API documentation for types and methods mentioned in this guide
Tip
To learn more about TLS, see the Wikipedia entry on Transport Layer Security.
Enable TLS
You can enable TLS on a connection to your MongoDB instance in one of the following ways:
Setting the
tls
option totrue
in your connection stringSetting the
tls
field of aClientOptions
instance to theTls::Enabled
variant with an emptyTlsOptions
struct and instantiating aClient
with those options
Select from the following Connection String and ClientOptions tabs to see a corresponding code sample:
let uri = "mongodb://<hostname>:<port>?tls=true" let client = Client::with_uri_str(uri).await?;
let uri = "<connection string>" let mut client_options = ClientOptions::parse_async(uri).await?; let tls_opts = TlsOptions::builder().build(); client_options.tls = Some(Tls::Enabled(tls_opts)); let client = Client::with_options(client_options)?;
Note
If your connection string uses a DNS SRV record by including
the mongodb+srv
prefix, TLS is enabled on your connection by
default.
For a full list of client options, see the Connection Options guide.
Configure Certificates
To successfully initiate a TLS request, your application must present cryptographic certificates to prove its identity. Your application's certificates must be stored as Privacy Enhanced Mail (PEM) files to enable TLS when connecting to a MongoDB deployment. The PEM file format is a container format for cryptographic certificates.
Important
For production use, we recommend that your MongoDB deployment use valid certificates generated and signed by the same certificate authority. For testing, your deployment can use self-signed certificates.
The following list describes the components that your client must present to establish a TLS-enabled connection:
TLS Component | Description |
---|---|
Certificate Authority (CA) | One or more certificate authorities to
trust when making a TLS connection |
Client Certificate | A digital certificate that allows the server to verify the identity
of your application to establish an encrypted network connection |
Certificate Key | The client certificate private key file, often
included within the certificate file itself |
Passphrase | The password to decrypt the private client key if it is encrypted |
Reference Certificates in a Client
You must reference your certificates in your TlsOptions
struct so that the server can validate them before the client connects.
You must first convert your certificate filepaths to
PathBuf
types, so you must import this type from the std::path
module. Then, call the TlsOptions
struct's builder functions
to set the ca_file_path
and cert_key_file_path
fields to the
certificate filepaths.
Within your TlsOptions
instance, you can set optional
fields to configure TLS on your connection. For testing purposes,
you can set the allow_invalid_certificates
and
allow_invalid_hostnames
fields.
Setting the allow_invalid_certificates
option to true
disables
hostname verification, and setting the
allow_invalid_hostnames
to true
disables certificate
validation.
Warning
Specifying either of these options in a production environment makes your application insecure and potentially vulnerable to expired certificates and to foreign processes posing as valid client instances.
Example
This example performs the following actions to create a TlsOptions
instance and a Client
instance that is configured for TLS:
Creates variables to reference the certificate filepaths in
PathBuf
instances.Instantiates a
TlsOptions
struct and sets theca_file_path
andcert_key_file_path
fields to the relevant filepaths.Passes the
TlsOptions
instance to theEnabled
variant of theTls
enum.Sets the
tls
field of theClientOptions
struct to theTls::Enabled
variant containing theTlsOptions
instance.Creates a
Client
instance with these options.
use std::path::PathBuf; use mongodb::{ options::{ ClientOptions, TlsOptions, Tls }, Client }; async fn main() -> mongodb::error::Result<()> { let uri = "<connection string>"; let mut client_options = ClientOptions::parse_async(uri).await?; let ca_file = PathBuf::from(r"<path to CA certificate>"); let key_file = PathBuf::from(r"<path to client certificate>"); let tls_opts = TlsOptions::builder() .ca_file_path(ca_file) .cert_key_file_path(key_file) .build(); client_options.tls = Some(Tls::Enabled(tls_opts)); let _client = Client::with_options(client_options)?; Ok(()) }
Additional Information
To learn more about enabling TLS on a connection, see the following Server manual documentation:
API Documentation
To learn more about any of the methods or types mentioned in this guide, see the following API documentation: