diff --git a/examples/src/test/kotlin/TlsTest.kt b/examples/src/test/kotlin/TlsTest.kt index f4548316..aada1d67 100644 --- a/examples/src/test/kotlin/TlsTest.kt +++ b/examples/src/test/kotlin/TlsTest.kt @@ -1,6 +1,7 @@ - import com.mongodb.ConnectionString import com.mongodb.MongoClientSettings +import com.mongodb.connection.SslSettings +import com.mongodb.connection.TransportSettings import com.mongodb.kotlin.client.coroutine.MongoClient import config.getConfig import io.netty.handler.ssl.SslContextBuilder @@ -12,6 +13,7 @@ import org.junit.jupiter.api.TestInstance import javax.net.ssl.SSLContext import kotlin.test.assertEquals + // :replace-start: { // "terms": { // "CONNECTION_URI_PLACEHOLDER": "\"\"" @@ -67,6 +69,28 @@ internal class TlsTest { assertEquals(true, settings.sslSettings.isEnabled) } + @Test + fun nettyTlsConfigurationTest() = runBlocking { + // :snippet-start: netty-tls-configuration + 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); + // :snippet-end: + mongoClient.close() + assertEquals(true, settings.sslSettings.isEnabled) + } + @Test fun customTlsConfigurationTest() = runBlocking { // :snippet-start: custom-tls-configuration diff --git a/snooty.toml b/snooty.toml index c117c58e..bb4f753e 100644 --- a/snooty.toml +++ b/snooty.toml @@ -32,10 +32,10 @@ core-api = "{+api-root+}/mongodb-driver-core/com/mongodb" driver-api = "{+api-root+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine" stable-api = "Stable API" mongocrypt-version = "{+full-version+}" -nettyVersion = "io.netty:netty-all:4.1.79.Final" snappyVersion = "org.xerial.snappy:snappy-java:1.1.8.4" zstdVersion = "com.github.luben:zstd-jni:1.5.5-2" logbackVersion = "1.2.11" log4j2Version = "2.17.1" serializationVersion = "1.6.0" kotlinx-dt-version = "0.6.1" +netty-version = "io.netty:netty-all:4.1.87.Final" diff --git a/source/examples/generated/TlsTest.snippet.netty-tls-configuration.kt b/source/examples/generated/TlsTest.snippet.netty-tls-configuration.kt index 002634ba..70591be0 100644 --- a/source/examples/generated/TlsTest.snippet.netty-tls-configuration.kt +++ b/source/examples/generated/TlsTest.snippet.netty-tls-configuration.kt @@ -1,12 +1,14 @@ val sslContext = SslContextBuilder.forClient() .sslProvider(SslProvider.OPENSSL) .build() + val settings = MongoClientSettings.builder() - .applyToSslSettings { builder -> builder.enabled(true) } - .streamFactoryFactory( - NettyStreamFactoryFactory.builder() + .applyToSslSettings { builder: SslSettings.Builder -> builder.enabled(true) } + .transportSettings( + TransportSettings.nettyBuilder() .sslContext(sslContext) .build() ) .build() -val mongoClient = MongoClient.create(settings) + +val mongoClient = MongoClient.create(settings); diff --git a/source/fundamentals/connection/tls.txt b/source/fundamentals/connection/tls.txt index 7821feb9..e450d0fc 100644 --- a/source/fundamentals/connection/tls.txt +++ b/source/fundamentals/connection/tls.txt @@ -20,20 +20,24 @@ Enable TLS/SSL on a Connection 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 <{+core-api+}/ConnectionString.html>`__ -or `MongoClientSettings <{+core-api+}/MongoClientSettings.html>`__. +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. -.. note:: Debugging TLS/SSL +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 `__. - If you experience trouble setting up your TLS/SSL connection, you can - use the ``-Djavax.net.debug=all`` system property to view more - log statements. See `the Oracle guide to debugging TLS/SSL connections - `__ - for more information. +.. tip:: Prefer Netty for Asynchronous Apps + + We recommend using Netty for asychronous applications because it supports + asynchronous I/O and handles high connection volumes effectively. To + learn about using Netty to configure your TLS settings, see the + :ref:`kotlin-tls-netty-sslContext` section of this guide. .. _tls-enable: @@ -82,6 +86,14 @@ using a method in the ``MongoClientSettings.Builder`` class. .. literalinclude:: /examples/generated/TlsTest.snippet.tls-mongoclient-settings.kt :language: kotlin +.. 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 more + log statements. See `the Oracle guide to debugging TLS/SSL connections + `__ + for more information. + .. _tls_configure-certificates: Configure Certificates @@ -225,6 +237,38 @@ To restrict your application to use only the TLS 1.2 protocol, set the the TLS 1.2 protocol, upgrade to a later release to connect by using TLS 1.2. +.. _kotlin-tls-netty-sslContext: + +Configure TLS/SSL by Using Netty SslContext +------------------------------------------- + +Include the following import statements: + +.. code-block:: kotlin + :copyable: true + + 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 + +.. note:: Netty Package Version + + The driver tests with Netty package version ``{+netty-version+}`` + +To instruct the driver to use +`io.netty.handler.ssl.SslContext `__, +configure `NettyTransportSettings <{+core-api+}/connection/NettyTransportSettings.html>`__ +when you define your ``MongoClientSettings``. + +Use ``MongoClientSettings.Builder.transportSettings()`` +and ``NettyTransportSettings.Builder.sslContext()`` to build your settings: + +.. literalinclude:: /examples/generated/TlsTest.snippet.netty-tls-configuration.kt + :language: kotlin + .. _tls-custom-sslContext: Customize TLS/SSL Configuration through the Java SE SSLContext