在连接上启用 TLS

本页内容

概述

启用 TLS
配置证书
配置 JVM 信任库
配置 JVM 密钥库
配置客户端特定信任库和密钥库
禁用主机名验证
仅允许 TLS 1.2 连接
通过 Java SE SSLContext 定制 TLS 配置
在线证书状态协议 (OCSP)
客户端驱动 OCSP
OCSP Stapling
API 文档

概述

在本指南中，您可以学习如何使用TLS 协议，通过 Kotlin Sync 驱动程序连接到 MongoDB。

启用 TLS

您可以通过以下方式在连接到您的 MongoDB 实例时启用 TLS

设置tls 参数到您的连接字符串
使用 enabled() 方法从 SslSettings.Builder 类中创建一个 MongoClientSettings 实例时

注意

DNS 种子列表协议启用 TLS

如果您使用以 mongodb+srv 前缀表示的 DNS 种子列表协议连接，驱动程序将自动启用 TLS。

有关使用 DNS 种子列表时的连接行为的更多信息，请参阅服务器手册中连接字符串指南的 SRV 连接格式部分。

要使用连接字符串启用连接的 TLS，在选项参数中将 tls 选项设置为 true，然后将字符串传递给 MongoClient.create()，如下所示

val mongoClient = MongoClient.create("mongodb+srv://<db_username>:<db_password>@<cluster_url>/?tls=true")

要在MongoClientSettings实例中启用TLS，请使用applyToSslSettings()构建方法。在SslSettings.Builder块中将enabled属性设置为true，如下所示

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string URI>"))
    .applyToSslSettings { builder ->
        builder.enabled(true)
    }
    .build()
val mongoClient = MongoClient.create(settings)

注意

调试TLS

如果您在设置TLS连接时遇到问题，可以使用系统属性-Djavax.net.debug=all来查看有用的日志语句。有关更多信息，请参阅Java语言文档中的调试SSL/TLS连接。

配置证书

发起TLS请求的Kotlin应用程序需要访问加密证书，这些证书证明应用程序的身份并验证与Kotlin应用程序交互的其他应用程序。您可以通过以下方式在应用程序中配置对这些证书的访问

使用JVM信任存储库和JVM密钥存储库
使用客户端特定的信任存储库和密钥存储库

配置 JVM 信任存储库

注意

默认情况下，JRE 包含许多常用的公共证书，例如来自 Let's Encrypt。因此，您可以在连接到由 JRE 默认证书存储库中权威机构签名的服务器（例如 MongoDB Atlas 实例）时启用 TLS，而无需配置信任存储库。

JVM 信任存储库保存了与您的 Kotlin 应用程序交互的其他应用程序的安全识别证书。通过使用这些证书，您的应用程序可以证明与另一个应用程序的连接是真实的，并且不受第三方篡改。

如果您的 MongoDB 实例使用的是 JRE 默认证书存储库中不存在的权威机构签名的证书，则您的应用程序必须配置以下系统属性以启动 TLS 请求。

javax.net.ssl.trustStore：包含客户端 TLS 证书的信任存储库的路径
javax.net.ssl.trustStorePassword：访问 javax.net.ssl.trustStore 中定义的信任存储库的密码

这些属性确保您的应用程序可以验证连接的 MongoDB 实例提供的 TLS 证书。

您可以使用JDK中的keytool命令行工具创建信任库，如下终端命令所示

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

配置JVM密钥库

注意

默认情况下，MongoDB实例不执行客户端证书验证。如果您已将MongoDB实例配置为验证客户端证书，则必须配置密钥库。

发起TLS请求的应用程序必须设置以下JVM系统属性，以确保客户端向MongoDB服务器提供TLS证书

javax.net.ssl.keyStore：包含客户端TLS/SSL证书的密钥库的路径
javax.net.ssl.keyStorePassword：访问在javax.net.ssl.keyStore中定义的密钥库的密码

您可以使用keytool或openssl命令行工具来创建密钥库。

要了解如何配置Kotlin应用程序使用TLS，请参阅Java语言文档中的JSSE参考指南。

配置特定客户端的信任库和密钥库

您可以通过使用 SSLContext 类的 init() 方法来配置特定客户端的信任库和密钥库。

