mongod
and mongos
for TLS/SSL¶On this page本页内容
This document helps you to configure a new MongoDB instance to support TLS/SSL. For instructions on upgrading a cluster currently not using TLS/SSL to using TLS/SSL, see Upgrade a Cluster to Use TLS/SSL instead.
Starting in version 4.0, MongoDB uses the native TLS/SSL OS libraries:
Windows | Secure Channel (Schannel) |
Linux/BSD | OpenSSL |
macOS | Secure Transport |
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.
For production use, your MongoDB deployment should use valid certificates generated and signed by a single certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by a third-party TLS/SSL vendor. Obtaining and managing certificates is beyond the scope of this documentation.
mongod
and mongos
Certificate Key File¶When establishing a TLS/SSL connection, the mongod
/mongos
presents a certificate key file to its clients to establish its identity. [1] The certificate key file contains a public key certificate and its associated private key, but only the public component is revealed to the client.
MongoDB can use any valid TLS/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 to prevent eavesdropping on the connection, there will be no validation of server identity. This 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.
With regards to certificates for replica set and sharded cluster members, it is advisable to use different certificates on different servers. This minimizes exposure of the private key and allows for hostname validation.
[1] | For FIPS mode, ensure that the certificate is FIPS-compliant (i.e uses a FIPS-compliant algorithm) and the private key meets the PKCS#8 format, various conversion tools exist, such as openssl pkcs8 and others. |
net.tls
Settings)¶Note
Starting in version 4.2, MongoDB provides net.tls
settings (and corresponding command-line options) that corresponds to the net.ssl
settings (and their corresponding command-line options). The net.tls
settings provide identical functionality as the net.ssl
options since MongoDB has always supported TLS 1.0 and later.
The procedures in this section use the net.tls
settings. For procedures using the net.ssl
alias, see Procedures (Using net.ssl Settings).
mongod
and mongos
with TLS/SSL Certificate and Key¶The following section configures mongod
/mongos
to use TLS/SSL connections. With these TLS/SSL settings, mongod
/mongos
presents its certificate key file to the client. However, the mongod
/mongos
does not require a certificate key file from the client to verify the client’s identity. To require client’s certificate key file, see Set Up mongod and mongos with Client Certificate Validation instead.
Note
The procedure uses the net.tls
settings (available starting in MongoDB 4.2). For procedures using the net.ssl
settings, see Procedures (Using net.ssl Settings).
To use TLS/SSL connections, include the following TLS/SSL settings in your mongod
/mongos
instance’s configuration file:
Setting | |
---|---|
net.tls.mode |
Set to This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value |
net.tls.certificateKeyFile |
Set to the path of the file that contains the TLS/SSL certificate and key. The |
For example, consider the following configuration file for a mongod
instance:
Starting in MongoDB 4.0, you can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specify net.tls.certificateSelector
instead of specifying the certificate key file.
Setting | |
---|---|
net.tls.mode |
Set to This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value |
net.tls.certificateSelector |
Set to the property (either This setting is used to select the certificate. See |
For example, consider the following configuration file for a mongod
instance:
A mongod
instance that uses the above configuration can only use TLS/SSL connections:
That is, clients must specify TLS/SSL connections. See Connect to MongoDB Instance Using Encryption (tls Options) for more information on connecting with TLS/SSL.
See also参阅
You can also configure mongod
and mongos
using command-line options instead of the configuration file:
mongod
, see: --tlsMode
;
--tlsCertificateKeyFile
; and --tlsCertificateSelector
.mongos
, see: --tlsMode
;
--tlsCertificateKeyFile
; and --tlsCertificateSelector
.mongod
and mongos
with Client Certificate Validation¶The following section configures mongod
/mongos
to use TLS/SSL connections and perform client certificate validation. With these TLS/SSL settings:
mongod
/mongos
presents its certificate key file to the client for verification.mongod
/mongos
requires a certificate key file from the client to verify the client’s identity.Note
The procedure uses the net.tls
settings (available starting in MongoDB 4.2). For procedures using the net.ssl
settings, see Procedures (Using net.ssl Settings).
To use TLS/SSL connections and perform client certificate validation, include the following TLS/SSL settings in your mongod
/mongos
instance’s configuration file:
Note
Starting in MongoDB 4.0, you can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specify net.ssl.certificateSelector
instead of specifying the certificate key file.
Setting | |
---|---|
net.tls.mode |
Set to This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify either the value |
net.tls.certificateKeyFile |
Set to the path of the file that contains the TLS/SSL certificate and key. The |
net.tls.CAFile |
Set to the path of the file that contains the certificate chain for verifying client certificates. The |
For example, consider the following configuration file for a mongod
instance:
A mongod
instance that uses the above configuration can only use TLS/SSL connections and requires valid certificate from its clients:
That is, clients must specify TLS/SSL connections and presents its certificate key file to the instance. See Connect to MongoDB Instance that Requires Client Certificates (tls Options) for more information on connecting with TLS/SSL.
See also参阅
You can also configure mongod
and mongos
using command-line options instead of the configuration file:
mongod
, see --tlsMode
, --tlsCertificateKeyFile
, and --tlsCAFile
.mongos
, see --tlsMode
, --tlsCertificateKeyFile
, --tlsCAFile
.Note
The procedure uses the net.tls
settings (available starting in MongoDB 4.2). For procedures using the net.ssl
settings, see Procedures (Using net.ssl Settings).
To prevent clients with revoked certificates from connecting to the mongod
or mongos
instance, you can use:
Starting in version 4.4, to check for certificate revocation, MongoDB enables
the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store
.
In versions 4.0 and 4.2, the use of OCSP is available only through the use of system certificate store
on Windows or macOS.
To specify a CRL file, include net.tls.CRLFile
set to a file that contains revoked certificates.
For example:例如:
Clients who presents certificates that are listed in the /etc/ssl/revokedCertificates.pem
will not be able to connect.
See also参阅
You can also configure the revoked certificate list using the command-line option.
mongod
, see --tlsCRLFile
.mongos
, see --tlsCRLFile
.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, you may only want to validate certificates from clients that present a certificate.
Note
The procedure uses the net.tls
settings (available starting in MongoDB 4.2). For procedures using the net.ssl
settings, see Procedures (Using net.ssl Settings).
To bypass client certificate validation for clients that do not present a certificate, include net.tls.allowConnectionsWithoutCertificates
set to true
.
For example:例如:
A mongod
/mongos
running with these settings allows connection from:
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 TLS/SSL.
See TLS/SSL Configuration for Clients for more information on TLS/SSL connections for clients.
See also参阅
You can also configure using the command-line options:
mongod
, see --tlsAllowConnectionsWithoutCertificates
.mongos
, see --tlsAllowConnectionsWithoutCertificates
.Note
The procedure uses the net.tls
settings (available starting in MongoDB 4.2). For procedures using the net.ssl
settings, see Procedures (Using net.ssl Settings).
To prevent MongoDB servers from accepting incoming connections that use specific protocols, include net.tls.disabledProtocols
set to the disallowed protocols.
For example, the following configuration prevents mongod
/mongos
from accepting incoming connections that use either TLS1_0
or TLS1_1
See also参阅
You can also configure using the command-line options:
mongod
, see --tlsDisabledProtocols
.mongos
, see --tlsDisabledProtocols
.If the certificate key files for mongod
/mongos
are encrypted, sinclude net.tls.certificateKeyFilePassword
set to the passphrase.
Tip
Starting in MongoDB 4.2, to avoid specifying the passphrase in cleartext, you can use an expansion value in the configuration file.
See also参阅
You can also configure using the command-line options:
mongod
, see --tlsCertificateKeyFilePassword
.mongos
, see --tlsCertificateKeyFilePassword
.Note
FIPS-compatible TLS/SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.
See Configure MongoDB for FIPS for more details.
To configure TLS/SSL support for clients, see TLS/SSL Configuration for Clients.
net.ssl
Settings)¶Note
Starting in version 4.2, MongoDB provides net.tls
settings (and corresponding command-line options) that corresponds to the net.ssl
settings (and their corresponding command-line options). The net.tls
settings provide identical functionality as the net.ssl
options since MongoDB has always supported TLS 1.0 and later.
The procedures in this section use the net.ssl
settings. For procedures using the net.tls
aliases, see Procedures (Using net.tls Settings).
mongod
and mongos
with TLS/SSL Certificate and Key¶The following section configures mongod
/mongos
to use TLS/SSL connections. With these TLS/SSL settings, mongod
/mongos
presents its certificate key file to the client. However, the mongod
/mongos
does not require a certificate key file from the client to verify the client’s identity. To require client’s certificate key file, see Set Up mongod and mongos with Client Certificate Validation instead.
To use TLS/SSL connections, include the following TLS/SSL settings in your mongod
/mongos
instance’s configuration file:
Setting | |
---|---|
net.ssl.mode |
Set to This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify |
net.ssl.PEMKeyFile |
Set to the The If the key is encrypted, specify the passphrase ( |
For example, consider the following configuration file for a mongod
instance:
Starting in MongoDB 4.0, you can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specify net.ssl.certificateSelector
instead of specifying the certificate key file.
Setting | |
---|---|
net.ssl.mode |
Set to This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify |
net.ssl.certificateSelector |
Set to the property (either This setting is used to select the certificate. See |
For example, consider the following configuration file for a mongod
instance:
A mongod
instance that uses the above configuration can only use TLS/SSL connections:
That is, clients must specify TLS/SSL connections. See Connect to MongoDB Instance Using Encryption (--ssl Options) for more information on connecting with TLS/SSL.
See also参阅
You can also configure mongod
and mongos
using command-line options instead of the configuration file:
mongod
, see: --sslMode
; --sslPEMKeyFile
;
and --sslCertificateSelector
.mongos
, see: --sslMode
;
--sslPEMKeyFile
; and --sslCertificateSelector
.mongod
and mongos
with Client Certificate Validation¶The following section configures mongod
/mongos
to use TLS/SSL connections and perform client certificate validation. With these TLS/SSL settings:
mongod
/mongos
presents its certificate key file to the client for verification.mongod
/mongos
requires a certificate key file from the client to verify the client’s identity.To use TLS/SSL connections, include the following TLS/SSL settings in your mongod
/mongos
instance’s configuration file:
Note
Starting in MongoDB 4.0, you can use system SSL certificate stores for Windows and macOS. To use the system SSL certificate store, specify net.ssl.certificateSelector
instead of specifying the certificate key file.
Setting | |
---|---|
net.ssl.mode |
Set to This setting restricts each server to use only TLS/SSL encrypted connections. You can also specify |
net.ssl.PEMKeyFile |
Set to the The If the key is encrypted, specify the passphrase ( |
net.ssl.CAFile |
Set to the path of the file that contains the certificate chain for verifying client certificates. The |
For example, consider the following configuration file for a mongod
instance:
A mongod
instance that uses the above configuration can only use TLS/SSL connections and requires valid certificate from its clients:
That is, clients must specify TLS/SSL connections and presents its certificate key file to the instance. See Connect to MongoDB Instance that Requires Client Certificates (ssl Options) for more information on connecting with TLS/SSL.
See also参阅
You can also configure mongod
and mongos
using command-line options instead of the configuration file:
mongod
, see --sslMode
, --sslPEMKeyFile
, and --sslCAFile
.mongos
, see --sslMode
, --sslPEMKeyFile
, and --sslCAFile
.To prevent clients with revoked certificates from connecting to the mongod
or mongos
instance, you can use:
Starting in version 4.4, to check for certificate revocation, MongoDB enables
the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store
.
In versions 4.0 and 4.2, the use of OCSP is available only through the use of system certificate store
on Windows or macOS.
To specify a CRL file, include net.ssl.CRLFile
set to a file that contains revoked certificates.
For example:例如:
Clients who presents certificates that are listed in the /etc/ssl/revokedCertificates.pem
will not be able to connect.
See also参阅
You can also configure the revoked certificate list using the command-line option.
mongod
, see --sslCRLFile
.mongos
, see --sslCRLFile
.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, you may only want to validate certificates from clients that present a certificate.
To bypass client certificate validation for clients that do not present a certificate, include net.ssl.allowConnectionsWithoutCertificates
set to true
.
For example:例如:
A mongod
/mongos
running with these settings allows connection from:
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 TLS/SSL.
See TLS/SSL Configuration for Clients for more information on TLS/SSL connections for clients.
See also参阅
You can also configure using the command-line options:
mongod
, see --sslAllowConnectionsWithoutCertificates
.mongos
, see --sslAllowConnectionsWithoutCertificates
.To prevent MongoDB servers from accepting incoming connections that use specific protocols, include net.ssl.disabledProtocols
set to the disallowed protocols.
For example, the following configuration prevents mongod
/mongos
from accepting incoming connections that use either TLS1_0
or TLS1_1
See also参阅
You can also configure using the command-line options:
mongod
, see --sslDisabledProtocols
.mongos
, see --sslDisabledProtocols
.If the certificate key files for mongod
/mongos
are encrypted, include net.ssl.PEMKeyPassword
set to the passphrase.
See also参阅
You can also configure using the command-line options:
mongod
, see --sslPEMKeyPassword
.mongos
, see --sslPEMKeyPassword
.Note
FIPS-compatible TLS/SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.
See Configure MongoDB for FIPS for more details.
To configure TLS/SSL support for clients, see TLS/SSL Configuration for Clients.