You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Common TLS/SSL Configuration Tasks <!-- Care when renaming, this section is referred to in driver-reactive/tutorials/ssl.md and driver-scala/tutorials/ssl.md -->
command line program provided as part of the JDK. For example:
173
-
174
-
```bash
175
-
keytool -importcert -trustcacerts -file <path to certificate authority file>
176
-
-keystore <path to trust store> -storepass <trust store password>
177
-
```
178
-
179
-
#### Set the Default Key Store
180
-
181
-
A typical application will also need to set several JVM system
182
-
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
183
-
MongoDB server:
184
-
185
-
-`javax.net.ssl.keyStore`
186
-
The path to a key store containing the client's TLS/SSL certificates
-out <path to key store> -passout pass:<trust store password>
204
-
```
205
-
206
-
For more information on configuring a Java application for TLS/SSL, please
207
-
refer to the [`JSSE Reference Guide`]({{< javaseref "technotes/guides/security/jsse/JSSERefGuide.html" >}}).
208
-
209
-
210
-
### Forcing TLS 1.2
211
-
212
-
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".
213
-
214
-
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.
215
-
216
-
217
-
### OCSP
218
-
219
-
{{% note %}}
220
-
The Java driver cannot enable OCSP by default on a per MongoClient basis.
221
-
{{% /note %}}
222
-
223
-
#### Client-driven OCSP
224
-
225
-
An application will need to set JVM system and security properties to ensure that client-driven OCSP is enabled:
226
-
227
-
-`com.sun.net.ssl.checkRevocation`:
228
-
When set to `true`, this system property enables revocation checking.
229
-
230
-
-`ocsp.enable`:
231
-
When set to `true`, this security property enables client-driven OCSP.
232
-
233
-
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.
234
-
235
-
{{% note %}}
236
-
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.
237
-
{{% /note %}}
238
-
239
-
#### OCSP Stapling
240
-
241
-
{{% note class="important" %}}
242
-
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):
243
-
244
-
`javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request`
245
-
246
-
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".
247
-
{{% /note %}}
248
-
249
-
An application will need to set several JVM system properties to set up OCSP stapling:
250
-
251
-
-`jdk.tls.client.enableStatusRequestExtension`:
252
-
When set to `true` (its default value), this enables OCSP stapling.
253
-
254
-
-`com.sun.net.ssl.checkRevocation`:
255
-
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.
256
-
257
-
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.
258
-
259
-
For more information on configuring a Java application to use OCSP, please
260
-
refer to the [`Client-Driven OCSP and OCSP Stapling`]({{< javaseref "technotes/guides/security/jsse/ocsp.html" >}}).
command line program provided as part of the JDK. For example:
26
+
27
+
```bash
28
+
keytool -importcert -trustcacerts -file <path to certificate authority file>
29
+
-keystore <path to trust store> -storepass <trust store password>
30
+
```
31
+
32
+
#### Set the Default Key Store
33
+
34
+
A typical application will also need to set several JVM system
35
+
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
36
+
MongoDB server:
37
+
38
+
-`javax.net.ssl.keyStore`
39
+
The path to a key store containing the client's TLS/SSL certificates
-out <path to key store> -passout pass:<trust store password>
57
+
```
58
+
59
+
For more information on configuring a Java application for TLS/SSL, please
60
+
refer to the [`JSSE Reference Guide`]({{< javaseref "technotes/guides/security/jsse/JSSERefGuide.html" >}}).
61
+
62
+
63
+
### Forcing TLS 1.2
64
+
65
+
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".
66
+
67
+
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.
68
+
69
+
70
+
### OCSP
71
+
72
+
{{% note %}}
73
+
The Java driver cannot enable OCSP by default on a per MongoClient basis.
74
+
{{% /note %}}
75
+
76
+
#### Client-driven OCSP
77
+
78
+
An application will need to set JVM system and security properties to ensure that client-driven OCSP is enabled:
79
+
80
+
-`com.sun.net.ssl.checkRevocation`:
81
+
When set to `true`, this system property enables revocation checking.
82
+
83
+
-`ocsp.enable`:
84
+
When set to `true`, this security property enables client-driven OCSP.
85
+
86
+
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.
87
+
88
+
{{% note %}}
89
+
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.
90
+
{{% /note %}}
91
+
92
+
#### OCSP Stapling
93
+
94
+
{{% note class="important" %}}
95
+
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):
96
+
97
+
`javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request`
98
+
99
+
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".
100
+
{{% /note %}}
101
+
102
+
An application will need to set several JVM system properties to set up OCSP stapling:
103
+
104
+
-`jdk.tls.client.enableStatusRequestExtension`:
105
+
When set to `true` (its default value), this enables OCSP stapling.
106
+
107
+
-`com.sun.net.ssl.checkRevocation`:
108
+
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.
109
+
110
+
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.
111
+
112
+
For more information on configuring a Java application to use OCSP, please
113
+
refer to the [`Client-Driven OCSP and OCSP Stapling`]({{< javaseref "technotes/guides/security/jsse/ocsp.html" >}}).
0 commit comments