为连接启用 TLS

在此页面上

Overview

启用 TLS
配置证书
客户端中的参考证书
创建用于存储证书的 SecureContext 对象
提供证书文件路径
创建缓冲对象以存储证书
SecureContext 示例
更多信息
API 文档

Overview

在本指南中，您可以了解如何使用 TLS 安全协议连接到 MongoDB 实例。

要将您的连接配置为使用 TLS，请启用 TLS 选项并提供您的证书以进行验证。

提示

要学习；了解有关 TLS 的更多信息，请参阅有关传输层安全性的维基百科条目。

启用 TLS

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

在 MongoClientOptions 对象中将 tls 选项设置为 true
在连接字符串中将 tls 选项设置为 true

如果您在 MongoClientOptions 对象中将 tls 设置为 true，则 MongoClient 实例可以使用 TLS 进行连接：

const client = new MongoClient(uri, { tls: true });

如果您在连接string中将 tls 选项设置为 true，则 MongoClient 实例可以使用 TLS 进行连接：

const uri = "mongodb://<hostname>:<port>?tls=true";
const client = new MongoClient(uri, myClientSettings);

注意

如果您在连接到 MongoDB 时通过在连接字符串中指定 +srv 修改来使用 DNS SRV 记录，则默认情况下会在连接上启用 TLS。要禁用 TLS/SSL，请在连接字符串或 MongoClientOptions 对象中将 tls 或 ssl 参数值设为 false。

要进一步了解使用 DNS 种子列表时的连接行为，请参阅服务器手册中的 SRV 连接格式部分。

注意

“不安全的传统重新协商已禁用”错误的解决方法

Node.js驾驶员默认依赖于 OpenSSL。在使用 OpenSSL 3.0 或更高版本的环境中，过时的 SSL 代理可能会导致 unsafe legacy renegotiation disabled 错误。您可以通过设置 SSL_OP_LEGACY_SERVER_CONNECT 选项来解决此错误，如以下示例所示：

import { MongoClient } from 'mongodb';
import crypto from 'crypto';
const client = new MongoClient("mongodb+srv://...", {
   secureContext: {
      secureOptions: crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT
   }
});

除了 tls 客户端选项外，驱动程序还提供了其他选项来配置连接上的 TLS。出于测试目的，您可以设置 tlsAllowInvalidHostnames、tlsAllowInvalidCertificates 和 tlsInsecure 客户端选项。

将 tlsAllowInvalidHostnames 选项设置为 true 会禁用主机名验证，而将 tlsAllowInvalidCertificates 设置为 true 会禁用证书验证。将 tlsInsecure 选项设置为 true 会同时禁用证书和主机名验证。

警告

在生产环境中指定任何这些选项都会导致您的应用程序变得不安全，并有可能对过期证书和伪装成有效客户端实例的外部进程产生潜在威胁。

有关客户端选项的完整列表，请参阅连接选项。

配置证书

要成功发起 TLS 请求，应用程序必须通过引用加密证书来证明其身份。要使用 TLS 连接到 MongoDB，您的证书必须作为 PEM 文件进行存储。

重要

对于生产用途，我们建议您的 MongoDB 部署使用由相同证书颁发机构生成和签名的有效证书。对于测试，您可以使用自签名证书。

以下列表描述了建立 TLS 连接所需的组件：

TLS 组件	说明
证书颁发机构 (CA)	建立 TLS 连接时要信任的一个或多个证书颁发机构。
客户端证书	数字证书和密钥，可允许服务器对您的应用程序进行验证以建立加密的网络连接。
证书密钥	客户端证书私钥文件。此密钥通常包含在证书文件中。
密码	用于解密客户端私钥（如果已加密）的密码。

提示

要了解有关 PEM 格式的更多信息，请参阅有关隐私增强邮件的维基百科条目。

客户端中的参考证书

您必须在 MongoClientOptions 对象中引用您的证书，以便服务器可以在客户端连接之前验证这些证书。可以通过以下方式引用证书：

创建一个 SecureContext 对象来存储证书（建议）。
提供指向证书的文件路径字符串
创建 Buffer 对象以存储证书

创建用于存储证书的 SecureContext 对象

我们建议您使用secureContext 选项来配置您的 TLS 连接。SecureContext对象是 Node.js 原生的，可允许您将所有 TLS 选项保留在单个可重用对象中。

要创建 SecureContext 对象，请从 tls 模块导入 createSecureContext() 方法。接下来，调用 createSecureContext() 方法并在 options 参数中传递证书的内容。此方法会返回一个 SecureContext 对象，您可以在 MongoClientOptions 对象中使用该对象。

以下代码展示了如何创建一个 SecureContext 对象并将其传递给您的客户端：

// Create a SecureContext object
const secureContext = tls.createSecureContext({
  ca: fs.readFileSync(`<path to CA certificate>`),
  cert: fs.readFileSync(`<path to public client certificate>`),
  key: fs.readFileSync(`<path to private client key>`),
});
// Pass the SecureContext as a client option
const client = new MongoClient(uri, { tls: true, secureContext });

要了解有关createSecureContext() 方法和tls 包的更多信息，请参阅 Node.js TLS API 文档。

有关使用 SecureContext 对象的可运行示例，请参阅 SecureContext 示例。

提供证书文件路径

可以将证书的文件路径包含为客户端选项，以便在使用 TLS 进行连接时检索您的证书。当您对 connect() 实例调用 MongoClient 方法时，驱动程序会读取这些文件。

以下代码演示如何将证书文件路径作为选项提供给 MongoClient

// Pass filepaths as client options
const client = new MongoClient(uri, {
  tls: true,
  tlsCAFile: `<path to CA certificate>`,
  tlsCertificateKeyFile: `<path to private client key>`,
});

注意

CRL 文件

您的 TLS 配置可能会要求您在连接到 MongoDB 时提供证书撤销列表 (CRL)。从驱动程序版本 6.0 开始，您可以将 CRL 文件的文件路径传递给连接字符串中的 tlsCRLFile 选项或 MongoClientOptions 实例。

创建缓冲对象以存储证书

您可以将证书文件的内容作为客户端选项中的 Buffer 对象进行传递，以便使用 TLS 进行连接。

以下代码演示了如何读取证书文件的内容并将生成的Buffer 对象作为选项传递到MongoClient

// Read file contents
const ca = fs.readFileSync(`<path to CA certificate>`);
const cert = fs.readFileSync(`<path to public client certificate>`);
const key = fs.readFileSync(`<path to private client key>`);
// Pass Buffers as client options
const client = new MongoClient(uri, { tls: true, ca, cert, key });

SecureContext 示例

此示例演示如何创建 SecureContext 对象和包含 TLS 选项的 MongoClient 实例。示例连接到 MongoDB 并执行查找查询：

import { MongoClient } from "mongodb";
import * as fs from "fs";
import * as tls from "tls";
// Replace the uri string with your connection string.
const uri = "<connection uri>";
// Replace the filepaths with your certificate filepaths.
const secureContext = tls.createSecureContext({
  ca: fs.readFileSync(`<path to CA certificate>`),
  cert: fs.readFileSync(`<path to public client certificate>`),
  key: fs.readFileSync(`<path to private client key>`),
});
// Create a client with the secureContext option
const client = new MongoClient(uri, { tls: true, secureContext });
async function run() {
  try {
    const db = client.db("myDB");
    const myColl = db.collection("myColl");
    const doc = await myColl.findOne({});
    console.log(doc);
  } finally {
    await client.close();
  }
}
run().catch(console.dir);