Database Manual / Security / Encryption / TLS/SSL

Developing MongoDB Locally with TLS使用TLS在本地开发MongoDB

MongoDB Atlas provides valid TLS certificates for development environments, but you may need to implement an on-premises deployment with customized security configurations. This guide provides instructions for setting up TLS encryption for a local MongoDB deployment, allowing you to create a secure testing environment that closely resembles production infrastructure.MongoDB Atlas为开发环境提供了有效的TLS证书，但您可能需要实现具有自定义安全配置的本地部署。本指南提供了为本地MongoDB部署设置TLS加密的说明，允许您创建一个与生产基础设施非常相似的安全测试环境。

Using either Community Edition or Enterprise MongoDB locally with TLS encryption provides a realistic environment for development, testing, and validating your application's security behaviors before deployment.在部署之前，在本地使用带有TLS加密的社区版或企业版MongoDB为开发、测试和验证应用程序的安全行为提供了一个现实的环境。

Self-Signed Certificate Chains for Local TLS本地TLS的自签名证书链

In production environments, MongoDB servers use certificates signed by trusted certificate authorities, or CAs. For local development, you can use any of the following options:在生产环境中，MongoDB服务器使用由受信任的证书颁发机构（CA）签名的证书。对于本地开发，您可以使用以下任何选项：

  • Commercial or Public CA Certificates: If you have registered a domain name, you can obtain a certificate from a recognized certificate authority.商业或公共CA证书：如果您已注册域名，则可以从公认的证书颁发机构获得证书。
  • Enterprise CA Certificates: If your organization maintains a private certificate authority like EJBCA or TinyCert, you can request certificates through your IT department.企业CA证书：如果组织维护一个私有证书颁发机构，如EJBCA或TinyCert，您可以通过IT部门申请证书。
  • Free CA Certificates: If you have a registered domain name, services like Let's Encrypt provide free certificate authority-signed certificates.免费CA证书：如果您有注册域名，Let's Encrypt等服务将提供免费的证书颁发机构签名的证书。
  • Self-Signed Certificates: For isolated local development environments, self-signed certificate chains provide a practical solution when other options aren't available.自签名证书：对于孤立的本地开发环境，当其他选项不可用时，自签名证书链提供了一种实用的解决方案。

You can implement self-signed certificate chain for local MongoDB deployments using the following steps. By creating your own certificate authority and server certificates, you can simulate TLS-encrypted connections without the need for external services.您可以使用以下步骤为本地MongoDB部署实现自签名证书链。通过创建自己的证书颁发机构和服务器证书，您可以模拟TLS加密连接，而不需要外部服务。

Important

Only use self-signed certificate chains in isolated development environments. Self-signed certificate chains do not contain the trust verification mechanisms of properly issued certificates and may present security vulnerabilities. Never use self-signed certificates in production or when working with sensitive data.仅在隔离的开发环境中使用自签名证书链。自签名证书链不包含正确颁发的证书的信任验证机制，可能存在安全漏洞。切勿在生产或处理敏感数据时使用自签名证书。

Server Certificates in TLS CommunicationsTLS通信中的服务器证书

In secure communications, server certificates prove the server's identity to connecting clients, preventing man-in-the-middle attacks, and facilitate secure key exchange for encrypted communications.在安全通信中，服务器证书向连接的客户端证明服务器的身份，防止中间人攻击，并促进加密通信的安全键交换。

In a typical TLS handshake, the client verifies the server certificate by checking whether:在典型的TLS握手中，客户端通过检查以下内容来验证服务器证书：

  • The certificate is signed by a trusted certificate authority证书由受信任的证书颁发机构签名
  • The certificate is valid, not expired or revoked证书有效，未过期或吊销
  • The server name in the certificate matches the server being connected to证书中的服务器名称与连接到的服务器匹配

The client accepts root and intermediate CA certificates only if they are present in the client's local trust store. For properly issued certificates, only the issuing authority can access the root certificate's private key, never with the server.只有当根证书和中间CA证书存在于客户端的本地信任存储中时，客户端才会接受它们。对于正确颁发的证书，只有颁发机构可以访问根证书的私钥，而不能访问服务器。

Self-Signed Certificate Chain Layout自签名证书链布局

For your local MongoDB TLS setup with self-signed certificates, you need to create and manage several certificate files that serve different purposes in the TLS handshake.对于使用自签名证书的本地MongoDB TLS设置，您需要创建和管理几个证书文件，这些文件在TLS握手中用于不同的目的。

