TLS/SSL
On this page
- MongoClient API
- Specify TLS/SSL in ConnectionString
- Specify TLS/SSL in MongoClientSettings
- Specify Java SE SSLContext in MongoClientSettings
- Customize TLS/SSL Configuration through the Netty SslContext
- Disable Hostname Verification
- Common TLS/SSL Configuration Tasks
- Configure Trust Store and Key Store
- Forcing TLS v1.2
- OCSP
By default, the driver supports TLS/SSL connections to MongoDB servers using the underlying support for TLS/SSL provided by the JDK. This can be changed either by utilizing the extensibility of the Java SE API, or by using the Netty API.
MongoClient API
You can configure the driver to use
TLS/SSL by specifying options in a ConnectionString
or in a
MongoClientSettings
instance.
Specify TLS/SSL in ConnectionString
Include the following import statements:
import com.mongodb.reactivestreams.client.MongoClients; import com.mongodb.reactivestreams.client.MongoClient;
To specify TLS/SSL in a ConnectionString
, specify ssl=true
as
part of the connection string:
MongoClient mongoClient = MongoClients.create("mongodb://localhost/?ssl=true");
Specify TLS/SSL in MongoClientSettings
Include the following import statements:
import com.mongodb.MongoClientSettings; import com.mongodb.reactivestreams.client.MongoClients; import com.mongodb.reactivestreams.client.MongoClient;
To specify TLS/SSL in a MongoClientSettings
instance, set the
enabled
property to true
:
MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> builder.enabled(true)) .build(); MongoClient client = MongoClients.create(settings);
Specify Java SE SSLContext in MongoClientSettings
Include the following import statements:
import javax.net.ssl.SSLContext; import com.mongodb.MongoClientSettings; import com.mongodb.MongoClient;
To specify the javax.net.ssl.SSLContext
with
MongoClientSettings
, set the sslContext
property:
SSLContext sslContext = ... MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> builder.enabled(true).context(sslContext)) .build(); MongoClient client = new MongoClient(settings);
Customize TLS/SSL Configuration through the Netty SslContext
Include the following import statements:
import com.mongodb.MongoClientSettings; import com.mongodb.client.MongoClients; import com.mongodb.client.MongoClient; import io.netty.handler.ssl.SslContext; import io.netty.handler.ssl.SslContextBuilder; import io.netty.handler.ssl.SslProvider;
Note
The driver tests with Netty version io.netty:netty-all:4.1.87.Final
To instruct the driver to use
io.netty.handler.ssl.SslContext,
configure NettyTransportSettings
when you define your MongoClientSettings
.
Use MongoClientSettings.Builder.transportSettings()
and NettyTransportSettings.Builder.sslContext()
to build your settings:
SslContext sslContext = SslContextBuilder.forClient() .sslProvider(SslProvider.OPENSSL) .build(); MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> builder.enabled(true)) .transportSettings(TransportSettings.nettyBuilder() .sslContext(sslContext) .build()) .build(); MongoClient client = MongoClients.create(settings);
For more details about the io.netty.handler.ssl.SslProvider
, see the Netty
documentation.
Disable Hostname Verification
By default, the driver ensures that the hostname included in the
server's SSL certificate matches the hostname provided when
constructing a MongoClient
.
If your application needs to disable hostname verification, you must
explicitly indicate this in MongoClientSettings
:
MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> { builder.enabled(true); builder.invalidHostNameAllowed(true); }) .build();
Common TLS/SSL Configuration Tasks
This section is based on the documentation for Oracle JDK, so some parts may be inapplicable to your JDK or to the custom TLS/SSL implementation you use.
Configure Trust Store and Key Store
You might configure trust stores and key stores specific to the
client by using javax.net.ssl.SSLContext.init(KeyManager[] km,
TrustManager[] tm, SecureRandom random)
, or you might set the JVM default
ones.
Set the Default Trust Store
A typical application will need to set several JVM system properties to ensure that the client can validate the TLS/SSL certificate presented by the server:
javax.net.ssl.trustStore
: the path to a trust store containing the certificate of the signing authorityjavax.net.ssl.trustStorePassword
: the password to access this trust store
The trust store is typically created with the keytool
command-line
program provided as part of the JDK:
keytool -importcert -trustcacerts -file <path to certificate authority file> -keystore <path to trust store> -storepass <trust store password>
Set the Default Key Store
A typical application will also need to set several JVM system properties to ensure that the client presents a TLS/SSL client certificate to the MongoDB server:
javax.net.ssl.keyStore
: the path to a key store containing the clients TLS/SSL certificatesjavax.net.ssl.keyStorePassword
: the password to access this key store
The key store is typically created with the keytool
or the
openssl
command-line program. For example, if you have a file with
the client certificate and its private key, and you want to create a key
store in the PKCS #12
format, you can run the following command:
openssl pkcs12 -export -in <path to client certificate & private key file> -out <path to key store> -passout pass:<trust store password>
To learn more about configuring a Java application for TLS/SSL, refer to the JSSE Reference Guide.
Forcing TLS v1.2
Some applications might want to force only the TLS 1.2 protocol. To do
this, set the jdk.tls.client.protocols
system property to TLSv1.2
.
Java runtime environments before Java 8 started to enable the TLS 1.2 protocol only in later updates, as shown in the previous section. For the driver to force the use of the TLS 1.2 protocol with a Java runtime environment before Java 8, ensure that the update has TLS 1.2 enabled.
OCSP
Note
The driver cannot enable OCSP by default on an individual
MongoClient
basis.
Client-Driven OCSP
An application will need to set the following JVM system and security properties to ensure that client-driven OCSP is enabled:
com.sun.net.ssl.checkRevocation
: when set totrue
, this system property enables revocation checkingocsp.enable
: When set totrue
, this security property enables client-driven OCSP
To configure an application to use client-driven OCSP, the application must already be set up to connect to a server using TLS. Setting these system properties is required to enable client-driven OCSP.
Note
The support for TLS provided by the JDK utilizes "hard fail" behavior
in the case of an unavailable OCSP responder in contrast to
mongosh
and the drivers that utilize "soft fail" behavior.
OCSP Stapling
Important
The following exception may occur when using OCSP stapling with Java runtime environments that use the TLS 1.3 protocol (Java 11 and higher use TLS 1.3 by default):
javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request
The exception is due to a known issue with TLS 1.3 in Java 11 and
higher. To avoid this exception when using Java runtime environments
that operate on the TLS 1.3 protocol, you can force the application to use the
TLS 1.2 protocol. To do this, set the jdk.tls.client.protocols
system property to TLSv1.2
.
An application will need to set several JVM system properties to set up OCSP stapling:
jdk.tls.client.enableStatusRequestExtension
: when set totrue
(its default value), this enables OCSP stapling.com.sun.net.ssl.checkRevocation
: when set totrue
, this enables revocation checking. If this property is not set totrue
, then the connection will be allowed to proceed regardless of the presence or status of the revocation information.
To configure an application to use OCSP stapling, the application must already be set up to connect to a server using TLS, and the server must be set up to staple an OCSP response to the certificate it returns as part of the TLS handshake.
To learn more about configuring a Java application to use OCSP, refer to Client-Driven OCSP and OCSP Stapling in the Java documentation.