diff --git a/docs/reference/config.toml b/docs/reference/config.toml index 7b75c1fd815..0a33cee2461 100644 --- a/docs/reference/config.toml +++ b/docs/reference/config.toml @@ -6,6 +6,9 @@ canonifyURLs = false disableHugoGeneratorInject = true disableKinds = ["section", "taxonomy", "taxonomyTerm", "404"] +[params] + javaSeDocsUri = "https://docs.oracle.com/javase/8/docs/" + [blackfriday] plainIdAnchors = true diff --git a/docs/reference/content/driver-reactive/reference/monitoring.md b/docs/reference/content/driver-reactive/reference/monitoring.md index b76fb1f660f..2474b39846a 100644 --- a/docs/reference/content/driver-reactive/reference/monitoring.md +++ b/docs/reference/content/driver-reactive/reference/monitoring.md @@ -10,7 +10,7 @@ title = "Monitoring" # JMX Monitoring -The driver uses [JMX](http://docs.oracle.com/javase/8/docs/technotes/guides/jmx/) to create +The driver uses [JMX]({{< javaseref "technotes/guides/jmx/" >}}) to create [MXBeans](http://docs.oracle.com/javase/tutorial/jmx/mbeans/mxbeans.html) that allow an application or end user to monitor various aspects of the driver. diff --git a/docs/reference/content/driver-reactive/tutorials/aggregation.md b/docs/reference/content/driver-reactive/tutorials/aggregation.md index 396cbc2a382..c1708cbc059 100644 --- a/docs/reference/content/driver-reactive/tutorials/aggregation.md +++ b/docs/reference/content/driver-reactive/tutorials/aggregation.md @@ -97,8 +97,8 @@ collection.aggregate( ### Explain an Aggregation To [explain]({{< docsref "reference/command/explain/" >}}) an aggregation pipeline, call the -[`AggregatePublisher.explain()`]({{< apiref "mongodb-driver-reactivestreams" "com/mongodb/reactivestreams/client/AggregatePublisher.html#explain()" -> >}}) +[`AggregatePublisher.explain()`] +({{< apiref "mongodb-driver-reactivestreams" "com/mongodb/reactivestreams/client/AggregatePublisher.html#explain()" >}}) method: ```java @@ -110,4 +110,4 @@ collection.aggregate( .subscribe(new PrintDocumentSubscriber()); ``` -The driver supports explain of aggregation pipelines starting with MongoDB 3.6. +The driver supports explain of aggregation pipelines starting with MongoDB 3.6. \ No newline at end of file diff --git a/docs/reference/content/driver-reactive/tutorials/ssl.md b/docs/reference/content/driver-reactive/tutorials/ssl.md index 7020ea1b7f1..2d2712680b8 100644 --- a/docs/reference/content/driver-reactive/tutorials/ssl.md +++ b/docs/reference/content/driver-reactive/tutorials/ssl.md @@ -58,7 +58,7 @@ import com.mongodb.reactivestreams.client.MongoClients; import com.mongodb.reactivestreams.client.MongoClient; ``` -To specify the [`javax.net.ssl.SSLContext`](https://docs.oracle.com/javase/8/docs/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 @@ -79,7 +79,7 @@ server's SSL certificate(s) matches the hostname(s) provided when constructing a [`MongoClient()`]({{< apiref "mongodb-driver-reactivestreams" "com/mongodb/reactivestreams/client/MongoClient.html" >}}). If your application needs to disable hostname verification, you must explicitly indicate -this in `MongoClientSettings`]({{< apiref "mongodb-driver-core" "com/mongodb/MongoClientSettings" >}}) +this in [`MongoClientSettings`]({{< apiref "mongodb-driver-core" "com/mongodb/MongoClientSettings" >}}) ```java MongoClientSettings settings = MongoClientSettings.builder() @@ -90,42 +90,117 @@ MongoClientSettings settings = MongoClientSettings.builder() .build(); ``` -## JVM System Properties for TLS/SSL +## Common TLS/SSL Configuration Tasks +

