- 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
TLS is the successor to SSL.
See also
mongo
Shell 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:
--ssl
--sslPEMKeyFile
with the name of the.pem
file that contains the TLS/SSL certificate and key.--sslPEMKeyPassword
option if the client certificate-key file is encrypted.--sslCAFile
with the name of the.pem
file that contains the certificate from the Certificate Authority (CA).
To connect to a mongod
or mongos
that
uses TLS/SSL, you must also specify the --host
option for the
mongo
shell if you haven’t specified a connect
string. The mongo
shell verifies that the hostname of
the mongod
or mongos
matches the CN or
SAN of --sslPEMKeyFile
certificate presented by the
mongod
or mongos
. If the hostname does
not match the CN/SAN, mongo
will fail to connect.
For a complete list of the mongo
shell’s TLS/SSL settings, see
TLS/SSL Options.
Connect to MongoDB Instance Using Encryption¶
To connect to a mongod
or mongos
instance that
requires encrypted communication,
start mongo
shell with --ssl
and
include the --sslCAFile
to validate the
server certificates.
Warning
For TLS/SSL connections to mongod
and
mongos
, avoid using
--sslAllowInvalidCertificates
if possible and only use
--sslAllowInvalidCertificates
on systems where intrusion is
not possible.
If the mongo
shell (and other
MongoDB Tools) runs with the
--sslAllowInvalidCertificates
option, the
mongo
shell (and other
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.
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 --host
option to specify the host to which to connect, the --sslPEMKeyFile
option to specify the signed certificate-key file,
and the --sslCAFile
to validate the
server certificates.
Warning
For TLS/SSL connections to mongod
and
mongos
, avoid using
--sslAllowInvalidCertificates
if possible and only use
--sslAllowInvalidCertificates
on systems where intrusion is
not possible.
If the mongo
shell (and other
MongoDB Tools) runs with the
--sslAllowInvalidCertificates
option, the
mongo
shell (and other
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.
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.
Warning
For TLS/SSL connections to mongod
and
mongos
, avoid using
--sslAllowInvalidCertificates
if possible and only use
--sslAllowInvalidCertificates
on systems where intrusion is
not possible.
If the mongo
shell (and other
MongoDB Tools) runs with the
--sslAllowInvalidCertificates
option, the
mongo
shell (and other
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.
For example, if mongod
is running with weak certificate
validation, both of the following mongo
shell clients can
connect to that mongod
:
Important
If the client presents a certificate, the certificate must be valid.
MongoDB Cloud Manager and Ops Manager Monitoring Agent¶
The MongoDB Cloud Manager and Ops Manager Monitoring agents will also have to use encrypted communication in order to gather its statistics. Because the agents already encrypted communications to the MongoDB Cloud Manager/Ops Manager servers, this is just a matter of enabling TLS/SSL support in MongoDB Cloud Manager/Ops Manager on a per host basis.
See the MongoDB Cloud Manager documentation for more information about TLS/SSL configuration.
For Ops Manager, see Ops Manager documentation.
MongoDB Drivers¶
The MongoDB Drivers support encrypted communication. See:
MongoDB Tools¶
Various MongoDB utility programs support encrypted communication. These tools include:
To use encrypted communication with these tools, use the same TLS/SSL options as
the mongo
shell. See mongo Shell Configuration.