0% found this document useful (0 votes)

47 views

mongo-Java-Driver/4.1/../) : Driver/blob/master/docs/reference/content/driver/tutorials/ssl - MD

The document discusses how to configure TLS/SSL encryption for connections between the Java driver and MongoDB servers. It provides examples of specifying TLS/SSL settings using ConnectionString, MongoClientSettings, MongoClientURI, and MongoClientOptions. It also covers disabling hostname verification, configuring truststores and keystores, forcing TLS 1.2, enabling client-driven OCSP, and issues with OCSP stapling in TLS 1.3.

Uploaded by

AMIMUL EHSAN

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

47 views

mongo-Java-Driver/4.1/../) : Driver/blob/master/docs/reference/content/driver/tutorials/ssl - MD

Uploaded by

AMIMUL EHSAN

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 6

 (/mongo-java-driver/4.1/..

/) Search docs 

 (https://github.com/mongodb/mongo-java-
driver/blob/master/docs/reference/content/driver/tutorials/ssl.md)
Java Driver (/mongo-java-driver/4.1/driver/) Tutorials (/mongo-java-driver/4.1/driver/tutorials/) Connect to MongoDB (/mongo-
java-driver/4.1/driver/tutorials/connect-to-mongodb/) 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. You can configure the driver to use TLS/SSL either with
ConnectionString (/mongo-java-driver/4.1/apidocs/mongodb-driver-
core/com/mongodb/ConnectionString.html ) or with MongoClientSettings (/mongo-java-
driver/4.1/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html ). With the legacy
MongoClient API you can use either MongoClientURI (/mongo-java-driver/4.1/apidocs/mongodb-driver-
core/com/mongodb/MongoClientURI.html ) or MongoClientOptions (/mongo-java-
driver/4.1/apidocs/mongodb-driver-core/com/mongodb/MongoClientOptions.html ).

MongoClient API (since 3.7)

Specify TLS/SSL via ConnectionString

com.mongodb.client.MongoClients;
com.mongodb.client.MongoClient;

To specify TLS/SSL with ConnectionString (/mongo-java-driver/4.1/apidocs/mongodb-driver-

core/com/mongodb/ConnectionString.html ), specify ssl=true as part of the connection string, as in:

MongoClient mongoClient = MongoClients.create("mongodb://localhost/?ssl=true");

Specify TLS/SSL via MongoClientSettings

import com.mongodb.MongoClientSettings;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;
To specify TLS/SSL with with MongoClientSettings (/mongo-java-driver/4.1/apidocs/mongodb-driver-
 (/mongo-java-driver/4.1/../)
core/com/mongodb/MongoClientSettings.html ), set the enabled property to
Search docs
true , as in:


MongoClientSettings settings = MongoClientSettings.builder()

.applyToSslSettings(builder ->
builder.enabled(true))
.build();
MongoClient client = MongoClients.create(settings);

Specify SSLContext via MongoClientSettings

import javax.net.ssl.SSLContext;
import com.mongodb.MongoClientSettings;
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 MongoClientSettings
(/mongo-java-driver/4.1/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html ), set the
sslContext property, as in:

SSLContext sslContext = ...

MongoClientSettings settings = MongoClientSettings.builder()
.applyToSslSettings(builder -> {
builder.enabled(true);
builder.context(sslContext);
})
.build();
MongoClient client = MongoClients.create(settings);

Legacy MongoClient API

Specify TLS/SSL via MongoClientURI

import com.mongodb.MongoClientURI;
import com.mongodb.MongoClient;

To specify TLS/SSL with MongoClientURI (/mongo-java-driver/4.1/apidocs/mongodb-driver-

core/com/mongodb/MongoClientURI.html ), specify ssl=true as part of the connection string, as in:
 MongoClientURI (/mongo-java-driver/4.1/../)
uri = new MongoClientURI("mongodb://localhost/?ssl=true"); Search docs 
MongoClient mongoClient = new MongoClient(uri);

Specify TLS/SSL via MongoClientOptions

import com.mongodb.MongoClientOptions;
import com.mongodb.MongoClient;

To specify TLS/SSL with with MongoClientOptions (/mongo-java-driver/4.1/apidocs/mongodb-driver-

core/com/mongodb/MongoClientOptions.html ), set the sslEnabled property to true , as in:

MongoClientOptions options = MongoClientOptions.builder()

.sslEnabled(true)
.build();
MongoClient client = new MongoClient("localhost", options);

Specify SSLContext via MongoClientOptions

import javax.net.ssl.SSLContext;
import com.mongodb.MongoClientOptions;
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 MongoClientOptions
(/mongo-java-driver/4.1/apidocs/mongodb-driver-core/com/mongodb/MongoClientOptions.html ), set the
sslContext property, as in:

SSLContext sslContext = ...

MongoClientOptions options = MongoClientOptions.builder()
.sslEnabled(true)
.sslContext(sslContext)
.build();
MongoClient client = new MongoClient("localhost", options);

Disable Hostname Verification

By default, the driver ensures that the hostname included in the server’s SSL certificate(s) matches the
hostname(s) provided (/mongo-java-driver/4.1/../)
 Search docs
when constructing a MongoClient() (/mongo-java-driver/4.1/apidocs/mongodb-


driver-sync/com/mongodb/client/MongoClient.html ).

If your application needs to disable hostname verification, you must explicitly indicate this in
MongoClientSettings ](/mongo-java-driver/4.1/apidocs/mongodb-driver-
core/com/mongodb/MongoClientSettings.html )

MongoClientSettings settings = MongoClientSettings.builder()

.applyToSslSettings(builder -> {
builder.enabled(true);
builder.invalidHostNameAllowed(true);
})
.build();

or, with the legacy MongoClientOptions ](/mongo-java-driver/4.1/apidocs/mongodb-driver-

core/com/mongodb/MongoClientOptions.html ), using the sslInvalidHostNameAllowed property:

MongoClientOptions.builder()
.sslEnabled(true)
.sslInvalidHostNameAllowed(true)
.build();

JVM System Properties for TLS/SSL

A typical application will need to set several JVM system properties to 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
javax.net.ssl.trustStorePassword : The password to access this trust store

The trust store is typically created with the keytool

(http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) command line program provided
as part of the JDK. For example:

keytool -importcert -trustcacerts -file <path to certificate authority file>

-keystore <path to trust store> -storepass <password>
A typical application will also need to set several JVM system properties to ensure that the client
 (/mongo-java-driver/4.1/../)
presents an TLS/SSL certificate to the MongoDB server:
Search docs 

javax.net.ssl.keyStore The path to a key store containing the client’s TLS/SSL certificates
javax.net.ssl.keyStorePassword The password to access this key store

The key store is typically created with the keytool

(http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) or the openssl
(https://www.openssl.org/docs/apps/openssl.html) command line program.

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).

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.

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 (/mongo-java-driver/4.1/../) Search docs
contrast to the mongo shell and drivers that utilize “soft fail” behavior.


OCSP Stapling

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_r

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”.

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” section in the JSSE Reference Guide
(https://docs.oracle.com/javase/9/security/java-secure-socket-extension-jsse-reference-guide.htm).