Server Requirements:服务器要求：

  • A self-signed certificate authority (CA) certificate, which acts as your own trusted root.自签名证书颁发机构（CA）证书，充当您自己的受信任根。
  • The private key of the self-signed CA certificate, which is used to sign server certificates.自签名CA证书的私钥，用于对服务器证书进行签名。
  • A server certificate signed by your self-signed CA, which identifies your MongoDB server.由自签名CA签名的服务器证书，用于标识MongoDB服务器。
  • The private key for the server certificate, which is used for TLS encryption.服务器证书的私钥，用于TLS加密。

Client Requirements:客户要求：

  • The self-signed root CA certificate, which is needed to verify the server's certificate.自签名的根CA证书，用于验证服务器的证书。
  • Client certificates and their private keys, which is optional and used for mutual TLS.客户端证书及其私钥，这是可选的，用于双向TLS。

When you configure MongoDB, specify paths to these certificate files in your server and client configurations to establish secure TLS connections.配置MongoDB时，在服务器和客户端配置中指定这些证书文件的路径，以建立安全的TLS连接。

Important

In a production environment with certificates from a recognized CA, you do not have access to the private key for the root certificate authority. This is a special exception for self-signed certificate chains in development environments.在具有来自公认CA的证书的生产环境中，您无权访问根证书颁发机构的私钥。这是开发环境中自签名证书链的一个特殊例外。

Create a Self-Signed Certificate Chain创建自签名证书链

The following code uses the openssl command-line tool to create a complete self-signed certificate chain for your MongoDB deployment. This process creates all necessary certificates and keys, formatted for use with MongoDB.以下代码使用openssl命令行工具为MongoDB部署创建完整的自签名证书链。此过程创建所有必要的证书和键，格式化以供MongoDB使用。

# Creating self-signed CA cert and SAN cert for localhost
# aka mdbinstance.mydevelopment.net
#=====================================================================================
openssl req -x509 -nodes -sha256 -days 1825 -newkey rsa:4096 \
 -keyout rootCA.key -out rootCA.crt -subj="/CN=ca.mydevelopment.net"
openssl req -newkey rsa:4096 -keyout server.key -nodes \
 -out domain.csr -subj "/CN=server.mydevelopment.net"
openssl req -x509 -nodes -CA rootCA.crt -CAkey rootCA.key -in domain.csr \
 -out mdbinstance.mydevelopment.net.crt -days 3560 -nodes \
 -subj '/CN=<mdbinstance_mydevelopment_net>' -extensions san -config <( \
   echo '[req]'; \
   echo 'distinguished_name=req'; \
   echo '[san]'; \
   echo 'subjectAltName=DNS:localhost,DNS:mdbinstance.mydevelopment.net')
cat rootCA.key rootCA.crt >rootCAcombined.pem
cat server.key mdbinstance.mydevelopment.net.crt >serverCert.pem

The previous commands perform the following actions:前面的命令执行以下操作：

  1. Creates a root CA certificate, rootCA.crt, and its private key, rootCA.key创建根CA证书rootCA.crt及其私钥rootCA.key
  2. Generates a certificate signing request, or a CSR, for your server为服务器生成证书签名请求或CSR
  3. Creates a server certificate with Subject Alternative Names, or SANs, for both localhost and mdbinstance.mydevelopment.net为localhost和mdbinstance.mydevelopment.net创建具有主题替代名称或SAN的服务器证书
  4. Combines the certificates and keys into the PEM files needed for MongoDB将证书和键合并到MongoDB所需的PEM文件中

The commands above produce the following files.上面的命令生成以下文件。

For MongoDB Server Configuration:对于MongoDB服务器配置：

  • rootCAcombined.pem: Combined CA certificate and private key：组合CA证书和私钥
  • serverCert.pem: Combined server certificate and private key：服务器证书和私钥组合

For Client Applications:对于客户端应用程序：

  • rootCA.crt: The CA certificate, used to trust the server certificate：CA证书，用于信任服务器证书
  • serverCert.pem: The server certificate with its private key, used for TLS connection：服务器证书及其私钥，用于TLS连接

MongoDB Server TLS ConfigurationMongoDB服务器TLS配置

Once you have generated your certificates, configure your MongoDB server to use them. The configuration below shows the net section of the mongod.conf file, focusing on the TLS settings.生成证书后，配置MongoDB服务器以使用它们。下面的配置显示了mongod.conf文件的net部分，重点是TLS设置。

