Join us Sept 17 at .local NYC! Use code WEB50 to save 50% on tickets. Learn more >
MongoDB Event
Docs 菜单
Docs 主页
/
语言
/
C 驱动程序
/
C 驱动程序
/
连接至 MongoDB

配置传输层安全 (TLS)

Overview

在本指南中，您可以学习；了解如何使用 TLS协议保护与MongoDB 部署的连接。

为连接启用TLS 时， C驾驶员将执行以下操作：

  • 使用 TLS 连接到 MongoDB 部署

  • 验证部署的证书

  • 确保证书证明部署

要学习；了解如何为 TLS 配置MongoDB 部署，请参阅MongoDB Server手册中的TLS 配置指南。

注意

TLS/SSL、PKI（公钥基础设施）证书和证书颁发机构 (CA) 的完整描述超出了本文档的范围。 本页假设您已了解 TLS/SSL 并可访问有效证书。

启用 TLS

您可以通过以下方式在与 MongoDB 实例的连接上启用 TLS：

  • 在连接string中设置 tls 参数

  • 使用 mongoc_uri_set_option_as_bool() 函数将 MONGOC_URI_TLS 连接选项设立为 true

mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true");
// Do database work here 
mongoc_client_destroy (client);
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017");  
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
mongoc_client_t *client = mongoc_client_new_from_uri (uri);
// Do database work here
mongoc_client_destroy (client);
mongoc_uri_destroy (uri);

提示

如果您的连接string包含 +srv 修饰符（指定 SRV 连接格式），则默认情况下会对您的连接启用 TLS。

要学习；了解有关 SRV 连接格式的更多信息，请参阅MongoDB Server文档中的SRV 连接格式。

指定客户端证书

当您连接到启用了 TLS 的MongoDB 部署时，默认下，该部署会要求客户端提供由证书颁发机构或服务器上使用的原生证书存储信任的颁发机构颁发的客户端证书。

您可以通过以下方式提供客户端证书：

  • 将连接字符串中的 tlsCertificateKeyFile 参数设置为包含根证书链的 .pem文件

  • 使用 mongoc_uri_set_option_as_utf8() 函数将 MONGOC_URI_TLSCERTIFICATEKEYFILE 选项设立为包含根证书链的 .pem文件

mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true&tlscertificatekeyfile=/path/to/certs/client-certificate.pem");
// Do database work here 
mongoc_client_destroy (client);
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017");  
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "/path/to/client-certificate.pem");  
mongoc_client_t *client = mongoc_client_new_from_uri (uri);
// Do database work here
mongoc_client_destroy (client);
mongoc_uri_destroy (uri);

MongoDB Server证书验证

MongoDB C驱动程序将自动验证由配置的证书颁发机构颁发的服务器证书的有效性。 该驾驶员还执行主机名验证和撤销检查。

要覆盖此行为，可以禁用 主机名验证、OCSP 端点撤销检查和所有撤销检查，并允许无效证书。

此行为可使用 tlsAllowInvalidHostnames、tlsDisableOCSPEndpointCheck、tlsDisableCertificateRevocationCheck 和 tlsAllowInvalidCertificates 选项进行控制。 默认下，全部设立为 false。

不建议更改这些默认值，因为您的客户端可能会面临以下安全风险：

  • 中间人攻击，当设立为tlsAllowInvalidHostnames 时

  • 证书无效，当设立tlsAllowInvalidCertificates 时

  • 可能已撤销的证书，当设立了tlsDisableOCSPEndpointCheck 或 tlsDisableCertificateRevocationCheck 时

支持的库

默认下，libmongoc 将尝试查找支持的 TLS 库并启用TLS支持。 它由 cmake 标志 ENABLE_SSL 控制，默认设立为 AUTO。 该标志接受以下值：

  • AUTO：链接到系统的原生TLS 库，或尝试查找 OpenSSL。 这是默认值。

  • OPENSSL：指向 OpenSSL (libssl) 的链接。 可以使用 OPENSSL_ROOT 指定可选的安装路径。

  • LIBRESSL （已弃用）：指向 LibreSSL 的 libtls 的链接。 您可以通过设置 OPENSSL 链接到 LibreSSL 的兼容 libssl。

  • WINDOWS：指向安全通道（ Windows上的原生TLS 库）的链接。

  • DARWIN：指向安全传输（macOS 上的原生TLS 库）的链接。

  • OFF：禁用 TLS支持。

OpenSSL

MongoDB C驱动程序在Linux和 Unix 平台（macOS 除外）上使用 OpenSSL。 行业最佳实践和某些法规要求使用 TLS 1.1 或更高版本，这至少需要 OpenSSL 1.0.1。 使用以下命令检查 OpenSSL 版本：

openssl version

确保系统的 OpenSSL 是最新版本（至少为 1.0.1），或使用以下命令在非系统路径中安装最新版本并对其构建：

cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/openssl

针对 OpenSSL 进行编译时，驾驶员将尝试加载发行版配置的系统默认证书存储。可以通过设置tlsCAFile URI 选项或使用ca_file ca_dirmongoc_ssl_opt_t 中的字段 和 来覆盖它。

使用 OpenSSL1.0.1 + 时，完全支持在线证书状态协议 (OCSP)。但是，当使用crl_file mongoc_ssl_opt_t设立了 并且crl_file 撤销了服务器的证书时，即使该证书具有有效的装订 OCSP 响应，该证书也被视为已撤销。

提示

有关 OCSP 的详细信息，请参阅 RFC6960 。

LibreSSL / libtls（已弃用）

在配置为针对openssl进行编译时， MongoDB C驱动程序通过使用 OpenSSL 兼容性检查来支持 LibreSSL。 当配置为针对libressl进行构建时，它还支持新的libtls库。

