Docs Home → Develop Applications → MongoDB Drivers → Java Sync

Enable TLS/SSL on a Connection

On this page

Overview

Enable TLS/SSL
Configure Certificates
Configure the JVM Trust Store
Configure the JVM Key Store
Configure a Client-Specific Trust Store and Key Store
Disable Hostname Verification
Restrict Connections to TLS 1.2 Only
Customize TLS/SSL Configuration through the Java SE SSLContext
Customize TLS/SSL Configuration through the Netty SslContext
Online Certificate Status Protocol (OCSP)
Client-Driven OCSP
OCSP Stapling

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of the Java Sync Driver.

Overview

In this guide, you can learn how to connect to MongoDB instances with the TLS/SSL security protocol using the underlying TLS/SSL support in the JDK. To configure your connection to use TLS/SSL, enable the TLS/SSL settings in either the ConnectionString or MongoClientSettings.

Note

Debugging TLS/SSL

If you experience trouble setting up your TLS/SSL connection, you can use the -Djavax.net.debug=all system property to view additional log statements. See the Oracle guide to debugging TLS/SSL connections for more information.

Enable TLS/SSL

You can enable TLS/SSL for the connection to your MongoDB instance in two different ways: through a parameter in your connection string, or using a method in the MongoClientSettings.Builder class.

Note

If you connect by using the DNS seedlist protocol, indicated by the mongodb+srv prefix in your connection string, the driver enables TLS/SSL. To disable it, set the tls or ssl parameter value to false in your connection string or MongoClientSettings instance.

To learn more about connection behavior when you use a DNS seedlist, see the SRV Connection Format section in the Server manual.

Configure Certificates

Java applications that initiate TLS/SSL requests require access to cryptographic certificates that prove identity for the application itself as well as other applications with which the application interacts. You can configure access to these certificates in your application with the following mechanisms:

The JVM Trust Store and JVM Key Store
A Client-Specific Trust Store and Key Store

Note

The following sections are 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 the JVM Trust Store

Note

By default, the JRE includes many commonly used public certificates from signing authorities like Let's Encrypt. As a result, you can connect to instances of MongoDB Atlas (or any other server whose certificate is signed by an authority in the JRE's default certificate store) with TLS/SSL without configuring the trust store.

The JVM trust store saves certificates that securely identify other applications with which your Java application interacts. Using these certificates, your application can prove that the connection to another application is genuine and secure from tampering by third parties.

If your MongoDB instance uses a certificate that is signed by an authority that is not present in the JRE's default certificate store, your application must configure two system properties to initiate SSL/TLS requests. These properties ensure that your application is able to validate the TLS/SSL certificate presented by a connected MongoDB instance.

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 the trust store defined in javax.net.ssl.trustStore

You can create a trust store with the keytool command line tool provided as part of the JDK:

keytool -importcert -trustcacerts -file <path to certificate authority file>
         -keystore <path to trust store> -storepass <password>

Configure the JVM Key Store

Note

By default, MongoDB instances do not perform client certificate validation. You only need to configure the key store if you explicitly configured your MongoDB instance to validate client certificates.

The JVM key store saves certificates that securely identify your Java application to other applications. Using these certificates, other applications can prove that the connection to your application is genuine and secure from tampering by third parties.

An application that initiates TLS/SSL requests needs to set two JVM system properties to ensure that the client presents a TLS/SSL certificate to the MongoDB deployment:

javax.net.ssl.keyStore: the path to a key store containing the client's TLS/SSL certificates
javax.net.ssl.keyStorePassword: the password to access the key store defined in javax.net.ssl.keyStore

You can create a key store with the keytool or openssl command line tools.

For more information on configuring a Java application to use TLS/SSL, please refer to the JSSE Reference Guide.

Configure a Client-Specific Trust Store and Key Store

You can configure a client-specific trust store and key store using the init() method of the SSLContext class.

You can find an example showing how to configure a client with an SSLContext instance in the Customize TLS/SSL Configuration with an SSLContext section of this guide.

For more information on the SSLContext class, see the API documentation for SSL Context.

Disable Hostname Verification

By default, the driver ensures that the hostname included in the server's TLS/SSL certificates matches the hostnames provided when constructing a MongoClient. If you need to disable hostname verification for your application, you can explicitly disable this by setting the invalidHostNameAllowed property of the builder to true in the applytoSslSettings() builder lambda:

