Docs Menu
Docs Home
/
Languages
/
C Driver
/
C Driver
/
Connect to MongoDB

Configure Transport Layer Security (TLS)

On this page

  • Overview
  • Enable TLS
  • Specify a CA File
  • Server Certificate Verification
  • Supported Libraries
  • OpenSSL
  • LibreSSL / libtls (Deprecated)
  • Native TLS Support on Windows (Secure Channel)
  • Native TLS Support on macOS / Darwin (Secure Transport)
  • API Documentation

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

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

Enable TLS

You can enable TLS on a connection to your MongoDB instance in the following ways:

  • Setting the tls parameter in your connection string

  • Using the mongoc_uri_set_option_as_bool() function to set the MONGOC_URI_TLS connection option to true

mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true");
// Do database work here 
mongoc_client_destroy (client);
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017");  
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
mongoc_client_t *client = mongoc_client_new_from_uri (uri);
// Do database work here
mongoc_client_destroy (client);
mongoc_uri_destroy (uri);

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

When you connect to a MongoDB deployment with TLS enabled, the deployment will by default require the client to provide a client certificate issued by a certificate authority, or an authority trusted by the native certificate store in use on the server.

You can provide the client certificate in the following ways:

  • Setting the tlscertificatekeyfile parameter in your connection string to a .pem file containing the root certificate chain

  • Using the mongoc_uri_set_option_as_utf8() function to set the MONGOC_URI_TLSCERTIFICATEKEYFILE option to a .pem file containing the root certificate chain

mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true&tlscertificatekeyfile=/path/to/certs/client-certificate.pem");
// Do database work here 
mongoc_client_destroy (client);
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017");  
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "/path/to/client-certificate.pem");  
mongoc_client_t *client = mongoc_client_new_from_uri (uri);
// Do database work here
mongoc_client_destroy (client);
mongoc_uri_destroy (uri);

Server Certificate Verification

The MongoDB C Driver will automatically verify the validity of a server certificate issued by the configured Certificate Authority. The driver also performs hostname validation and revocation checking.

To overwrite this behavior, it is possible to disable hostname validation, OCSP endpoint revocation checking, all revocation checking, and allow invalid certificates.

This behavior is controlled using the tlsAllowInvalidHostnames, tlsDisableOCSPEndpointCheck, tlsDisableCertificateRevocationCheck, and tlsAllowInvalidCertificates options. By default, all are set to false.

It is not recommended to change these defaults, since you might expose your client to the following security risks:

  • Man In The Middle attacks, when tlsAllowInvalidHostnames is set

  • Invalid certificates, when tlsAllowInvalidCertificates is set

  • Potentially revoked certificates, when tlsDisableOCSPEndpointCheck or tlsDisableCertificateRevocationCheck are set

Supported Libraries

By default, libmongoc will attempt to find a supported TLS library and enable TLS support. This is controlled by the cmake flag ENABLE_SSL, which is set to AUTO by default. This flag accepts the following values:

  • AUTO: Links to the system's native TLS library, or attempts to find OpenSSL. This is the default value.

  • OPENSSL: Links to OpenSSL (libssl). An optional install path may be specified with OPENSSL_ROOT.

  • LIBRESSL (Deprecated): Links to LibreSSL's libtls. You can link to LibreSSL's compatible libssl by setting OPENSSL.

  • WINDOWS: Links to Secure Channel, the native TLS library on Windows.

  • DARWIN: Links to Secure Transport, the native TLS library on macOS.

  • OFF: Disables TLS support.

OpenSSL

The MongoDB C Driver uses OpenSSL on Linux and Unix platforms (besides macOS). Industry best practices and some regulations require the use of TLS 1.1 or newer, which requires at least OpenSSL 1.0.1. Use the following command to check your OpenSSL version:

openssl version

Ensure your system's OpenSSL is a recent version (at least 1.0.1), or use the following command to install a recent version in a non-system path and build against it:

cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/openssl

When compiled against OpenSSL, the driver will attempt to load the system default certificate store, as configured by the distribution. That can be overridden by setting the tlsCAFile URI option or with the fields ca_file and ca_dir in the mongoc_ssl_opt_t.

The Online Certificate Status Protocol (OCSP) is fully supported when using OpenSSL 1.0.1+. However, when a crl_file is set with mongoc_ssl_opt_t and the crl_file revokes the server's certificate, the certificate is considered revoked, even if the certificate has a valid stapled OCSP response.

Tip

For more information about OCSP, see RFC 6960.

LibreSSL / libtls (Deprecated)

The MongoDB C Driver supports LibreSSL through the use of OpenSSL compatibility checks when configured to compile against openssl. It also supports the new libtls library when configured to build against libressl.

When compiled with LibreSSL, the crl_file option of a mongoc_ssl_opt_t is not supported, and will issue an error if used. Setting tlsDisableOCSPEndpointCheck and tlsDisableCertificateRevocationCheck has no effect.

The Online Certificate Status Protocol (OCSP) is partially supported with the following notes:

  • Must-Staple extension (see RFC 7633) is ignored

  • Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down

  • Connection will not continue if the client receives a revoked response from an OCSP responder

Tip

For more information about OCSP, see RFC 6960.

Native TLS Support on Windows (Secure Channel)

The MongoDB C Driver supports the Windows native TLS library (Secure Channel, or SChannel) and its native crypto library (Cryptography API: Next Generation, or CNG).

When compiled against the Windows native libraries, the ca_dir option of a mongoc_ssl_opt_t is not supported and will issue an error if used.

Encrypted PEM files, set by using the tlsCertificateKeyPassword URI option, are also not supported and will result in error when attempting to load them.

When tlsCAFile is set, the driver will only allow server certificates issued by one or more authorities provided. When no tlsCAFile is set, the driver will look up the Certificate Authority using the System Local Machine Root certificate store to confirm the provided certificate.

When crl_file is set with mongoc_ssl_opt_t, the driver will import the revocation list to the System Local Machine Root certificate store.

Setting tlsDisableOCSPEndpointCheck has no effect.

The Online Certificate Status Protocol (OCSP) is partially supported with the following notes:

  • Must-Staple extension (see RFC 7633) is ignored.

  • Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down.

  • Connection will not continue if the client receives a revoked response from an OCSP responder.

  • When a crl_file is set with mongoc_ssl_opt_t, and the crl_file revokes the server's certificate, the OCSP response takes precedence. For example, if the server presents a certificate with a valid stapled OCSP response, the certificate is considered valid even if the crl_file marks it as revoked.

Tip

For more information about OCSP, see RFC 6960.

Native TLS Support on macOS / Darwin (Secure Transport)

The MongoDB C Driver supports both the Darwin native TLS library and Common Crypto, its native crypto library.

When compiled against Secure Transport, the ca_dir and crl_file options of a mongoc_ssl_opt_t are not supported. An error is issued if either are used.

When tlsCAFile is set, the driver will only allow server certificates issued by the authority (or authorities) provided. When no tlsCAFile is set, the driver will use the Certificate Authorities in the unlocked keychains.

Setting tlsDisableOCSPEndpointCheck and tlsDisableCertificateRevocationCheck has no effect when compiling against secure transport.

The Online Certificate Status Protocol (OCSP) is partially supported with the following notes.

  • Must-Staple extension (see RFC 7633) is ignored

  • Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down

  • Connection will not continue if the client receives a revoked response from an OCSP responder

Tip

For more information about OCSP, see RFC 6960.

API Documentation

For more information about the objects and functions mentioned in this guide, see the following API documentation:

Back

Choose a Connection Target

Next

Databases & Collections