OPTIONS

Configure mongod and mongos for SSL

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

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL, you must either build MongoDB locally passing the --ssl option to scons or use MongoDB Enterprise.

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

    Changed in version 2.6:
  • MongoDB’s SSL encryption only allows use of strong SSL ciphers with a minimum of 128-bit key length for all connections.

  • MongoDB Enterprise for Windows includes support for SSL.

See also

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

.pem File

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

MongoDB can use any valid 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

Set Up mongod and mongos with SSL Certificate and Key

To use 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 SSL encrypted connections. You can also specify either the value allowSSL or preferSSL to set up the use of mixed SSL modes on a port. See net.ssl.mode for details.
  • PEMKeyfile with the .pem file that contains the SSL certificate and key.

Consider the following syntax for mongod:

mongod --sslMode requireSSL --sslPEMKeyFile <pem>

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

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem

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 SSL Certificate Passphrase.

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

    sslMode = requireSSL
    sslPEMKeyFile = /etc/ssl/mongodb.pem
    

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

Set Up mongod and mongos with Certificate Validation

To set up mongod or mongos for SSL encryption using an 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 SSL encrypted connections. You can also specify either the value allowSSL or preferSSL to set up the use of mixed SSL modes on a port. See net.ssl.mode for details.
  • PEMKeyfile with the name of the .pem file that contains the signed 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>

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

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem

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 SSL Certificate Passphrase.

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

    sslMode = requireSSL
    sslPEMKeyFile = /etc/ssl/mongodb.pem
    sslCAFile = /etc/ssl/ca.pem
    

To connect, to mongod and mongos instances using SSL, the mongo tools must include the both the --ssl and --sslPEMKeyFile option. See SSL Configuration for Clients for more information on connecting to mongod and mongos running with 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 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

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 weakCertificateValidation 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 SSL.

For example, consider the following mongod with an SSL configuration that includes the weakCertificateValidation setting:

mongod --sslMode requireSSL --sslWeakCertificateValidation --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem

Then, clients can connect either with the option --ssl and no certificate or with the option --ssl and a valid certificate. See SSL Configuration for Clients for more information on 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 SSL.

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.

Changed in version 2.6: In previous versions, you can only specify the passphrase with a command-line or a configuration file option.

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

See Configure MongoDB for FIPS for more details.