Enable TLS/SSL on a Connection

Overview

In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment. TLS is a cryptographic protocol that secures communication between your application and MongoDB. To configure your connection to use TLS, enable the TLS option and provide your certificates for validation when creating a client.

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 using the Netty API or the extensibility of the Java SE API.

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.

val mongoClient = MongoClient.create("mongodb+srv://<user>:<password>@<cluster-url>?tls=true")

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string>"))
    .applyToSslSettings { builder ->
        builder.enabled(true)
    }
    .build()
val mongoClient = MongoClient.create(settings)

Configure Certificates

Kotlin applications that initiate TLS/SSL requests require access to cryptographic certificates that prove identity for the application itself and 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

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

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. 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:

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string>"))
    .applyToSslSettings { builder ->
        builder.enabled(true)
        builder.invalidHostNameAllowed(true)
    }
    .build()
val mongoClient = MongoClient.create(settings);

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".

Configure TLS/SSL by Using Netty SslContext

Include the following import statements:

import com.mongodb.MongoClientSettings
import com.mongodb.connection.SslSettings
import com.mongodb.connection.TransportSettings
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.netty.handler.ssl.SslContextBuilder
import io.netty.handler.ssl.SslProvider

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:

val sslContext = SslContextBuilder.forClient()
    .sslProvider(SslProvider.OPENSSL)
    .build()
val settings = MongoClientSettings.builder()
    .applyToSslSettings { builder: SslSettings.Builder -> builder.enabled(true) }
    .transportSettings(
        TransportSettings.nettyBuilder()
            .sslContext(sslContext)
            .build()
    )
    .build()
val mongoClient = MongoClient.create(settings);

Customize TLS/SSL Configuration through the Java SE SSLContext

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

// You can customize SSL settings using the SSLContext
val sslContext = SSLContext.getDefault()
val settings = MongoClientSettings.builder()
    .applyToSslSettings { builder ->
        builder.enabled(true)
        builder.context(sslContext)
    }
    .build()
val mongoClient = MongoClient.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) before 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.