Configure Transport Layer Security (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.
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: