Docs Menu
Docs Home
/
Languages
/
Java
/
Java Reactive Streams Driver
/
Tutorials
/
Connect to MongoDB

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 authority

  • javax.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 certificates

  • javax.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 to true, this system property enables revocation checking

  • ocsp.enable: When set to true, 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 to true (its default value), this enables OCSP stapling.

  • com.sun.net.ssl.checkRevocation: when set to true, this enables revocation checking. If this property is not set to true, 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.

Back

Connect to MongoDB