使用 LibreSSL 进行编译时，不支持crl_file mongoc_ssl_opt_t 的 选项，使用该选项会报告错误。设置tlsDisableOCSPEndpointCheck 和tlsDisableCertificateRevocationCheck 无效。

部分支持在线证书状态协议 (OCSP)，但有以下说明：

  • Must-Staple 扩展（请参阅 RFC7633 ）被忽略

  • 如果提供了必须装订证书而没有装订响应，并且 OCSP 响应程序已关闭，则连接将继续

  • 如果客户端收到来自 OCSP 响应程序的已撤销响应，则连接不会继续

提示

有关 OCSP 的详细信息，请参阅 RFC6960 。

Windows上的原生 TLS 支持（安全通道）

MongoDB C驱动程序支持Windows原生TLS 库（安全通道或 SChannel）及其原生加密库（加密API：下一代或 CNG）。

针对Windows原生库进行编译时，不支持ca_dir mongoc_ssl_opt_t 的 选项，如果使用该选项，则会出现错误。使用tlsCertificateKeyPassword URI 选项设立的加密 PEM 文件也不受支持，并且在您尝试加载这些文件时会出现错误。

tlsCertificateKeyFile URI 选项可以引用以 PKCS#8 或 PKCS#1 格式编码的证书。从C驾驶员的 2.1.0 版本开始，驾驶员将私钥作为持久密钥导入，以支持现代签名算法。在早期版本中，驾驶员会将密钥作为临时密钥导入。要学习；了解有关管理导入密钥的更多信息，请参阅管理导入密钥。

设立tlsCAFile 时，驾驶员会将证书颁发机构文件导入 System Local Machine Root 证书存储。如果未设立tlsCAFile，驾驶员将使用 System Local Machine Root 证书存储查找证书颁发机构文件，以确认所提供的证书。

当使用crl_file mongoc_ssl_opt_t设立 时，驾驶员会将吊销列表导入System Local Machine Root 证书存储。设置tlsDisableOCSPEndpointCheck 无效。

部分支持在线证书状态协议 (OCSP)，但有以下说明：

  • Must-Staple 扩展（请参阅 RFC7633 ）将被忽略。

  • 如果提供了必须装订证书而没有装订响应，并且 OCSP 响应程序已关闭，则连接将继续。

  • 如果客户端收到来自 OCSP 响应程序的已撤销响应，则连接不会继续。

  • 当crl_file 设立了mongoc_ssl_opt_t ，并且crl_file 撤销了服务器的证书时，OCSP 响应优先。示例，如果服务器提供的证书带有有效装订的 OCSP 响应，则即使crl_file 已将其标记为已撤销，该证书也被视为有效。

提示

有关 OCSP 的详细信息，请参阅 RFC6960 。

管理导入的密钥

C驱动程序将 PKCS#8 密钥导入 CNG KSP：Microsoft Software Key Storage Provider ，并将 PKCS#1 密钥导入传统 CryptoAPI CSP：Microsoft Enhanced Cryptographic Provider v1.0 。要学习；了解有关密钥导入的更多信息，请参阅Microsoft文档中的“密钥存储和检索”。

导入密钥后，您可能需要计算 密钥名称 和提供商、查看密钥或删除密钥。以下 PowerShell 代码计算密钥名称和提供程序：

$cert = "client.pem"
# Compute the SHA256 fingerprint:
$fingerprint = (openssl x509 -in $cert -noout -fingerprint -sha256) -replace 'SHA256 Fingerprint=', '' -replace ':', ''
if (Select-String -Path $cert -Pattern '-----BEGIN RSA PRIVATE KEY-----' -Quiet) {
    # Key name for PKCS#1 key:
    $key_name = "libmongoc-$fingerprint-pkcs1"
    $csp = "Microsoft Enhanced Cryptographic Provider v1.0"
} elseif (Select-String -Path $cert -Pattern '-----BEGIN PRIVATE KEY-----' -Quiet) {
    # Key name for PKCS#8 key:
    $key_name = "libmongoc-$fingerprint-pkcs8"
    $csp = "Microsoft Software Key Storage Provider"
} else {
    Write-Output "Unexpected PEM format for $cert"
}

以下 PowerShell 代码显示有关密钥的详细信息：

certutil -user -csp $csp -key $key_name

以下 PowerShell 代码删除该密钥：

certutil -user -csp $csp -key $key_name

macOS / Darwin 上的原生 TLS 支持（安全传输）

MongoDB C驱动程序支持 Darwin原生TLS 库及其原生加密库 Common Crypto。

针对安全传输进行编译时，不支持ca_dir crl_filemongoc_ssl_opt_t 的 和 选项。使用任一操作都会发出错误。

设立tlsCAFile 时，驾驶员将仅允许由所提供的一个或多个颁发机构颁发的服务器证书。 如果未设立tlsCAFile，驾驶员将使用解锁钥匙串中的证书颁发机构。

针对安全传输进行编译时，设置 tlsDisableOCSPEndpointCheck 和 tlsDisableCertificateRevocationCheck 无效。

部分支持在线证书状态协议 (OCSP)，但注释如下。

  • Must-Staple 扩展（请参阅 RFC7633 ）被忽略

  • 如果提供了必须装订证书而没有装订响应，并且 OCSP 响应程序已关闭，则连接将继续

  • 如果客户端收到来自 OCSP 响应程序的已撤销响应，则连接不会继续

提示

有关 OCSP 的详细信息，请参阅 RFC6960 。

API 文档

有关本指南中提及的对象和函数的更多信息，请参阅以下API文档：

后退

选择连接目标

来年

AWS Lambda

在此页面上