diff --git a/source/security/tls.txt b/source/security/tls.txt index d38ed1440..26dc20e39 100644 --- a/source/security/tls.txt +++ b/source/security/tls.txt @@ -303,34 +303,21 @@ 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. -.. _tls-custom-sslContext: - -Customize TLS/SSL Configuration through the Java SE SSLContext --------------------------------------------------------------- +.. _java-netty-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: +Customize TLS/SSL Configuration through the Netty SslContext +------------------------------------------------------------ -.. code-block:: java +We recommend using `Netty `__ for network IO, as +Netty supports non-blocking, asynchronous IO and handles high connection +volumes effectively. When using Netty, you can plug an alternative +TLS/SSL protocol implementation. - SSLContext sslContext = ... - MongoClientSettings settings = MongoClientSettings.builder() - .applyToSslSettings(builder -> { - builder.enabled(true); - builder.context(sslContext); - }) - .build(); - MongoClient client = MongoClients.create(settings); +.. note:: -Customize TLS/SSL Configuration through the Netty SslContext ------------------------------------------------------------- + The driver tests with Netty version ``{+nettyVersion+}`` -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. +The example in this section requires the following import statements: .. code-block:: java :copyable: true @@ -342,39 +329,59 @@ provided by Netty. import io.netty.handler.ssl.SslContextBuilder; import io.netty.handler.ssl.SslProvider; -.. note:: - - The driver tests with Netty version ``{+nettyVersion+}`` - To instruct the driver to use `io.netty.handler.ssl.SslContext `__, configure `NettyTransportSettings <{+core-api+}/connection/NettyTransportSettings.html>`__ when you define your `MongoClientSettings <{+core-api+}/MongoClientSettings.html>`__. -Use `MongoClientSettings.Builder.transportSettings + +Use `MongoClientSettings.Builder.transportSettings() <{+core-api+}/MongoClientSettings.Builder.html#transportSettings(com.mongodb.connection.TransportSettings)>`__ -and `NettyTransportSettings.Builder.sslContext +and `NettyTransportSettings.Builder.sslContext() <{+core-api+}/connection/NettyTransportSettings.Builder.html#sslContext(io.netty.handler.ssl.SslContext)>`__ to build your settings: .. code-block:: java - :emphasize-lines: 3-8 + :emphasize-lines: 7-9 :copyable: true 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 -`__ +To learn more about the ``io.netty.handler.ssl.SslProvider``, see the `Netty +documentation `__. + +.. _tls-custom-sslContext: + +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: + +.. code-block:: java + + SSLContext sslContext = ... + MongoClientSettings settings = MongoClientSettings.builder() + .applyToSslSettings(builder -> { + builder.enabled(true); + builder.context(sslContext); + }) + .build(); + MongoClient client = MongoClients.create(settings); Online Certificate Status Protocol (OCSP) -----------------------------------------