- Security >
- Encryption >
- Transport Encryption >
- TLS/SSL Configuration for Clients
TLS/SSL Configuration for Clients¶
On this page
Clients must have support for TLS/SSL to work with a mongod or a mongos instance that has TLS/SSL support enabled.
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
Although TLS is the successor to SSL, this page uses the more familiar term SSL to refer to TLS/SSL.
See also
mongo Shell SSL Configuration¶
For SSL connections, you must use the mongo shell built with SSL support or distributed with MongoDB Enterprise.
New in version 3.0: Most MongoDB distributions now include support for SSL.
The mongo shell provides various TLS/SSL Options settings, including:
--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 (CA).
Changed in version 3.0: When running mongo with the --ssl option, you must include either --sslCAFile or --sslAllowInvalidCertificates.
This restriction does not apply to the MongoDB tools. However, running the tools without -sslCAFile creates the same vulnerability to invalid certificates.
Warning
For SSL connections (--ssl) to mongod and mongos, if the mongo shell (or MongoDB tools) runs without the --sslCAFile <CAFile> option (i.e. specifies the --sslAllowInvalidCertificates instead), the mongo shell (or MongoDB tools) will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file to validate the server certificates in cases where intrusion is a possibility.
--sslPEMKeyPassword option if the client certificate-key file is encrypted.
For a complete list of the mongo shell’s SSL settings, see TLS/SSL Options.
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 and include the --sslCAFile to validate the server certificates.
mongo --ssl --sslCAFile /etc/ssl/ca.pem
Changed in version 3.0: When running mongo with the --ssl option, you must include either --sslCAFile or --sslAllowInvalidCertificates.
This restriction does not apply to the MongoDB tools. However, running the tools without -sslCAFile creates the same vulnerability to invalid certificates.
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, the --sslPEMKeyFile option to specify the signed certificate-key file, and the --sslCAFile to validate the server certificates.
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem
Changed in version 3.0: When running mongo with the --ssl option, you must include either --sslCAFile or --sslAllowInvalidCertificates.
This restriction does not apply to the MongoDB tools. However, running the tools without -sslCAFile creates the same vulnerability to invalid certificates.
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, --sslCAFile, and no certificate or
- with the --ssl, --sslCAFile, and a valid signed certificate.
Changed in version 3.0: When running mongo with the --ssl option, you must include either --sslCAFile or --sslAllowInvalidCertificates.
This restriction does not apply to the MongoDB tools. However, running the tools without -sslCAFile creates the same vulnerability to invalid certificates.
For example, if mongod is running with weak certificate validation, both of the following mongo shell clients can connect to that mongod:
mongo --ssl --sslCAFile /etc/ssl/ca.pem
mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem
Important
If the client presents a certificate, the certificate must be valid.
MongoDB Cloud Manager and Ops Manager Monitoring Agent¶
The MongoDB Cloud Manager Monitoring agent will also have to connect via SSL in order to gather its statistics. Because the agent already utilizes SSL for its communications to the MongoDB Cloud Manager servers, this is just a matter of enabling SSL support in MongoDB Cloud Manager itself on a per host basis. å See the MongoDB Cloud Manager documentation for more information about SSL configuration.
For Ops Manager, see Ops Manager documentation.
MongoDB Drivers¶
The MongoDB Drivers support for connection to SSL enabled MongoDB. See:
MongoDB Tools¶
Changed in version 2.6.
Various MongoDB utility programs supports SSL. These tools include:
To use SSL connections with these tools, use the same SSL options as the mongo shell. See mongo Shell SSL Configuration.