+### 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)`] +({{< javaseref "api/javax/net/ssl/SSLContext.html#init-javax.net.ssl.KeyManager:A-javax.net.ssl.TrustManager:A-java.security.SecureRandom-" >}}), +or set the JVM default ones. + +#### Set the Default Trust Store A typical application will need to set several JVM system properties to -ensure that the client is able to validate the TLS/SSL certificate +ensure that the client is able to *validate* the TLS/SSL certificate presented by the server: - `javax.net.ssl.trustStore`: - The path to a trust store containing the certificate of the - signing authority + The path to a trust store containing the certificate of the + signing authority + (see `` below) - `javax.net.ssl.trustStorePassword`: - The password to access this trust store + The password to access this trust store + (see `` below) The trust store is typically created with the -[`keytool`](http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) +[`keytool`]({{< javaseref "technotes/tools/unix/keytool.html" >}}) command line program provided as part of the JDK. For example: ```bash keytool -importcert -trustcacerts -file - -keystore -storepass + -keystore -storepass ``` + +#### Set the Default Key Store + A typical application will also need to set several JVM system -properties to ensure that the client presents an TLS/SSL certificate to the +properties to ensure that the client *presents* an TLS/SSL [client certificate](https://docs.mongodb.com/manual/tutorial/configure-ssl/#set-up-mongod-and-mongos-with-client-certificate-validation) to the MongoDB server: - `javax.net.ssl.keyStore` - The path to a key store containing the client's TLS/SSL certificates + The path to a key store containing the client's TLS/SSL certificates + (see `` below) - `javax.net.ssl.keyStorePassword` - The password to access this key store + The password to access this key store + (see `` below) The key store is typically created with the -[`keytool`](http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) +[`keytool`]({{< javaseref "technotes/tools/unix/keytool.html" >}}) or the [`openssl`](https://www.openssl.org/docs/apps/openssl.html) -command line program. +command line program. For example, if you have a file with the client certificate and its private key +(may be in the PEM format) +and want to create a key store in the [PKCS #12](https://www.rfc-editor.org/rfc/rfc7292) format, +you can do the following: + +```sh +openssl pkcs12 -export -in + -out -passout pass: +``` For more information on configuring a Java application for TLS/SSL, please -refer to the [`JSSE Reference Guide`](http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSS -ERefGuide.html). +refer to the [`JSSE Reference Guide`]({{< javaseref "technotes/guides/security/jsse/JSSERefGuide.html" >}}). + + +### Forcing TLS 1.2 + +Some applications may want to force only the TLS 1.2 protocol. To do this, set the `jdk.tls.client.protocols` system property to "TLSv1.2". + +Java runtime environments prior to Java 8 started to enable the TLS 1.2 protocol only in later updates, as shown in the previous section. For the driver to force the use of the TLS 1.2 protocol with a Java runtime environment prior to Java 8, ensure that the update has TLS 1.2 enabled. + + +### OCSP + +{{% note %}} +The Java driver cannot enable OCSP by default on a per MongoClient basis. +{{% /note %}} + +#### Client-driven OCSP + +An application will need to set JVM system and security properties to ensure that client-driven OCSP is enabled: + +- `com.sun.net.ssl.checkRevocation`: + When set to `true`, this system property enables revocation checking. + +- `ocsp.enable`: + When set to `true`, this security property enables client-driven OCSP. + +To configure an application to use client-driven OCSP, the application must already be set up to connect to a server using TLS. Setting these system properties is required to enable client-driven OCSP. + +{{% note %}} +The support for TLS provided by the JDK utilizes “hard fail” behavior in the case of an unavailable OCSP responder in contrast to the mongo shell and drivers that utilize “soft fail” behavior. +{{% /note %}} + +#### OCSP Stapling + +{{% note class="important" %}} +The following exception may occur when using OCSP stapling with Java runtime environments that use the TLS 1.3 protocol (Java 11 and higher use TLS 1.3 by default): + +`javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request` + +The exception is due to a known issue with TLS 1.3 in Java 11 and higher. To avoid this exception when using a Java runtime environments using the TLS 1.3 protocol, you can force the application to use the TLS 1.2 protocol. To do this, set the `jdk.tls.client.protocols` system property to "TLSv1.2". +{{% /note %}} + +An application will need to set several JVM system properties to set up OCSP stapling: + +- `jdk.tls.client.enableStatusRequestExtension`: + When set to `true` (its default value), this enables OCSP stapling. + +- `com.sun.net.ssl.checkRevocation`: + When set to `true`, this enables revocation checking. If this property is not set to `true`, then the connection will be allowed to proceed regardless of the presence or status of the revocation information. + +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" >}}). \ No newline at end of file diff --git a/docs/reference/content/driver-scala/reference/monitoring.md b/docs/reference/content/driver-scala/reference/monitoring.md index cbfc4457044..fc00b73baa1 100644 --- a/docs/reference/content/driver-scala/reference/monitoring.md +++ b/docs/reference/content/driver-scala/reference/monitoring.md @@ -10,7 +10,7 @@ title = "Monitoring" # JMX Monitoring -The driver uses [JMX](http://docs.oracle.com/javase/8/docs/technotes/guides/jmx/) to create +The driver uses [JMX]({{< javaseref "technotes/guides/jmx/" >}}) to create [MXBeans](http://docs.oracle.com/javase/tutorial/jmx/mbeans/mxbeans.html) that allow an application or end user to monitor various aspects of the driver. diff --git a/docs/reference/content/driver-scala/tutorials/ssl.md b/docs/reference/content/driver-scala/tutorials/ssl.md index 0bacbbd4d99..0cc19fede31 100644 --- a/docs/reference/content/driver-scala/tutorials/ssl.md +++ b/docs/reference/content/driver-scala/tutorials/ssl.md @@ -48,7 +48,7 @@ val client = MongoClients.create(settings) import javax.net.ssl.SSLContext ``` -To specify the [`javax.net.ssl.SSLContext`](https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html) with +To specify the [`javax.net.ssl.SSLContext`]({{< javaseref "api/javax/net/ssl/SSLContext.html" >}}) with [`MongoClientSettings`]({{< apiref "mongo-scala-driver" "org/mongodb/scala/MongoClientSettings$.html" >}}), set the `sslContext` property, as in: ```scala @@ -69,7 +69,7 @@ server's SSL certificate(s) matches the hostname(s) provided when constructing a [`MongoClient()`]({{< apiref "mongo-scala-driver" "org/mongodb/scala/MongoClient$.html" >}}). If your application needs to disable hostname verification, you must explicitly indicate -this in `MongoClientSettings`]({{< apiref "mongo-scala-driver" "org/mongodb/scala/MongoClientSettings$.html" >}}) +this in [`MongoClientSettings`]({{< apiref "mongo-scala-driver" "org/mongodb/scala/MongoClientSettings$.html" >}}) ```scala val settings = MongoClientSettings.builder() @@ -80,42 +80,117 @@ val settings = MongoClientSettings.builder() .build() ``` -## JVM System Properties for TLS/SSL +## Common TLS/SSL Configuration Tasks +

