对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单
Docs 主页
/ /
安全性
Docs 主页
/
客户端库
/
C
/
安全性
Docs 主页
/
客户端库
/
C
/
安全性

配置传输层安全 (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 时

注意

Let's Encrypt OCSP 弃用

Let's Encrypt 已终止对较新证书的 OCSP支持。 Let's Encrypt 颁发的新证书可能不包含 OCSP 响应程序URL。仅当证书包含 OCSP URI 时，才会进行 OCSP 吊销检查，因此缺少 OCSP URL是正常情况，并不一定表示MongoDB 部署有问题。

支持的库

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

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

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

  • 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 选项或使用 mongoc_ssl_opt_t 中的字段 ca_file 和 ca_dir 来覆盖它。

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

提示

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

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 扩展（请参阅 RFC 7633）将被忽略。

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

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

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

提示

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

管理导入的密钥

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。

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

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

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

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

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

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

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

提示

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

API 文档

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

后退

安全性

来年

身份验证

在此页面上