OPTIONS

Connect to MongoDB with SSL

This document outlines the use and operation of MongoDB’s SSL support. SSL allows MongoDB clients to support encrypted connections to mongod 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 outline the process for getting started with SSL and 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.

Configure mongod and mongos for SSL

Combine SSL Certificate and Key File

Before you can use SSL, you must have a .pem file that contains the public key certificate and private key. MongoDB can use any valid SSL certificate. To generate a self-signed certificate and private key, use a command that resembles the following:

cd /etc/ssl/
openssl req -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.

Run in FIPS Mode

MongoDB Enterprise supports running in FIPS mode.

If your mongod or mongos is running on a system with an OpenSSL library configured with the FIPS 140-2 module, you can run mongod or mongos in FIPS mode, with the FIPSMode setting.

For Red Hat Enterprise Linux 6.x (RHEL 6.x) or its derivatives such as CentOS 6.x, the OpenSSL toolkit must be at least openssl-1.0.1e-16.el6_5 to run in FIPS mode. To upgrade the toolkit for these platforms, issue the following command:

yum update openssl

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.

SSL Configuration for Clients

Clients must have support for SSL to work with a mongod or a mongos instance that has SSL support enabled. The current versions of the Python, Java, Ruby, Node.js, .NET, and C++ drivers have support for SSL, with full support coming in future releases of other drivers.

mongo SSL Configuration

For SSL connections, you must use the mongo shell built with SSL support or distributed with MongoDB Enterprise. To support SSL, mongo has the following settings:

  • --ssl
  • --sslPEMKeyFile with the name of the .pem file that contains the SSL certificate and key.
  • --sslCAFile with the name of the .pem file that contains the certificate from the Certificate Authority.
  • --sslPEMKeyPassword option if the client certificate-key file is encrypted.

Connect to MongoDB Instance with SSL Encryption

To connect to a mongod or mongos instance that requires only a SSL encryption mode, start mongo shell with --ssl, as in the following:

mongo --ssl

Connect to MongoDB Instance that Requires Client Certificates

To connect to a mongod or mongos that requires CA-signed client certificates, start the mongo shell with --ssl and the --sslPEMKeyFile option to specify the signed certificate-key file, as in the following:

mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem

Connect to MongoDB Instance that Validates when Presented with a Certificate

To connect to a mongod or mongos instance that only requires valid certificates when the client presents a certificate, start mongo shell either with the --ssl ssl and no certificate or with the --ssl ssl and a valid signed certificate.

For example, if mongod is running with weak certificate validation, both of the following mongo shell clients can connect to that mongod:

mongo --ssl
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem

Important

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

MMS Monitoring Agent

The Monitoring agent will also have to connect via SSL in order to gather its stats. Because the agent already utilizes SSL for its communications to the MMS servers, this is just a matter of enabling SSL support in MMS itself on a per host basis.

Use the “Edit” host button (i.e. the pencil) on the Hosts page in the MMS console to enable SSL.

Please see the MMS documentation for more information about MMS configuration.

PyMongo

Add the “ssl=True” parameter to a PyMongo MongoClient to create a MongoDB connection to an SSL MongoDB instance:

from pymongo import MongoClient
c = MongoClient(host="mongodb.example.net", port=27017, ssl=True)

To connect to a replica set, use the following operation:

from pymongo import MongoReplicaSetClient
c = MongoReplicaSetClient("mongodb.example.net:27017",
                          replicaSet="mysetname", ssl=True)

PyMongo also supports an “ssl=true” option for the MongoDB URI:

mongodb://mongodb.example.net:27017/?ssl=true

Java

Consider the following example “SSLApp.java” class file:

import com.mongodb.*;
import javax.net.ssl.SSLSocketFactory;

public class SSLApp {

    public static void main(String args[])  throws Exception {

        MongoClientOptions o = new MongoClientOptions.Builder()
                .socketFactory(SSLSocketFactory.getDefault())
                .build();

        MongoClient m = new MongoClient("localhost", o);

        DB db = m.getDB( "test" );
        DBCollection c = db.getCollection( "foo" );

        System.out.println( c.findOne() );
    }
}

Ruby

The recent versions of the Ruby driver have support for connections to SSL servers. Install the latest version of the driver with the following command:

gem install mongo

Then connect to a standalone instance, using the following form:

require 'rubygems'
require 'mongo'

connection = MongoClient.new('localhost', 27017, :ssl => true)

Replace connection with the following if you’re connecting to a replica set:

connection = MongoReplicaSetClient.new(['localhost:27017'],
                                       ['localhost:27018'],
                                       :ssl => true)

Here, mongod instance run on “localhost:27017” and “localhost:27018”.

Node.JS (node-mongodb-native)

In the node-mongodb-native driver, use the following invocation to connect to a mongod or mongos instance via SSL:

var db1 = new Db(MONGODB, new Server("127.0.0.1", 27017,
                                     { auto_reconnect: false, poolSize:4, ssl:ssl } );

To connect to a replica set via SSL, use the following form:

var replSet = new ReplSetServers( [
    new Server( RS.host, RS.ports[1], { auto_reconnect: true } ),
    new Server( RS.host, RS.ports[0], { auto_reconnect: true } ),
    ],
  {rs_name:RS.name, ssl:ssl}
);

.NET

As of release 1.6, the .NET driver supports SSL connections with mongod and mongos instances. To connect using SSL, you must add an option to the connection string, specifying ssl=true as follows:

var connectionString = "mongodb://localhost/?ssl=true";
var server = MongoServer.Create(connectionString);

The .NET driver will validate the certificate against the local trusted certificate store, in addition to providing encryption of the server. This behavior may produce issues during testing if the server uses a self-signed certificate. If you encounter this issue, add the sslverifycertificate=false option to the connection string to prevent the .NET driver from validating the certificate, as follows:

var connectionString = "mongodb://localhost/?ssl=true&sslverifycertificate=false";
var server = MongoServer.Create(connectionString);

MongoDB Tools

Changed in version 2.6.

Various MongoDB utility programs supports SSL. These tools include:

Tip

To use SSL connections with these tools, use the same SSL options as the mongo shell. See mongo SSL Configuration.