MongoClientSettings settings = MongoClientSettings.builder()
     .applyToSslSettings(builder -> {
                 builder.enabled(true);
                 builder.invalidHostNameAllowed(true);
             })
     .build();

Warning

Disabling hostname verification can make your configuration insecure. You should only disable hostname verification for testing purposes or when there is no other alternative.

Restrict Connections to TLS 1.2 Only

To restrict your application to use only the TLS 1.2 protocol, set the jdk.tls.client.protocols system property to "TLSv1.2".

Note

Java Runtime Environments (JREs) prior to Java 8 only enabled the TLS 1.2 protocol in update releases. If your JRE has not enabled the TLS 1.2 protocol, you may need to upgrade to a later release to connect using TLS 1.2.

Customize TLS/SSL Configuration through the Java SE SSLContext

If your TLS/SSL configuration requires additional customization, you can set the sslContext property of your MongoClient by passing an SSLContext object to the builder in the applyToSslSettings() lambda:

SSLContext sslContext = ...
MongoClientSettings settings = MongoClientSettings.builder()
     .applyToSslSettings(builder -> {
                 builder.enabled(true);
                 builder.context(sslContext);
             })
     .build();
MongoClient client = MongoClients.create(settings);

Customize TLS/SSL Configuration through the Netty SslContext

If you use the driver with Netty for network IO, you have an option to plug an alternative TLS/SSL protocol implementation provided by Netty.

import com.mongodb.MongoClientSettings;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;
import com.mongodb.connection.netty.NettyStreamFactoryFactory;
import io.netty.handler.ssl.SslContext;
import io.netty.handler.ssl.SslContextBuilder;
import io.netty.handler.ssl.SslProvider;

To instruct the driver to use io.netty.handler.ssl.SslContext, use the NettyStreamFactoryFactory.Builder.sslContext method. See the method documentation for details about the different io.netty.handler.ssl.SslProvider variants the driver supports and the implications of using them.

SslContext sslContext = SslContextBuilder.forClient()
        .sslProvider(SslProvider.OPENSSL)
        .build();
MongoClientSettings settings = MongoClientSettings.builder()
        .applyToSslSettings(builder -> builder.enabled(true))
        .streamFactoryFactory(NettyStreamFactoryFactory.builder()
                .sslContext(sslContext)
                .build())
        .build();
MongoClient client = MongoClients.create(settings);

Online Certificate Status Protocol (OCSP)

OCSP is a standard used to check whether X.509 certificates have been revoked. A certificate authority can add an X.509 certificate to the Certificate Revocation List (CRL) prior to the expiry time to invalidate the certificate. When a client sends an X.509 certificate during the TLS handshake, the CA's revocation server checks the CRL and returns a status of "good", "revoked", or "unknown".

The driver supports the following variations of OCSP:

Client-Driven OCSP
OCSP Stapling

The following sections describe the differences between them and how to enable them for your application.

Note

The Java driver uses the JVM arguments configured for the application and cannot be overridden for a specific MongoClient instance.

Client-Driven OCSP

In client-driven OCSP, the client sends the certificate in an OCSP request to an OCSP responder after receiving the certificate from the server. The OCSP responder checks the status of the certificate with a certificate authority (CA) and reports whether it's valid in a response sent to the client.

To enable client-driven OCSP for your application, set the following JVM system properties:

Property	Value
`com.sun.net.ssl.checkRevocation`	Set this property to `true` to enable revocation checking.
`ocsp.enable`	Set this property to `true` to enable client-driven OCSP.

Warning

If the OCSP responder is unavailable, the TLS support provided by the JDK reports a "hard fail". This differs from the "soft fail" behavior of the MongoDB Shell and some other drivers.

OCSP Stapling

OCSP stapling is a mechanism in which the server must obtain the signed certificate from the certificate authority (CA) and include it in a time-stamped OCSP response to the client.

To enable OCSP stapling for your application, set the following JVM system properties:

Property	Description
`com.sun.net.ssl.checkRevocation`	Set this property to `true` to enable revocation checking.
`jdk.tls.client.enableStatusRequestExtension`	Set this property to `true` to enable OCSP stapling. If unset or set to `false`, the connection can proceed regardless of the presence or status of the certificate revocation response.

For additional information about OCSP, check out the following resources:

Oracle JDK 8 Documentation on how to enable OCSP for an application
Official IETF specification for OCSP (RFC 6960)

← Network Compression Connect to MongoDB Using a JNDI Datasource →