Docs Menu
Docs Home
/
Languages
/
Kotlin
/
Kotlin Sync Driver
/
Connect

Enable TLS on a Connection

On this page

  • Overview
  • Enable TLS
  • 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 Configuration through the Java SE SSLContext
  • Online Certificate Status Protocol (OCSP)
  • Client-Driven OCSP
  • OCSP Stapling
  • API Documentation

Overview

In this guide, you can learn how to use the TLS security protocol when connecting to MongoDB by using the Kotlin Sync driver.

Enable TLS

You can enable TLS on a connection to your MongoDB instance in the following ways:

  • Setting the tls parameter in your connection string

  • Using the enabled() method from the SslSettings.Builder class when creating a MongoClientSettings instance

Note

DNS Seedlist Protocol Enables TLS

If you connect by using the DNS seedlist protocol, indicated by the mongodb+srv prefix in your connection string, the driver automatically enables TLS.

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

To enable TLS on a connection by using a connection string, set the tls option to true in the options parameter and pass the string to MongoClient.create(), as shown in the following code:

val mongoClient = MongoClient.create("mongodb+srv://<db_username>:<db_password>@<cluster_url>/?tls=true")

To enable TLS within a MongoClientSettings instance, use the applyToSslSettings() builder method. Set the enabled property to true in the SslSettings.Builder block, as shown in the following code:

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

Note

Debugging TLS

If you experience trouble setting up your TLS connection, you can use the -Djavax.net.debug=all system property to view helpful log statements. See Debugging SSL/TLS connections in the Java language documentation for more information.

Configure Certificates

Kotlin applications that initiate TLS requests require access to cryptographic certificates that prove the application's identity and verify other applications with which the Kotlin application interacts. You can configure access to these certificates in your application in the following ways:

  • Using a JVM trust store and JVM key store

  • Using a client-specific trust store and key store

Configure the JVM Trust Store

Note

By default, the JRE includes many commonly used public certificates from signing authorities such as Let's Encrypt. As a result, you can enable TLS when connecting to a MongoDB Atlas instance, or any other server whose certificate is signed by an authority in the JRE's default certificate store, with TLS enabled without configuring the trust store.

The JVM trust store saves certificates that securely identify other applications with which your Kotlin application interacts. By 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 the following system properties to initiate TLS requests.

  • javax.net.ssl.trustStore: Path to a trust store containing the client's TLS certificates

  • javax.net.ssl.trustStorePassword: Password to access the trust store defined in javax.net.ssl.trustStore

These properties ensure that your application can validate the TLS certificate presented by a connected MongoDB instance.

You can create a trust store by using the keytool command line tool from the JDK as shown in the following terminal command:

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 must configure the key store if you configured your MongoDB instance to validate client certificates.

An application that initiates TLS requests must set the following JVM system properties to ensure that the client presents a TLS certificate to the MongoDB server:

  • javax.net.ssl.keyStore: Path to a key store containing the client's TLS/SSL certificates

  • javax.net.ssl.keyStorePassword: Password to access the key store defined in javax.net.ssl.keyStore

You can create a key store by using the keytool or openssl command line tool.

To learn more about configuring a Kotlin application to use TLS, see the JSSE Reference Guide in the Java language documentation.

Configure a Client-Specific Trust Store and Key Store

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

Find an example showing how to configure a client to use an SSLContext instance in the Customize TLS Configuration through the Java SE SSLContext section of this guide.

Disable Hostname Verification

By default, the driver ensures that the hostname included in the server's TLS certificates matches the hostnames provided when constructing a MongoClient. To disable hostname verification for your application, set the invalidHostNameAllowed property of the builder to true in the applytoSslSettings() builder block:

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

Warning

Disabling hostname verification makes your application insecure and potentially vulnerable to expired certificates and foreign processes posing as valid client instances.

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) before Java 8 only enabled the TLS 1.2 protocol in update releases. If your JRE has not enabled the TLS 1.2 protocol, upgrade to a later release to connect by using TLS 1.2.

Customize TLS Configuration through the Java SE SSLContext

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

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

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

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.

Note

The Kotlin Sync 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 more information about OCSP, check out the following resources:

API Documentation

For more information about any of the methods or types discussed in this guide, see the following API documentation:

Back

Connection Options

Next

Stable API