Configure mongod and mongos for TLS/SSL

On this page

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. MongoDB TLS/SSL implementation uses OpenSSL libraries.

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.

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:

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

copy 
cat mongodb-cert.key mongodb-cert.crt > mongodb.pem

See also

Use x.509 Certificates to Authenticate Clients

[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

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:

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

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

copy 
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.

See also

Upgrade a Cluster to Use 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:

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

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

copy 
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.

See also

Upgrade a Cluster to Use 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:

copy 
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.

Val

首页