+### 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)`] +({{< javaseref "api/javax/net/ssl/SSLContext.html#init-javax.net.ssl.KeyManager:A-javax.net.ssl.TrustManager:A-java.security.SecureRandom-" >}}), +or set the JVM default ones. + +#### Set the Default Trust Store A typical application will need to set several JVM system properties to -ensure that the client is able to validate the TLS/SSL certificate +ensure that the client is able to *validate* the TLS/SSL certificate presented by the server: - `javax.net.ssl.trustStore`: - The path to a trust store containing the certificate of the - signing authority + The path to a trust store containing the certificate of the + signing authority + (see `` below) - `javax.net.ssl.trustStorePassword`: - The password to access this trust store + The password to access this trust store + (see `` below) The trust store is typically created with the -[`keytool`](http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) +[`keytool`]({{< javaseref "technotes/tools/unix/keytool.html" >}}) command line program provided as part of the JDK. For example: ```bash keytool -importcert -trustcacerts -file - -keystore -storepass + -keystore -storepass ``` + +#### Set the Default Key Store + A typical application will also need to set several JVM system -properties to ensure that the client presents an TLS/SSL certificate to the +properties to ensure that the client *presents* an TLS/SSL [client certificate](https://docs.mongodb.com/manual/tutorial/configure-ssl/#set-up-mongod-and-mongos-with-client-certificate-validation) to the MongoDB server: - `javax.net.ssl.keyStore` - The path to a key store containing the client's TLS/SSL certificates + The path to a key store containing the client's TLS/SSL certificates + (see `` below) - `javax.net.ssl.keyStorePassword` - The password to access this key store + The password to access this key store + (see `` below) The key store is typically created with the -[`keytool`](http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) +[`keytool`]({{< javaseref "technotes/tools/unix/keytool.html" >}}) or the [`openssl`](https://www.openssl.org/docs/apps/openssl.html) -command line program. +command line program. For example, if you have a file with the client certificate and its private key +(may be in the PEM format) +and want to create a key store in the [PKCS #12](https://www.rfc-editor.org/rfc/rfc7292) format, +you can do the following: + +```sh +openssl pkcs12 -export -in + -out -passout pass: +``` For more information on configuring a Java application for TLS/SSL, please -refer to the [`JSSE Reference Guide`](http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSS -ERefGuide.html). +refer to the [`JSSE Reference Guide`]({{< javaseref "technotes/guides/security/jsse/JSSERefGuide.html" >}}). + + +### Forcing TLS 1.2 + +Some applications may want to force only the TLS 1.2 protocol. To do this, set the `jdk.tls.client.protocols` system property to "TLSv1.2". + +Java runtime environments prior to Java 8 started to enable the TLS 1.2 protocol only in later updates, as shown in the previous section. For the driver to force the use of the TLS 1.2 protocol with a Java runtime environment prior to Java 8, ensure that the update has TLS 1.2 enabled. + + +### OCSP + +{{% note %}} +The Java driver cannot enable OCSP by default on a per MongoClient basis. +{{% /note %}} + +#### Client-driven OCSP + +An application will need to set JVM system and security properties to ensure that client-driven OCSP is enabled: + +- `com.sun.net.ssl.checkRevocation`: + When set to `true`, this system property enables revocation checking. + +- `ocsp.enable`: + When set to `true`, this security property enables client-driven OCSP. + +To configure an application to use client-driven OCSP, the application must already be set up to connect to a server using TLS. Setting these system properties is required to enable client-driven OCSP. + +{{% note %}} +The support for TLS provided by the JDK utilizes “hard fail” behavior in the case of an unavailable OCSP responder in contrast to the mongo shell and drivers that utilize “soft fail” behavior. +{{% /note %}} + +#### OCSP Stapling + +{{% note class="important" %}} +The following exception may occur when using OCSP stapling with Java runtime environments that use the TLS 1.3 protocol (Java 11 and higher use TLS 1.3 by default): + +`javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request` + +The exception is due to a known issue with TLS 1.3 in Java 11 and higher. To avoid this exception when using a Java runtime environments using the TLS 1.3 protocol, you can force the application to use the TLS 1.2 protocol. To do this, set the `jdk.tls.client.protocols` system property to "TLSv1.2". +{{% /note %}} + +An application will need to set several JVM system properties to set up OCSP stapling: + +- `jdk.tls.client.enableStatusRequestExtension`: + When set to `true` (its default value), this enables OCSP stapling. + +- `com.sun.net.ssl.checkRevocation`: + When set to `true`, this enables revocation checking. If this property is not set to `true`, then the connection will be allowed to proceed regardless of the presence or status of the revocation information. + +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" >}}). \ No newline at end of file diff --git a/docs/reference/content/driver/reference/monitoring.md b/docs/reference/content/driver/reference/monitoring.md index 4a6db9e6d72..378bd91bacb 100644 --- a/docs/reference/content/driver/reference/monitoring.md +++ b/docs/reference/content/driver/reference/monitoring.md @@ -10,7 +10,7 @@ title = "Monitoring" # JMX Monitoring -The driver uses [JMX](http://docs.oracle.com/javase/8/docs/technotes/guides/jmx/) to create +The driver uses [JMX]({{< javaseref "technotes/guides/jmx/" >}}) to create [MXBeans](http://docs.oracle.com/javase/tutorial/jmx/mbeans/mxbeans.html) that allow an application or end user to monitor various aspects of the driver. diff --git a/docs/reference/content/driver/tutorials/gridfs.md b/docs/reference/content/driver/tutorials/gridfs.md index 03e34e3282a..989a4debce1 100644 --- a/docs/reference/content/driver/tutorials/gridfs.md +++ b/docs/reference/content/driver/tutorials/gridfs.md @@ -79,7 +79,7 @@ To upload data into GridFS, you can upload from an `InputStream` or write data t ### UploadFromStream -The [`GridFSBucket.uploadFromStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSBucket.html#openUploadStream(java.lang.String,com.mongodb.client.gridfs.model.GridFSUploadOptions)" >}}) method reads the contents of an [`InputStream`](http://docs.oracle.com/javase/8/docs/api/index.html?java/io/InputStream.html) and saves it to the `GridFSBucket`. +The [`GridFSBucket.uploadFromStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSBucket.html#openUploadStream(java.lang.String,com.mongodb.client.gridfs.model.GridFSUploadOptions)" >}}) method reads the contents of an [`InputStream`]({{< javaseref "api/java/io/InputStream.html" >}}) and saves it to the `GridFSBucket`. You can use the [`GridFSUploadOptions`]({{< apiref "mongodb-driver-core" "com/mongodb/client/gridfs/model/GridFSUploadOptions" >}}) to configure the chunk size or include additional metadata. @@ -104,7 +104,7 @@ try { ### OpenUploadStream You can write data to a [`GridFSUploadStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSUploadStream.html" >}}) which extends - [`OutputStream`](http://docs.oracle.com/javase/8/docs/api/index.html?java/io/OutputStream.html). The + [`OutputStream`]({{< javaseref "api/java/io/OutputStream.html" >}}). The [`GridFSBucket.openUploadStream `]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSBucket.html#openUploadStream(java.lang.String,com.mongodb.client.gridfs.model.GridFSUploadOptions)" >}}) method returns a [`GridFSUploadStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSUploadStream.html" >}}). @@ -154,7 +154,7 @@ There are various ways to download data from GridFS. ### DownloadToStream -The [`downloadToStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSBucket.html#downloadToStream(org.bson.types.ObjectId,java.io.OutputStream)" >}}) method reads the contents from MongoDB and writes the data directly to the provided [`OutputStream`](http://docs.oracle.com/javase/8/docs/api/index.html?java/io/OutputStream.html). +The [`downloadToStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSBucket.html#downloadToStream(org.bson.types.ObjectId,java.io.OutputStream)" >}}) method reads the contents from MongoDB and writes the data directly to the provided [`OutputStream`]({{< javaseref "api/java/io/OutputStream.html" >}}). To download a file by its file `_id`, pass the `_id` to the method. The following example downloads a file by its file `_id` into the provided @@ -193,7 +193,7 @@ try { ### OpenDownloadStream -The [`openDownloadStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSBucket.html#openDownloadStream(org.bson.types.ObjectId)" >}}) method returns a [`GridFSDownloadStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSDownloadStream.html" >}}) which extends [`InputStream`](http://docs.oracle.com/javase/8/docs/api/index.html?java/io/InputStream.html). +The [`openDownloadStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSBucket.html#openDownloadStream(org.bson.types.ObjectId)" >}}) method returns a [`GridFSDownloadStream`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/gridfs/GridFSDownloadStream.html" >}}) which extends [`InputStream`]({{< javaseref "api/java/io/InputStream.html" >}}). The following example reads from the `GridFSBucket` via the returned `InputStream`: diff --git a/docs/reference/content/driver/tutorials/jndi.md b/docs/reference/content/driver/tutorials/jndi.md index 8a6e9245483..c973382a6c8 100644 --- a/docs/reference/content/driver/tutorials/jndi.md +++ b/docs/reference/content/driver/tutorials/jndi.md @@ -10,7 +10,7 @@ title = "JNDI" ## Java Naming and Directory Interface (JNDI) -The driver includes a [JNDI](http://docs.oracle.com/javase/8/docs/technotes/guides/jndi/index.html) ObjectFactory implementation, +The driver includes a [JNDI]({{< javaseref "technotes/guides/jndi/index.html" >}}) ObjectFactory implementation, [`MongoClientFactory`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/MongoClientFactory" >}}) ([`legacy version`]({{< apiref "mongodb-driver-legacy" "com/mongodb/client/jndi/MongoClientFactory" >}})), that returns `MongoClient` instances based on a [connection string](http://docs.mongodb.org/manual/reference/connection-string/). diff --git a/docs/reference/content/driver/tutorials/ssl.md b/docs/reference/content/driver/tutorials/ssl.md index 8b427e7efce..743b7f059ca 100644 --- a/docs/reference/content/driver/tutorials/ssl.md +++ b/docs/reference/content/driver/tutorials/ssl.md @@ -59,7 +59,7 @@ import com.mongodb.client.MongoClients; import com.mongodb.client.MongoClient; ``` -To specify the [`javax.net.ssl.SSLContext`](https://docs.oracle.com/javase/8/docs/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 @@ -112,7 +112,7 @@ import com.mongodb.MongoClientSettings; import com.mongodb.MongoClient; ``` -To specify the [`javax.net.ssl.SSLContext`](https://docs.oracle.com/javase/8/docs/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 @@ -130,7 +130,7 @@ server's SSL certificate(s) matches the hostname(s) provided when constructing a [`MongoClient()`]({{< apiref "mongodb-driver-sync" "com/mongodb/client/MongoClient.html" >}}). If your application needs to disable hostname verification, you must explicitly indicate -this in `MongoClientSettings`]({{< apiref "mongodb-driver-core" "com/mongodb/MongoClientSettings" >}}) +this in [`MongoClientSettings`]({{< apiref "mongodb-driver-core" "com/mongodb/MongoClientSettings" >}}) ```java MongoClientSettings settings = MongoClientSettings.builder() @@ -141,45 +141,67 @@ MongoClientSettings settings = MongoClientSettings.builder() .build(); ``` -## JVM System Properties for TLS/SSL +## Common TLS/SSL Configuration Tasks +

