On this page本页内容
Clients must have support for TLS/SSL to connect to a mongod or a mongos instance that require TLS/SSL connections.
Note
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.
mongo Shell Configuration (Using tls Options)¶Note
Starting in version 4.2, MongoDB provides tls options that corresponds to the ssl options. The tls options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.
The procedures in this section use the tls options. For procedures using their ssl aliases, see mongo Shell Configuration (Using ssl Options).
The mongo shell provides various TLS/SSL settings, including:
| TLS Option (New in 4.2) | |
|---|---|
--tls |
Enables TLS/SSL connection. |
--tlsCertificateKeyFile |
Specifies the
|
--tlsCertificateKeyFilePassword |
If the mongo shell’s certificate key file is encrypted. |
--tlsCAFile |
Specifies the Certificate Authority (CA) .pem file for verification of the certificate presented by the mongod or the mongos instance. |
--tlsCertificateSelector |
If running on Windows or macOS, use a certificate from the system certificate store. (New in version 4.0) This option is mutually exclusive with Changed in version 4.4: |
For a complete list of the mongo shell’s tls options, see TLS Options.
For TLS/SSL connections, the mongo shell validates the certificate presented by the mongod or mongos instance:
mongo shell verifies that the certificate is from the specified Certificate Authority (--tlsCAFile. If the certificate is not from the specified CA, the mongo shell will fail to connect.mongo shell verifies that the hostname (specified in --host option or the connection string)
matches the SAN (or, if SAN is not present, the CN) in the certificate presented by the mongod or mongos. If SAN is present, mongo does not match against the CN. If the hostname does not match the SAN (or CN), the mongo shell will fail to connect.
Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names.
To connect a mongo shell to a mongod or mongos that requires TLS/SSL, specify the --host option or use a connection string to specify the hostname. All other TLS/SSL options must be specified using the command-line options.
tls Options)¶Note
The procedure uses the tls options (available starting in MongoDB 4.2). For procedures using their ssl aliases, see mongo Shell Configuration (Using ssl Options).
To connect to a mongod or mongos instance that requires encrypted communication, start the mongo shell with:
--tls--host and --tlsCAFile to validate the server certificate.For example, consider a mongod instance running on hostname.example.com with the following options:
To connect to the instance, start a mongo shell with the following options:
The mongo shell verifies the certificate presented by the mongod instance against the specified hostname and the CA file.
tls Options)¶Note
The procedure uses the tls options (available starting in MongoDB 4.2). For procedures using their ssl aliases, see mongo Shell Configuration (Using ssl Options).
To connect to a mongod or mongos that requires CA-signed client certificates, start the mongo shell with:
--tls--host and the --tlsCAFile to validate the server certificate,--tlsCertificateKeyFile option to specify the client certificate to present to the server.For example, consider a mongod instance running on hostname.example.com with the following options:
To connect to the instance, start a mongo shell with the following options:
You can also use the --tlsCertificateSelector option to specify the client certificate from the system certificate store instead of using --tlsCertificateKeyFile. If the CA file is also in the system certificate store, you can omit the --tlsCAFile option as well. For example, to use a certificate with the CN (Common Name) of myclient.example.net and the CA file from the system certificate store on macOS, start a mongo shell with the following options:
Although still available, the mongo shell --ssl, --sslCAFile, --sslPEMKeyFile, --sslCertificateSelector are deprecated as of MongoDB 4.2.
--tlsAllowInvalidCertificates Option¶Warning
Although available, avoid using the --tlsAllowInvalidCertificates option if possible. If the use of --tlsAllowInvalidCertificates is necessary, only use the option on systems where intrusion is not possible.
If the mongo shell runs with the --tlsAllowInvalidCertificates option, the mongo shell 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. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see --tlsAllowInvalidHostnames.
mongo Shell Configuration (Using ssl Options)¶The mongo shell provides various TLS/SSL settings, including:
| SSL Option (Deprecated in 4.2) | |
|---|---|
--ssl |
Enables TLS/SSL connection. |
--sslPEMKeyFile |
Specifies the .pem file that contains the mongo shell’s certificate and key to present to the mongod or mongos instance. |
--sslPEMKeyPassword |
If the mongo shell’s certificate key file is encrypted. |
--sslCAFile |
Specifies the Certificate Authority (CA) .pem file for verification of the certificate presented by the mongod or the mongos instance. |
--sslCertificateSelector |
If running on Windows or macOS, use a certificate from the system certificate store. (New in version 4.0) |
For a complete list of the mongo shell’s ssl options, see SSL Options.
For TLS/SSL connections, the mongo shell validates the certificate presented by the mongod or mongos instance:
mongo shell verifies that the certificate is from the specified Certificate Authority --sslCAFile. If the certificate is not from the specified CA, the mongo shell will fail to connect.mongo shell verifies that the hostname (specified in --host option or the connection string)
matches the SAN (or, if SAN is not present, the CN) in the certificate presented by the mongod or mongos. If SAN is present, mongo does not match against the CN. If the hostname does not match the SAN (or CN), the mongo shell will fail to connect.
Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names.
To connect a mongo shell to a mongod or mongos that requires TLS/SSL, specify the --host option or use a connection string to specify the hostname. All other TLS/SSL options must be specified using the command-line options.
--ssl Options)¶Note
The procedure uses the ssl options. For procedures using the tls aliases (available starting in MongoDB 4.2), see mongo Shell Configuration (Using tls Options).
To connect to a mongod or mongos instance that requires encrypted communication, start the mongo shell with:
--ssl--host and --sslCAFile to validate the server certificate.For example, consider a mongod instance running on hostname.example.com with the following options:
To connect to the instance, start a mongo shell with the following options:
The mongo shell verifies the certificate presented by the mongod instance against the specified hostname and the CA file.
ssl Options)¶Note
The procedure uses the ssl options. For procedures using the tls aliases (available starting in MongoDB 4.2), see mongo Shell Configuration (Using tls Options).
To connect to a mongod or mongos that requires CA-signed client certificates, start the mongo shell with:
--ssl--host and the --sslCAFile to validate the server certificate,--sslPEMKeyFile option to specify the client certificate to present to the server.For example, consider a mongod instance running on hostname.example.com with the following options:
To connect to the instance, start a mongo shell with the following options:
You can also use the --sslCertificateSelector option to specify the client certificate from the system certificate store instead of using --sslPEMKeyFile. If the CA file is also in the system certificate store, you can omit the --sslCAFile option as well. For example, to use a certificate with the CN (Common Name) of myclient.example.net and the CA file from the system certificate store on macOS, start a mongo shell with the following options:
--sslAllowInvalidCertificates Option¶Warning
Although available, avoid using the --sslAllowInvalidCertificates option if possible. If the use of --sslAllowInvalidCertificates is necessary, only use the option 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. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see --sslAllowInvalidHostnames.
MongoDB Atlas uses TLS/SSL to encrypt the connections to your databases.
The MongoDB Cloud Manager and Ops Manager Monitoring agents use encrypted communication to gather its statistics. Because the agents already encrypt 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.
For more information, see:
Various MongoDB utility programs support encrypted communication. These tools include:
To use encrypted communication with these tools, use the same ssl options as the mongo shell. See mongo Shell Configuration (Using ssl Options).
See also参阅