在本指南的“通过 Java SE SSLContext 自定义 TLS 配置”部分中，您可以找到一个配置客户端使用 SSLContext 实例的示例。

禁用主机名验证

默认情况下，驱动程序确保服务器 TLS 证书中包含的主机名与在构建 MongoClient 时提供的主机名匹配。要禁用应用程序中的主机名验证，请在 applytoSslSettings() 构建块中将构建器的 invalidHostNameAllowed 属性设置为 true。

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string URI>"))
    .applyToSslSettings { builder ->
        builder.enabled(true)
        builder.invalidHostNameAllowed(true)
    }
    .build()
val mongoClient = MongoClient.create(settings);

警告

禁用主机名验证会使您的应用程序不安全，并且可能容易受到过期的证书和冒充有效客户端实例的外部进程的攻击。

仅限制连接到 TLS 1.2

要使应用程序仅使用 TLS 1.2 协议，请将系统属性 jdk.tls.client.protocols 设置为 "TLSv1.2"。

注意

Java 8之前的Java运行时环境（JRE）仅在更新版本中启用了TLS 1.2协议。如果您的JRE未启用TLS 1.2协议，请升级到较新版本以使用TLS 1.2进行连接。

通过Java SE SSLContext自定义TLS配置

如果您的TLS配置需要自定义，您可以通过传递一个SSLContext对象到MongoClient的context()方法构建器中，在applyToSslSettings()块中

val sslContext = SSLContext.getDefault()
val settings = MongoClientSettings.builder()
    .applyToSslSettings { builder ->
        builder.enabled(true)
        builder.context(sslContext)
    }
    .build()
val mongoClient = MongoClient.create(settings);

有关SSLContext类的更多信息，请参阅SSL上下文。的API文档

在线证书状态协议（OCSP）

OCSP是一种用于检查X.509证书是否被撤销的标准。证书颁发机构可以在证书过期之前将其X.509证书添加到证书撤销列表（CRL）中，以使证书无效。当客户端在TLS握手过程中发送X.509证书时，CA的撤销服务器会检查CRL并返回“良好”、“已撤销”或“未知”的状态。

驱动程序支持以下OCSP变体：

客户端驱动 OCSP
OCSP Stapling

以下各节描述了它们之间的区别以及如何为您的应用程序启用它们。

注意

Kotlin Sync驱动程序使用为应用程序配置的JVM参数，不能为特定的MongoClient实例覆盖。

客户端驱动的OCSP

在客户端驱动的OCSP中，客户端在从服务器收到证书后，将证书发送到OCSP响应器的OCSP请求中。OCSP响应器通过证书颁发机构（CA）检查证书状态，并在发送给客户端的响应中报告证书是否有效。

要为您的应用程序启用客户端驱动的OCSP，设置以下JVM系统属性：

属性	值
`com.sun.net.ssl.checkRevocation`	将此属性设置为`true`以启用撤销检查。
`ocsp.enable`	将此属性设置为`true`以启用客户端驱动的OCSP。

警告

如果OCSP响应器不可用，JDK提供的TLS支持将报告“硬失败”。这与MongoDB Shell和一些其他驱动程序的“软失败”行为不同。

OCSP Stapling

OCSP stapling是一种机制，其中服务器必须从证书颁发机构（CA）获取已签名的证书，并将其包含在带有时间戳的OCSP响应中，发送给客户端。

要为您的应用程序启用OCSP stapling，请设置以下JVM系统属性

属性	描述
`com.sun.net.ssl.checkRevocation`	将此属性设置为`true`以启用撤销检查。
`jdk.tls.client.enableStatusRequestExtension`	将此属性设置为`true`以启用OCSP stapling。如果未设置或设置为`false`，则连接可以继续，无论证书吊销响应的存在或状态如何。

有关OCSP的更多信息，请参阅以下资源

Oracle JDK 8关于如何在应用程序中启用OCSP的文档如何为应用程序启用OCSP
OCSP（RFC 6960）的官方IETF规范

API文档

有关本指南中讨论的任何方法或类型的更多信息，请参阅以下API文档

连接选项

下一步

稳定 API