+### 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)`] +({{< javaseref "api/javax/net/ssl/SSLContext.html#init-javax.net.ssl.KeyManager:A-javax.net.ssl.TrustManager:A-java.security.SecureRandom-" >}}), +or set the JVM default ones. + +#### Set the Default Trust Store A typical application will need to set several JVM system properties to -ensure that the client is able to validate the TLS/SSL certificate +ensure that the client is able to *validate* the TLS/SSL certificate presented by the server: - `javax.net.ssl.trustStore`: The path to a trust store containing the certificate of the signing authority + (see `` below) - `javax.net.ssl.trustStorePassword`: The password to access this trust store + (see `` below) The trust store is typically created with the -[`keytool`](http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) +[`keytool`]({{< javaseref "technotes/tools/unix/keytool.html" >}}) command line program provided as part of the JDK. For example: ```bash keytool -importcert -trustcacerts -file - -keystore -storepass + -keystore -storepass ``` + +#### Set the Default Key Store + A typical application will also need to set several JVM system -properties to ensure that the client presents an TLS/SSL certificate to the +properties to ensure that the client *presents* an TLS/SSL [client certificate](https://docs.mongodb.com/manual/tutorial/configure-ssl/#set-up-mongod-and-mongos-with-client-certificate-validation) to the MongoDB server: - `javax.net.ssl.keyStore` The path to a key store containing the client's TLS/SSL certificates + (see `` below) - `javax.net.ssl.keyStorePassword` The password to access this key store + (see `` below) The key store is typically created with the -[`keytool`](http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) +[`keytool`]({{< javaseref "technotes/tools/unix/keytool.html" >}}) or the [`openssl`](https://www.openssl.org/docs/apps/openssl.html) -command line program. +command line program. For example, if you have a file with the client certificate and its private key +(may be in the PEM format) +and want to create a key store in the [PKCS #12](https://www.rfc-editor.org/rfc/rfc7292) format, +you can do the following: + +```sh +openssl pkcs12 -export -in + -out -passout pass: +``` For more information on configuring a Java application for TLS/SSL, please -refer to the [`JSSE Reference Guide`](http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSS -ERefGuide.html). +refer to the [`JSSE Reference Guide`]({{< javaseref "technotes/guides/security/jsse/JSSERefGuide.html" >}}). ### Forcing TLS 1.2 @@ -189,13 +211,13 @@ Some applications may want to force only the TLS 1.2 protocol. To do this, set t Java runtime environments prior to Java 8 started to enable the TLS 1.2 protocol only in later updates, as shown in the previous section. For the driver to force the use of the TLS 1.2 protocol with a Java runtime environment prior to Java 8, ensure that the update has TLS 1.2 enabled. -## OCSP +### OCSP {{% note %}} The Java driver cannot enable OCSP by default on a per MongoClient basis. {{% /note %}} -### Client-driven OCSP +#### Client-driven OCSP An application will need to set JVM system and security properties to ensure that client-driven OCSP is enabled: @@ -211,7 +233,7 @@ To configure an application to use client-driven OCSP, the application must alre The support for TLS provided by the JDK utilizes “hard fail” behavior in the case of an unavailable OCSP responder in contrast to the mongo shell and drivers that utilize “soft fail” behavior. {{% /note %}} -### OCSP Stapling +#### OCSP Stapling {{% note class="important" %}} The following exception may occur when using OCSP stapling with Java runtime environments that use the TLS 1.3 protocol (Java 11 and higher use TLS 1.3 by default): @@ -232,4 +254,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" section in the [`JSSE Reference Guide`](https://docs.oracle.com/javase/9/security/java-secure-socket-extension-jsse-reference-guide.htm). +refer to the [`Client-Driven OCSP and OCSP Stapling`]({{< javaseref "technotes/guides/security/jsse/ocsp.html" >}}). \ No newline at end of file diff --git a/docs/reference/layouts/shortcodes/javaseref.html b/docs/reference/layouts/shortcodes/javaseref.html new file mode 100644 index 00000000000..0a16b75d89f --- /dev/null +++ b/docs/reference/layouts/shortcodes/javaseref.html @@ -0,0 +1 @@ +{{ .Site.Params.javaSeDocsUri }}{{ .Get 0 }}