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

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)?;

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.

The following list describes the components that your client must present to establish a TLS-enabled connection:

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.

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 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:

• TLS/SSL (Transport Encryption)

• TLS/SSL Configuration for Clients