Navigation

Configure mongod and mongos for TLS/SSL

Overview

This document helps you to configure MongoDB to support TLS/SSL. MongoDB clients can use TLS/SSL to encrypt connections to mongod and mongos instances.

Starting in version 4.0, MongoDB uses the native TLS/SSL OS libraries:

Windows Secure Channel (Schannel)
Linux/BSD OpenSSL
macOS Secure Transport

Note

TLS is the successor to SSL.

These instructions assume that you have already installed a build of MongoDB that includes TLS/SSL support and that your client driver supports encrypted connections. For instructions on upgrading a cluster currently not using TLS/SSL to using TLS/SSL, see Upgrade a Cluster to Use TLS/SSL.

MongoDB’s TLS/SSL encryption only allows use of strong TLS/SSL ciphers with a minimum of 128-bit key length for all connections.

Starting in version 4.0, MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.

Prerequisites

Important

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

Note

The Linux 64-bit legacy x64 builds of MongoDB do not include support for TLS/SSL.

Client Support

See TLS/SSL Configuration for Clients to learn about TLS/SSL support for Python, Java, Ruby, and other clients.

Certificate Authorities

For production use, your MongoDB deployment should use valid certificates generated and signed by a single certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by a third-party TLS/SSL vendor. Obtaining and managing certificates is beyond the scope of this documentation.

.pem File

Before you can use TLS/SSL, you must have a .pem file containing a public key certificate and its associated private key. [1]

MongoDB can use any valid TLS/SSL certificate issued by a certificate authority, or a self-signed certificate. If you use a self-signed certificate, although the communications channel will be encrypted, there will be no validation of server identity. Although such a situation will prevent eavesdropping on the connection, it leaves you vulnerable to a man-in-the-middle attack. Using a certificate signed by a trusted certificate authority will permit MongoDB drivers to verify the server’s identity.

In general, avoid using self-signed certificates unless the network is trusted.

Additionally, with regards to authentication among replica set/sharded cluster members, in order to minimize exposure of the private key and allow hostname validation, it is advisable to use different certificates on different servers.

For testing purposes, you can generate a self-signed certificate and private key on a Unix system with a command that resembles the following:

cd /etc/ssl/
openssl req -newkey rsa:2048 -new -x509 -days 365 -nodes -out mongodb-cert.crt -keyout mongodb-cert.key

This operation generates a new, self-signed certificate with no passphrase that is valid for 365 days. Once you have the certificate, concatenate the certificate and private key to a .pem file, as in the following example:

cat mongodb-cert.key mongodb-cert.crt > mongodb.pem
[1]For FIPS mode, ensure that the certificate is FIPS-compliant (i.e use of FIPS-compliant algorithms) and the private key meets the PKCS#8 standard. If you need to convert a private key to PKCS#8 format, various conversion tools exist, such as openssl pkcs8 and others.

Procedures

New in version 4.0.

Using System Stores for Storing Keys and Certificates for macOS and Windows

Both Windows and macOS offer system certificate stores that can be accessed across applications via OS specific APIs. Starting in MongoDB version 4.0, certificates can be retrieved from these stores by searching for them via certain well-defined selectors that are available in all certificates.

On the command line you can pass the --sslCertificateSelector followed by the certificate selector you would like to use and the value of that selector.

Property Value type Description
subject ASCII string Subject name or common name on certificate
thumbprint hex string

A sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA-1 digest.

The thumbprint is sometimes referred to as a fingerprint.

Use the selectors by passing <parameter>=<value> on the command line. For example, for a certificate with the common name or subject my.dev.server, you would use:

mongod --sslMode requireSSL --sslCertificateSelector subject=my.dev.server

Alternatively, use the certificateSelector to configure the certificate storage selector with a config file.

net:
   ssl:
      certificateSelector: <parameter>=<value>

Tip

If you are using --sslCertificateSelector or certificateSelector, the --sslPEMKeyFile is invalid. OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates.

Note

Starting in MongoDB 3.6, mongod and mongos bind to localhost by default. If the members of your deployment are run on different hosts or if you wish remote clients to connect to your deployment, you must specify --bind_ip or net.bindIp. For more information, see Localhost Binding Compatibility Changes.

Set Up mongod and mongos with TLS/SSL Certificate and Key

To use TLS/SSL in your MongoDB deployment, include the following run-time options with mongod and mongos:

  • net.ssl.mode set to requireSSL. This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value allowSSL or preferSSL to set up the use of mixed TLS/SSL modes on a port. See net.ssl.mode for details.
  • PEMKeyfile with the .pem file that contains the TLS/SSL certificate and key.

Consider the following syntax for mongod:

mongod --sslMode requireSSL --sslPEMKeyFile <pem> <additional options>

For example, given an TLS/SSL certificate located at /etc/ssl/mongodb.pem, configure mongod to use TLS/SSL encryption for all connections with the following command:

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem <additional options>

Note

  • Specify <pem> with the full path name to the certificate.
  • If the private key portion of the <pem> is encrypted, specify the passphrase. See TLS/SSL Certificate Passphrase.

You may also specify these options in the configuration file, as in the following examples:

If using the YAML configuration file format, include the following configuration in the file:

