Enable and Configure TLS

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 options
Additional 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 to true in your connection string
Setting the tls field of a ClientOptions instance to the Tls::Enabled variant with an empty TlsOptions struct and instantiating a Client 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(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.
Creates a variable to store the password used to decrypt the client key.
Instantiates a TlsOptions struct and sets the ca_file_path, cert_key_file_path, and tls_certificate_key_file_password fields to configure the TLS-enabled connection.
Passes the TlsOptions instance to the Enabled variant of the Tls enum.
Sets the tls field of the ClientOptions struct to the Tls::Enabled variant containing the TlsOptions instance.
Creates a Client instance with these options.

use std::path::PathBuf;
use mongodb::{ options::{ ClientOptions, TlsOptions, Tls }, Client };
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri).await?;
    let ca_file = PathBuf::from(r"<path to CA certificate>");
    let key_file = PathBuf::from(r"<path to client certificate>");
    let key_password = b"<password for client key>".to_vec();
    let tls_opts = TlsOptions::builder()
        .ca_file_path(ca_file)
        .cert_key_file_path(key_file)
        .tls_certificate_key_file_password(key_password)
        .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:

Back

Network Compression

AWS Lambda