文档菜单
文档首页
/
语言
/
Java
/
Java响应式流驱动程序
/
教程
/
连接到MongoDB

TLS/SSL

本页

  • MongoClient API
  • 在ConnectionString中指定TLS/SSL
  • 在MongoClientSettings中指定TLS/SSL
  • 在MongoClientSettings中指定Java SE SSLContext
  • 通过Netty SslContext自定义TLS/SSL配置
  • 禁用主机名验证
  • 常见的TLS/SSL配置任务
  • 配置信任存储库和密钥存储库
  • 强制使用TLS v1.2
  • OCSP

默认情况下，驱动程序支持使用JDK提供的TLS/SSL底层支持与MongoDB服务器建立TLS/SSL连接。这可以通过利用的扩展性来更改。Java SE API，或者通过使用Netty API

MongoClient API

您可以通过在ConnectionString或一个MongoClientSettings实例中指定选项来配置驱动程序以使用TLS/SSL。

在ConnectionString中指定TLS/SSL

包含以下导入语句

import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoClient;

要在ConnectionString中指定TLS/SSL，请将连接字符串中的ssl=true指定为

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

在MongoClientSettings中指定TLS/SSL

包含以下导入语句

import com.mongodb.MongoClientSettings;
import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoClient;

要在MongoClientSettings实例中指定TLS/SSL，将enabled属性设置为true

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

在MongoClientSettings中指定Java SE SSLContext

包含以下导入语句

import javax.net.ssl.SSLContext;
import com.mongodb.MongoClientSettings;
import com.mongodb.MongoClient;

要指定与MongoClientSettings的javax.net.ssl.SSLContext，设置sslContext属性

SSLContext sslContext = ...
MongoClientSettings settings = MongoClientSettings.builder()
    .applyToSslSettings(builder -> builder.enabled(true).context(sslContext))
    .build();
MongoClient client = new MongoClient(settings);

通过Netty SslContext自定义TLS/SSL配置

包含以下导入语句

import com.mongodb.MongoClientSettings;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;
import io.netty.handler.ssl.SslContext;
import io.netty.handler.ssl.SslContextBuilder;
import io.netty.handler.ssl.SslProvider;

注意

驱动程序使用Netty版本 io.netty:netty-all:4.1.87.Final

要指导驱动程序使用io.netty.handler.ssl.SslContext，在定义你的MongoClientSettings时配置NettyTransportSettings。

使用MongoClientSettings.Builder.transportSettings()和NettyTransportSettings.Builder.sslContext()来构建你的设置

SslContext sslContext = SslContextBuilder.forClient()
        .sslProvider(SslProvider.OPENSSL)
        .build();
MongoClientSettings settings = MongoClientSettings.builder()
        .applyToSslSettings(builder -> builder.enabled(true))
        .transportSettings(TransportSettings.nettyBuilder()
                           .sslContext(sslContext)
                           .build())
        .build();
MongoClient client = MongoClients.create(settings);

有关 io.netty.handler.ssl.SslProvider 的更多详细信息，请参阅 Netty 文档。

禁用主机名验证

默认情况下，驱动程序确保服务器 SSL 证书中的主机名与构建 MongoClient 时提供的主机名匹配。

如果您的应用程序需要禁用主机名验证，您必须在 MongoClientSettings 中明确指出这一点。

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

常见 TLS/SSL 配置任务

本节基于Oracle JDK的文档，因此某些部分可能不适用于您的JDK或您使用的自定义TLS/SSL实现。

配置信任库和密钥库

您可以使用javax.net.ssl.SSLContext.init(KeyManager[] km, TrustManager[] tm, SecureRandom random)来配置特定于客户端的信任库和密钥库，或者您可能需要设置JVM的默认值。

设置默认信任库

典型的应用程序需要设置几个JVM系统属性，以确保客户端可以验证服务器提供的TLS/SSL证书。

  • javax.net.ssl.trustStore：包含签名机构证书的信任库的路径

  • javax.net.ssl.trustStorePassword：访问此信任库的密码

信任库通常使用JDK提供的keytool命令行程序创建

keytool -importcert -trustcacerts -file <path to certificate authority file>
             -keystore <path to trust store> -storepass <trust store password>

设置默认密钥库

典型的应用程序还需要设置几个JVM系统属性，以确保客户端向MongoDB服务器展示 TLS/SSL客户端证书

  • javax.net.ssl.keyStore：包含客户端TLS/SSL证书的密钥库路径

  • javax.net.ssl.keyStorePassword：访问此密钥库的密码

密钥库通常使用keytool或openssl命令行程序创建。例如，如果您有一个包含客户端证书及其私钥的文件，并且您想在PKCS #12格式中创建密钥库，可以运行以下命令

openssl pkcs12 -export -in <path to client certificate & private key file>
             -out <path to key store> -passout pass:<trust store password>

要了解更多关于配置Java应用程序以使用TLS/SSL的信息，请参阅JSSE参考指南。

强制使用 TLS v1.2

某些应用程序可能只想强制使用 TLS 1.2 协议。为此，将 jdk.tls.client.protocols 系统属性设置为 TLSv1.2。

Java 运行时环境在 Java 8 之前仅在后续更新中开始启用 TLS 1.2 协议，如前文所述。对于在 Java 8 之前的 Java 运行时环境中强制使用 TLS 1.2 协议的驱动程序，请确保更新已启用 TLS 1.2。

OCSP

注意

驱动程序默认无法在单个 MongoClient 基础上启用 OCSP。

客户端驱动 OCSP

应用程序需要设置以下 JVM 系统和安全属性以确保启用客户端驱动 OCSP

  • com.sun.net.ssl.checkRevocation：当设置为 true 时，此系统属性启用吊销检查

  • ocsp.enable：当设置为 true 时，此安全属性启用客户端驱动 OCSP

要将应用程序配置为使用客户端驱动的OCSP，应用程序必须已经设置好通过TLS连接到服务器。设置以下系统属性是启用客户端驱动的OCSP所必需的。

注意

JDK提供的TLS支持，在OCSP响应者不可用的情况下使用“硬失败”行为，与mongosh和利用“软失败”行为的驱动程序相反。

OCSP Stapling

重要

当使用TLS 1.3协议的Java运行时环境（Java 11及以上版本默认使用TLS 1.3）与OCSP Stapling一起使用时，可能会发生以下异常

javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request

此异常是由于Java 11及更高版本中TLS 1.3的已知问题。要避免在运行TLS 1.3协议的Java运行时环境中使用此异常，可以强制应用程序使用TLS 1.2协议。为此，将系统属性jdk.tls.client.protocols设置为TLSv1.2。

应用程序需要设置几个JVM系统属性以设置OCSP Stapling

  • jdk.tls.client.enableStatusRequestExtension：当设置为true（其默认值）时，此选项启用OCSP Stapling。

  • com.sun.net.ssl.checkRevocation：当设置为true时，此选项启用吊销检查。如果未将此属性设置为true，则无论吊销信息是否存在或状态如何，都会允许连接继续。

要配置应用程序以使用OCSP Stapling，应用程序必须已经设置好通过TLS连接到服务器，并且服务器必须设置好将OCSP响应附加到TLS握手返回的证书。

有关配置Java应用程序以使用OCSP的更多信息，请参阅Java文档中的Client-Driven OCSP and OCSP Stapling。

返回

连接到MongoDB