net:
   ssl:
      mode: requireSSL
      PEMKeyFile: /etc/ssl/mongodb.pem

To connect to mongod and mongos instances using TLS/SSL, the mongo shell and MongoDB tools must include the --ssl option. See TLS/SSL Configuration for Clients for more information on connecting to mongod and mongos running with TLS/SSL.

Set Up mongod and mongos with Certificate Validation

To set up mongod or mongos for TLS/SSL encryption using an TLS/SSL certificate signed by a certificate authority, include the following run-time options during startup:

  • net.ssl.mode set to requireSSL. This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value allowSSL or preferSSL to set up the use of mixed TLS/SSL modes on a port. See net.ssl.mode for details.
  • PEMKeyfile with the name of the .pem file that contains the signed TLS/SSL certificate and key.
  • CAFile with the name of the .pem file that contains the root certificate chain from the Certificate Authority.

Consider the following syntax for mongod:

mongod --sslMode requireSSL --sslPEMKeyFile <pem> --sslCAFile <ca> <additional options>

For example, given a signed TLS/SSL certificate located at /etc/ssl/mongodb.pem and the certificate authority file at /etc/ssl/ca.pem, you can configure mongod for TLS/SSL encryption as follows:

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem <additional options>

Note

  • Specify the <pem> file and the <ca> file with either the full path name or the relative path name.
  • If the <pem> is encrypted, specify the passphrase. See TLS/SSL Certificate Passphrase.

You may also specify these options in the configuration file, as in the following examples:

If using the YAML configuration file format, include the following configuration in the file:

net:
   ssl:
      mode: requireSSL
      PEMKeyFile: /etc/ssl/mongodb.pem
      CAFile: /etc/ssl/ca.pem

To connect to mongod and mongos instances using TLS/SSL, the mongo tools must include the both the --ssl and --sslPEMKeyFile option. See TLS/SSL Configuration for Clients for more information on connecting to mongod and mongos running with TLS/SSL.

Block Revoked Certificates for Clients

To prevent clients with revoked certificates from connecting, include the sslCRLFile to specify a .pem file that contains revoked certificates.

For example, the following mongod with TLS/SSL configuration includes the sslCRLFile setting:

mongod --sslMode requireSSL --sslCRLFile /etc/ssl/ca-crl.pem --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem <additional options>

Clients with revoked certificates in the /etc/ssl/ca-crl.pem will not be able to connect to this mongod instance.

Validate Only if a Client Presents a Certificate

In most cases it is important to ensure that clients present valid certificates. However, if you have clients that cannot present a client certificate, or are transitioning to using a certificate authority you may only want to validate certificates from clients that present a certificate.

If you want to bypass validation for clients that don’t present certificates, include the allowConnectionsWithoutCertificates run-time option with mongod and mongos. If the client does not present a certificate, no validation occurs. These connections, though not validated, are still encrypted using TLS/SSL.

For example, consider the following mongod with an TLS/SSL configuration that includes the allowConnectionsWithoutCertificates setting:

mongod --sslMode requireSSL --sslAllowConnectionsWithoutCertificates --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem <additional options>

Then, clients can connect either with the option --ssl and no certificate or with the option --ssl and a valid certificate. See TLS/SSL Configuration for Clients for more information on TLS/SSL connections for clients.

Note

If the client presents a certificate, the certificate must be a valid certificate.

All connections, including those that have not presented certificates are encrypted using TLS/SSL.

Disallow Protocols

New in version 3.0.7.

To prevent MongoDB servers from accepting incoming connections that use specific protocols, include the --sslDisabledProtocols option, or if using the configuration file the net.ssl.disabledProtocols setting.

For example, the following configuration uses --sslDisabledProtocols option to prevent mongod from accepting incoming connections that use either TLS1_0 or TLS1_1:

mongod --sslMode requireSSL --sslDisabledProtocols TLS1_0,TLS1_1 --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem <additional options>

If using the YAML configuration file format:

net:
   ssl:
      mode: requireSSL
      PEMKeyFile: /etc/ssl/mongodb.pem
      CAFile: /etc/ssl/ca.pem
      disabledProtocols: TLS1_0,TLS1_1

For more information, including the protocols recognized by the option, see net.ssl.disabledProtocols or the --sslDisabledProtocols option for mongod and mongos.

TLS/SSL Certificate Passphrase

The PEM files for PEMKeyfile and ClusterFile may be encrypted. With encrypted PEM files, you must specify the passphrase at startup with a command-line or a configuration file option or enter the passphrase when prompted.

To specify the passphrase in clear text on the command line or in a configuration file, use the PEMKeyPassword and/or the clusterPassword option.

To have MongoDB prompt for the passphrase at the start of mongod or mongos and avoid specifying the passphrase in clear text, omit the PEMKeyPassword and/or the clusterPassword option. MongoDB will prompt for each passphrase as necessary.

Important

The passphrase prompt option is available if you run the MongoDB instance in the foreground with a connected terminal. If you run mongod or mongos in a non-interactive session (e.g. without a terminal or as a service on Windows), you cannot use the passphrase prompt option.

Run in FIPS Mode

Note

FIPS-compatible TLS/SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.

See Configure MongoDB for FIPS for more details.