# network interfaces
net:
  port: 27017
  bindIp: 0.0.0.0  # Binds to all network interfaces - use only in secure networks
  tls:
    mode: requireTLS  # Forces all connections to use TLS
    certificateKeyFile: /path/to/serverCert.pem  # Server certificate with private key
    CAFile: /path/to/rootCAcombined.pem  # CA certificate with private key

The configuration above includes:上述配置包括：

  • port: Standard MongoDB port 27017：标准MongoDB端口27017
  • bindIp: Set to 0.0.0.0 to allow connections from any IP address, appropriate only for development environments on secure private networks：设置为0.0.0.0以允许来自任何IP地址的连接，仅适用于安全专用网络上的开发环境
  • tls.mode: Set to requireTLS to ensure all connections use TLS encryption：设置为requireTLS以确保所有连接都使用TLS加密
  • certificateKeyFile: Path to your server certificate with its private key：服务器证书及其私钥的路径
  • CAFile: Path to your CA certificate with its private key：CA证书及其私钥的路径

After updating the configuration file, restart your MongoDB server to apply the TLS settings. Your MongoDB instance then requires TLS for all connections.更新配置文件后，重新启动MongoDB服务器以应用TLS设置。然后，MongoDB实例要求所有连接都使用TLS。

Connecting to MongoDB with TLS使用TLS连接到MongoDB

The following examples demonstrate how to establish connections to your MongoDB server configured for TLS.以下示例演示了如何建立与配置为TLS的MongoDB服务器的连接。

MongoDB Shell
mongosh --tls --tlsCAFile /path/to/rootCA.crt --tlsCertificateKeyFile \
/path/to/serverCert.pem 'mongodb://userid:password@hostname.domain'
Compass

For MongoDB Compass connections, URL-encode the certificate paths in your connection string. For example, convert forward-slashes (/) to %2F:对于MongoDB Compass连接，在连接字符串中对证书路径进行URL编码。例如，将正斜杠（/）转换为%2F：

mongodb://userid:password@hostname.domain/?directConnection=true&tls=true&tlsCAFile=%2Fpath%2Fto%2FrootCA.crt&tlsCertificateKeyFile=%2Fpath%2Fto%2Fserver_certificate.pem
PHP
$mongodb_client = new MongoDB\Client($mongodb_uri,
   [
      'tls' => true,  # Enable TLS for the connection
      'tlsCAFile' => $mongodb_ca_cert_path,  # Path to your CA certificate
      'tlsCertificateKeyFile' => $mongodb_cert_path  # Path to your client certificate
   ]
);

For all clients, you need to provide:对于所有客户端，您需要提供：

  1. The option to enable TLS启用TLS的选项
  2. The path to your CA certificate to trust the server信任服务器的CA证书的路径
  3. Optionally, for mutual TLS, the path to a client certificate对于双向TLS，可以选择客户端证书的路径

Testing your connection confirms that your TLS setup is working correctly. If the connection succeeds, your MongoDB deployment is secured with TLS encryption.测试连接可确认TLS设置工作正常。如果连接成功，MongoDB部署将使用TLS加密进行保护。

Using Trusted Certificate Authorities使用受信任的证书颁发机构

Although self-signed certificates work for development, production environments should use certificates from trusted certificate authorities. If you have a registered domain name, Let's Encrypt offers free certificates that are widely trusted.尽管自签名证书适用于开发，但生产环境应使用来自受信任证书颁发机构的证书。如果您有注册域名，Let's Encrypt提供广泛信任的免费证书。

When using certificates from recognized CAs, ensure that the CA's root and intermediate certificates are part of the operating system's trust store on both the server and clients.使用来自公认CA的证书时，请确保CA的根证书和中间证书是服务器和客户端上操作系统信任存储的一部分。

In production deployments with trusted certificates, configure your MongoDB server settings using the following code:在具有可信证书的生产部署中，使用以下代码配置MongoDB服务器设置：

net:
   tls:
      mode: requireTLS
      certificateKeyFile: /etc/ssl/mongodb.pem  # Your trusted certificate with private key

In the previous configuration, mongodb.pem contains your server's certificate, signed by a trusted CA, and its private key. 在前面的配置中，mongodb.pem包含由受信任的CA签名的服务器证书及其私钥。Because the CA is already trusted by the operating system, you don't need to specify the CAFile parameter.因为CA已经被操作系统信任，所以不需要指定CAFile参数。

For more details on configuring MongoDB with trusted certificates, see Configure mongod and mongos for TLS/SSL on Self-Managed Deployments.有关使用可信证书配置MongoDB的更多详细信息，请参阅在自我管理部署上为TLS/SSL配置mongod和mongos。