Add support for setting io.netty.handler.ssl.SslContext (#734)

This may be used as a convenient way to utilize OpenSSL as an alternative
to the TLS/SSL protocol implementation in a JDK.
See also https://netty.io/wiki/requirements-for-4.x.html#tls-with-openssl.

JAVA-4177

Author: stIncMale

.evergreen/.evg.yml

@@ -333,7 +333,7 @@ functions:
         working_dir: "src"
         script: |
           ${PREPARE_SHELL}
-          STREAM_TYPE=netty AUTH="${AUTH}" SSL="${SSL}" MONGODB_URI="${MONGODB_URI}" TOPOLOGY="${TOPOLOGY}" COMPRESSOR="${COMPRESSOR}" JDK="${JDK}" .evergreen/run-tests.sh
+          STREAM_TYPE="netty" AUTH="${AUTH}" SSL="${SSL}" NETTY_SSL_PROVIDER="${NETTY_SSL_PROVIDER}" MONGODB_URI="${MONGODB_URI}" TOPOLOGY="${TOPOLOGY}" COMPRESSOR="${COMPRESSOR}" JDK="${JDK}" .evergreen/run-tests.sh
 
   "run plain auth test":
     - command: shell.exec
@@ -1224,6 +1224,8 @@ tasks:
           name: "plain-auth-test"
         - variant: ".test-scala-variant"
           name: "scala-tests"
+        - variant: ".tests-netty-variant"
+          name: "netty-test"
       commands:
         - func: "publish snapshot"
 
@@ -1350,6 +1352,17 @@ axes:
         display_name: NoSSL
         variables:
            SSL: "nossl"
+  - id: netty-ssl-provider
+    display_name: Netty TLS/SSL protocol provider
+    values:
+      - id: "jdk"
+        display_name: JDK
+        variables:
+          NETTY_SSL_PROVIDER: "JDK"
+      - id: "openssl"
+        display_name: OpenSSL
+        variables:
+          NETTY_SSL_PROVIDER: "OPENSSL"
   - id: compressor
     display_name: Compressor
     values:
@@ -1489,10 +1502,17 @@ buildvariants:
 
 - matrix_name: "tests-netty"
   matrix_spec: { auth: "noauth", ssl: "*", jdk: "jdk8", version: ["4.2", "4.4"], topology: "replicaset", os: "linux" }
-  display_name: "Netty: ${version} ${topology} ${ssl} ${jdk} ${os} "
-  tags: ["tests-variant"]
+  display_name: "Netty: ${version} ${topology} ${ssl} ${auth} ${jdk} ${os} "
+  tags: ["tests-netty-variant"]
   tasks:
-    - name: "test"
+    - name: "netty-test"
+
+- matrix_name: "tests-netty-ssl-provider"
+  matrix_spec: { netty-ssl-provider: "*", auth: "auth", ssl: "ssl", jdk: "jdk8", version: ["5.0"], topology: "replicaset", os: "linux" }
+  display_name: "Netty SSL provider: ${version} ${topology} ${ssl} SslProvider.${netty-ssl-provider} ${auth} ${jdk} ${os} "
+  tags: ["tests-netty-variant"]
+  tasks:
+    - name: "netty-test"
 
 - matrix_name: "tests-socket-snappy-compression"
   matrix_spec: { compressor : "snappy", auth: "noauth", ssl: "nossl", jdk: "jdk8", version: ["4.2"], topology: "standalone", os: "linux" }

.evergreen/run-tests.sh

@@ -6,6 +6,7 @@ set -o errexit  # Exit the script with error if any of the commands fail
 # Supported/used environment variables:
 #       AUTH                        Set to enable authentication. Values are: "auth" / "noauth" (default)
 #       SSL                         Set to enable SSL. Values are "ssl" / "nossl" (default)
+#       NETTY_SSL_PROVIDER          The Netty TLS/SSL protocol provider. Ignored unless SSL is "ssl" and STREAM_TYPE is "netty". Values are "JDK", "OPENSSL", null (a.k.a. "" or '') (default).
 #       MONGODB_URI                 Set the suggested connection MONGODB_URI (including credentials and topology info)
 #       TOPOLOGY                    Allows you to modify variables and the MONGODB_URI based on test topology
 #                                   Supported values: "server", "replica_set", "sharded_cluster"
@@ -36,7 +37,9 @@ SLOW_TESTS_ONLY=${SLOW_TESTS_ONLY:-false}
 export ASYNC_TYPE="-Dorg.mongodb.test.async.type=${STREAM_TYPE}"
 
 export JAVA_HOME="/opt/java/jdk11"
-
+if [ "${SSL}" = "ssl" ] && [ "${STREAM_TYPE}" = "netty" ] && [ "${NETTY_SSL_PROVIDER}" != "" ]; then
+  readonly JAVA_SYSPROP_NETTY_SSL_PROVIDER="-Dorg.mongodb.test.netty.ssl.provider=${NETTY_SSL_PROVIDER}"
+fi
 
 ############################################
 #            Functions                     #
@@ -126,12 +129,16 @@ echo "Running tests with ${JDK}"
 
 if [ "$SLOW_TESTS_ONLY" == "true" ]; then
     ./gradlew -PjdkHome=/opt/java/${JDK} -Dorg.mongodb.test.uri=${MONGODB_URI} \
-              ${TRANSACTION_URI} ${GRADLE_EXTRA_VARS} ${ASYNC_TYPE} --stacktrace --info testSlowOnly
+              ${TRANSACTION_URI} ${GRADLE_EXTRA_VARS} ${ASYNC_TYPE} \
+              ${JAVA_SYSPROP_NETTY_SSL_PROVIDER} \
+              --stacktrace --info testSlowOnly
 else
     ./gradlew -PjdkHome=/opt/java/${JDK} -Dorg.mongodb.test.uri=${MONGODB_URI} \
               -Dorg.mongodb.test.awsAccessKeyId=${AWS_ACCESS_KEY_ID} -Dorg.mongodb.test.awsSecretAccessKey=${AWS_SECRET_ACCESS_KEY} \
               -Dorg.mongodb.test.tmpAwsAccessKeyId=${AWS_TEMP_ACCESS_KEY_ID} -Dorg.mongodb.test.tmpAwsSecretAccessKey=${AWS_TEMP_SECRET_ACCESS_KEY} -Dorg.mongodb.test.tmpAwsSessionToken=${AWS_TEMP_SESSION_TOKEN} \
               -Dorg.mongodb.test.azureTenantId=${AZURE_TENANT_ID} -Dorg.mongodb.test.azureClientId=${AZURE_CLIENT_ID} -Dorg.mongodb.test.azureClientSecret=${AZURE_CLIENT_SECRET} \
               -Dorg.mongodb.test.gcpEmail=${GCP_EMAIL} -Dorg.mongodb.test.gcpPrivateKey=${GCP_PRIVATE_KEY} \
-              ${TRANSACTION_URI} ${API_VERSION} ${GRADLE_EXTRA_VARS} ${ASYNC_TYPE} --stacktrace --info --continue test
+              ${TRANSACTION_URI} ${API_VERSION} ${GRADLE_EXTRA_VARS} ${ASYNC_TYPE} \
+              ${JAVA_SYSPROP_NETTY_SSL_PROVIDER} \
+              --stacktrace --info --continue test
 fi

docs/reference/config.toml

@@ -8,6 +8,7 @@ disableKinds = ["section", "taxonomy", "taxonomyTerm", "404"]
 
 [params]
   javaSeDocsUri = "https://docs.oracle.com/javase/8/docs/"
+  nettyApiUri = "https://netty.io/4.1/api/"
 
 [blackfriday]
   plainIdAnchors = true

docs/reference/content/driver-reactive/tutorials/ssl.md

@@ -10,8 +10,9 @@ title = "TLS/SSL"
 
 ## TLS/SSL
 
-The Java driver supports TLS/SSL connections to MongoDB servers using
-the underlying support for TLS/SSL provided by the JDK. 
+By default the Java 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 utilizing extensibility
+of the [Java SE API]({{< javaseref "api">}}), or via the [Netty API]({{< nettyapiref >}}).
 You can configure the driver to use TLS/SSL either with [`ConnectionString`]({{< apiref "mongodb-driver-core" "com/mongodb/ConnectionString" >}}) or with
 [`MongoClientSettings`]({{< apiref "mongodb-driver-core" "com/mongodb/MongoClientSettings" >}}).
 
@@ -49,25 +50,56 @@ MongoClientSettings settings = MongoClientSettings.builder()
 MongoClient client = MongoClients.create(settings);
 ```
 
-### Specify `SSLContext` via `MongoClientSettings`
+### Specify Java SE `SSLContext` via `MongoClientSettings`
 
 ```java
 import javax.net.ssl.SSLContext;
 import com.mongodb.MongoClientSettings;
-import com.mongodb.reactivestreams.client.MongoClients;
-import com.mongodb.reactivestreams.client.MongoClient;
+import com.mongodb.MongoClient;
 ```
 
-To specify the [`javax.net.ssl.SSLContext`]({{< javaseref "api/javax/net/ssl/SSLContext.html" >}}) with 
+To specify the [`javax.net.ssl.SSLContext`]({{< javaseref "api/javax/net/ssl/SSLContext.html" >}}) with
 [`MongoClientSettings`]({{< apiref "mongodb-driver-core" "com/mongodb/MongoClientSettings" >}}), set the `sslContext` property, as in:
 
 ```java
 SSLContext sslContext = ...
+        MongoClientSettings settings = MongoClientSettings.builder()
+        .applyToSslSettings(builder -> builder.enabled(true).context(sslContext))
+        .build();
+        MongoClient client = new MongoClient(settings);
+```
+
+### Specify Netty `SslContext` via `NettyStreamFactoryFactory`
+
+If you use the driver with [Netty](https://netty.io/) for network IO,
+you have an option to plug an alternative TLS/SSL protocol implementation provided by Netty.
+
+```java
+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`]({{< nettyapiref "io/netty/handler/ssl/SslContext.html" >}}),
+use the method
+[`NettyStreamFactoryFactory.Builder.sslContext`]({{< apiref "mongodb-driver-core" "com/mongodb/connection/netty/NettyStreamFactoryFactory.Builder.html#sslContext(io.netty.handler.ssl.SslContext)" >}}).
+See the documentation of this method for details on which
+[`io.netty.handler.ssl.SslProvider`]({{< nettyapiref "io/netty/handler/ssl/SslProvider.html" >}})s are supported by the driver
+and implications of using them.
+
+```java
+SslContext sslContext = SslContextBuilder.forClient()
+        .sslProvider(SslProvider.OPENSSL)
+        .build();
 MongoClientSettings settings = MongoClientSettings.builder()
-        .applyToSslSettings(builder -> {
-                    builder.enabled(true);
-                    builder.context(sslContext);
-                })
+        .applyToSslSettings(builder -> builder.enabled(true))
+        .streamFactoryFactory(NettyStreamFactoryFactory.builder()
+                .sslContext(sslContext)
+                .build())
         .build();
 MongoClient client = MongoClients.create(settings);
 ```
@@ -91,7 +123,10 @@ MongoClientSettings settings = MongoClientSettings.builder()
 ```
 
 ## Common TLS/SSL Configuration Tasks
-<p></p>
+
+This section is based on the documentation for [Oracle JDK](https://www.oracle.com/java/technologies/javase-downloads.html#JDK8),
+so some parts may be inapplicable to your JDK or to the custom TLS/SSL implementation you use.
+
 ### Configure Trust Store and Key Store
 One may either configure trust stores and key stores specific to the client via 
 [`javax.net.ssl.SSLContext.init(KeyManager[] km, TrustManager[] tm, SecureRandom random)`]
@@ -203,4 +238,4 @@ An application will need to set several JVM system properties to set up OCSP sta
 To configure an application to use OCSP stapling, the application must already be set up to connect to a server using TLS, and the server must be set up to staple an OCSP response to the certificate it returns as part of the the TLS handshake.
 
 For more information on configuring a Java application to use OCSP, please
-refer to the [`Client-Driven OCSP and OCSP Stapling`]({{< javaseref "technotes/guides/security/jsse/ocsp.html" >}}).
+refer to the [`Client-Driven OCSP and OCSP Stapling`]({{< javaseref "technotes/guides/security/jsse/ocsp.html" >}}).

docs/reference/content/driver-scala/tutorials/ssl.md

@@ -10,8 +10,9 @@ title = "TLS/SSL"
 
 ## TLS/SSL
 
-The Java driver supports TLS/SSL connections to MongoDB servers using
-the underlying support for TLS/SSL provided by the JDK. 
+By default the Java 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 utilizing extensibility
+of the [Java SE API]({{< javaseref "api">}}), or via the [Netty API]({{< nettyapiref >}}).
 You can configure the driver to use TLS/SSL either with [`ConnectionString`]({{< apiref "mongo-scala-driver" "org/mongodb/scala/package$$ConnectionString$.html" >}}) or with
 [`MongoClientSettings`]({{< apiref "mongo-scala-driver" "org/mongodb/scala/MongoClientSettings$.html" >}}).
 
@@ -42,7 +43,7 @@ val settings = MongoClientSettings.builder()
 val client = MongoClient(settings)
 ```
 
-### Specify `SSLContext` via `MongoClientSettings`
+### Specify Java SE `SSLContext` via `MongoClientSettings`
 
 ```scala
 import javax.net.ssl.SSLContext
@@ -62,6 +63,36 @@ val settings = MongoClientSettings.builder()
 val client = MongoClient(settings)
 ```
 
+### Specify Netty `SslContext` via `NettyStreamFactoryFactory`
+
+If you use the driver with [Netty](https://netty.io/) for network IO,
+you have an option to plug an alternative TLS/SSL protocol implementation provided by Netty.
+
+```java
+import io.netty.handler.ssl.SslContextBuilder;
+import io.netty.handler.ssl.SslProvider;
+```
+
+To instruct the driver to use [`io.netty.handler.ssl.SslContext`]({{< nettyapiref "io/netty/handler/ssl/SslContext.html" >}}),
+use the method
+[`NettyStreamFactoryFactory.Builder.sslContext`]({{< apiref "mongodb-driver-core" "com/mongodb/connection/netty/NettyStreamFactoryFactory.Builder.html#sslContext(io.netty.handler.ssl.SslContext)" >}}).
+See the documentation of this method for details on which
+[`io.netty.handler.ssl.SslProvider`]({{< nettyapiref "io/netty/handler/ssl/SslProvider.html" >}})s are supported by the driver
+and implications of using them.
+
+```scala
+val sslContext = SslContextBuilder.forClient()
+    .sslProvider(SslProvider.OPENSSL)
+    .build();
+val settings = MongoClientSettings.builder()
+    .applyToSslSettings((builder: SslSettings.Builder) => builder.enabled(true))
+    .streamFactoryFactory(NettyStreamFactoryFactory.builder()
+        .sslContext(sslContext)
+        .build())
+    .build()
+val client = MongoClient(settings)
+```
+
 ## Disable Hostname Verification
 
 By default, the driver ensures that the hostname included in the
@@ -81,7 +112,10 @@ val settings = MongoClientSettings.builder()
 ```
 
 ## Common TLS/SSL Configuration Tasks
-<p></p>
+
+This section is based on the documentation for [Oracle JDK](https://www.oracle.com/java/technologies/javase-downloads.html#JDK8),
+so some parts may be inapplicable to your JDK or to the custom TLS/SSL implementation you use.
+
 ### Configure Trust Store and Key Store
 One may either configure trust stores and key stores specific to the client via 
 [`javax.net.ssl.SSLContext.init(KeyManager[] km, TrustManager[] tm, SecureRandom random)`]