/ /

Configure Transport Layer Security (TLS)

Overview

In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment.

When you enable TLS for a connection, the C++ driver performs the following actions:

Uses TLS to connect to the MongoDB deployment
Verifies the deployment's certificate
Ensures that the certificate certifies the deployment

To learn how to configure your MongoDB deployment for TLS, see the TLS configuration guide in the MongoDB Server manual.

Note

This page assumes prior knowledge of TLS/SSL and access to valid certificates. A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authorities (CAs) is beyond the scope of this documentation.

Tip

The C++ driver delegates most TLS behavior to the MongoDB C Driver. For information about how the C driver handles TLS, including configuration steps and expected behavior, see Configuring TLS in the C driver Documentation.

Enable TLS

To enable TLS for the connection to your MongoDB instance, set the tls connection option to true in your connection string, as shown in the following example:

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");

Tip

If your connection string includes the +srv modification, which specifies the SRV connection format, TLS is enabled on your connection by default.

To learn more about the SRV connection format, see SRV Connection Format in the MongoDB Server documentation.

Specify a CA File

During the TLS handshake, the MongoDB deployment presents a certificate key file to your application to establish its identity. Usually, a deployment's certificate has been signed by a well-known CA, and your application relies on this CA to validate the certificate.

During testing, however, you might want to act as your own CA. In this case, you must instruct the C++ driver to use your CA certificates instead of ones signed by another CA.

To do so, specify the path to a .pem file containing the root certificate chain. You can do this in two ways: by setting a property on a mongocxx::options::tls object, or by using the tlsCAFile parameter in your connection string.

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.pem_file("/path/to/file.pem");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsCAFile=/path/to/file.pem");

Specify a CA Directory

If you are using OpenSSL or LibreSSL (libtls) for TLS support, you can also instruct the C++ driver to search for a CA file within a directory. The driver searches this directory if it doesn't find a CA file at the path specified in the tlsCAFile or pem_file option.

The following code example shows how to use the ca_dir option to specify the directory that the driver should search:

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.ca_dir("/path/to/search/");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

Tip

This option corresponds to the OpenSSL SSL_CTX_load_verify_locations parameter and the LibreSSL tls_config_set_ca_path parameter.

Check Certificate Revocation

When an X.509 certificate is no longer trustworthy—for example, if its private key has been compromised—the CA revokes the certificate. The C++ driver includes two ways to check whether a server's certificate has been revoked.

OCSP

The Online Certificate Status Protocol (OCSP) process varies depending on the version of MongoDB Server you're connecting to:

MongoDB v4.4 or later: The server staples a time-stamped OCSP response to its certificate. The C++ driver validates the certificate against the OCSP response. If the CA has revoked the certificate, or if the OCSP response is otherwise invalid, the TLS handshake fails.
MongoDB v4.3 or earlier: The server supplies an OCSP endpoint, which the C++ driver contacts directly. The C++ driver then validates the certificate against the OCSP response. If the CA hasn't revoked the certificate, the TLS handshake continues, even if the OCSP response is invalid or malformed.

To stop the C++ driver from contacting the OCSP endpoint, set the tlsDisableOCSPEndpointCheck connection option to true in your connection string, as shown in the following code example:

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsDisableOCSPEndpointCheck=true");

Certificate Revocation List

Instead of using OCSP, you can instruct the C++ driver to check the server's certificate against a Certificate Revocation List (CRL) published by the CA.

The following code example shows how to use the crl_file option to specify the path to specify the path to a .pem file from the CA:

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.crl_file("/path/to/file.pem");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

Tip

You can specify a CRL file in either the .pem or .der format.

Present a Client Certificate

Some MongoDB deployments require every connecting application to present a client certificate that proves its identity. To specify the client certificate for the C++ driver to present, specify the file path of the .pem file that contains your certificate and private key.

You can do this in two ways: by setting a property on a mongocxx::options::tls object, or by using the tlsCertificateKeyFile parameter in your connection string.

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.pem_file("/path/to/file.pem");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem");

Important

Your client certificate and private key must be in the same .pem file. If they are stored in different files, you must concatenate them. The following example shows how to concatenate a key file and a certificate file into a third file called combined.pem on a Unix system:

$ cat key.pem cert.pem > combined.pem

Provide a Key Password

If the private key in your certificate file is encrypted, you must provide the password. You can do this in two ways: by setting a property on a mongocxx::options::tls object, or by using the tlsCertificateKeyFilePassword parameter in your connection string.

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.pem_file("/path/to/file.pem");
tls_options.pem_password("<password>");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem&tlsCertificateKeyFilePassword=<password>");

Allow Insecure TLS

When TLS is enabled, the C++ driver automatically verifies the certificate that the server presents. When testing your code, you can disable this verification. This is known as insecure TLS.

When insecure TLS is enabled, the driver requires only that the server present an X.509 certificate. The driver accepts a certificate even if any of the following are true:

The hostname of the server and the subject name (or subject alternative name) on the certificate don't match.
The certificate is expired or not yet valid.
The certificate doesn't have a trusted root certificate in the chain.
The certificate purpose isn't valid for server identification.

Note

Even when insecure TLS is enabled, communication between the client and server is encrypted with TLS.

To enable insecure TLS, set the tlsInsecure connection option to true in your connection string, as shown in the following code example:

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsInsecure=true");

To disable only certificate validation, set the tlsAllowInvalidCertificates option to true, and set the tlsInsecure option to false (or omit it):

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.allow_invalid_certificates(true);
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidCertificates=true");

To disable only hostname verification, set the tlsAllowInvalidHostnames option to true, and set the tlsInsecure option to false (or omit it):

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidHostnames=true");

Warning

Don't Use in Production

Always set the tlsInsecure, tlsAllowInvalidCertificates, and tlsAllowInvalidHostnames options to false in production.

Setting any of these options to true in a production environment makes your application insecure and potentially vulnerable to expired certificates and to foreign processes posing as valid client instances.

API Documentation

To learn more about configuring TLS for the C++ driver, see the following API documentation:

Back

Specify Connection Options

Compress Network Traffic