TLS/SSL

The Java driver supports TLS/SSL connections to MongoDB servers using the underlying support for TLS/SSL provided by the JDK. To use TLS/SSL, you must configure the asynchronous driver to use Netty.

Specify TLS/SSL and Netty Configuration

Via Connection String

To configure the driver to use Netty, include the ssl=true and streamType=netty options in the connection string, as in:

MongoClient client = MongoClients.create("mongodb://localhost/?streamType=netty&ssl=true");

Via MongoClientSettings

To specify TLS/SSL with MongoClientSettings , set the sslEnabled property to true, and the stream factory to NettyStreamFactoryFactory, as in

EventLoopGroup eventLoopGroup = new NioEventLoopGroup();  // make sure application shuts this down


MongoClient client = MongoClients.create(MongoClientSettings.builder()
                        .clusterSettings(ClusterSettings.builder()
                                          .hosts(Arrays.asList(new ServerAddress()))
                                          .build())
                        .streamFactoryFactory(NettyStreamFactoryFactory.builder()
                                          .eventLoopGroup(eventLoopGroup).build())
                        .sslSettings(SslSettings.builder()
                                          .enabled(true)
                                          .build())
                        .build());

By default, the Netty-based streams will use the NioEventLoopGroup and Netty’s default ByteBufAllocator, but these are configurable via the NettyStreamFactoryFactory constructor.

To override the default javax.net.ssl.SSLContext used for SSL connections, set the sslContext property on the SslSettings, as in:

 SSLContext sslContext = ...
 SslSettings sslSettings = SslSettings.builder()
                                      .enabled(true)
                                      .sslContext(sslContext)
                                      .build();
 // Pass sslSettings to the MongoClientSettings.Builder

Disable Hostname Verification

By default, the driver ensures that the hostname included in the server’s SSL certificate(s) matches the hostname(s) provided when creating a MongoClient. However, the hostname verification requires a Java 7 JVM, as it relies on additions introduced in Java 7 to the javax.net.SSLParameters class.

If your application must run on Java 6, or for some other reason you need to disable host name verification, you must explicitly indicate this using the invalidHostNameAllowed property:

EventLoopGroup eventLoopGroup = new NioEventLoopGroup();  // make sure application shuts this down

MongoClient client = MongoClients.create(MongoClientSettings.builder()
                                                 .clusterSettings(ClusterSettings.builder()
                                                                          .hosts(Arrays.asList(new ServerAddress()))
                                                                          .build())
                                                  .sslSettings(SslSettings.builder()
                                                                       .enabled(true)
                                                                       .invalidHostNameAllowed(true)
                                                                       .build())
                                                  .streamFactoryFactory(NettyStreamFactoryFactory.builder()
                                                                            .eventLoopGroup(eventLoopGroup).build())
                                                  .build());

Or via the connection string:

MongoClient client = MongoClients.create("mongodb://localhost/?ssl=true&sslInvalidHostNameAllowed=true&streamType=netty");

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 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 presents an TLS/SSL certificate to the MongoDB server:

• 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 or the openssl command line program.

For more information on configuring a Java application for TLS/SSL, please refer to the JSSE Reference Guide.