配置传输层安全 (TLS)

在此页面上

Overview

启用 TLS
指定 CA 文件
指定 CA 目录
检查证书撤销
OCSP
证书吊销列表
出示客户端证书
提供密钥密码
允许不安全的 TLS
API 文档

Overview

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

为连接启用TLS 时， PHP库会执行以下操作：

使用 TLS 连接到 MongoDB 部署
验证部署的证书
确保证书证明部署

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

注意

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

提示

PHP库将大多数 TLS 行为委托给MongoDB C驱动程序。有关C驾驶员如何处理 TLS 的信息，包括配置步骤和预期行为，请参阅C驾驶员文档中的配置 TLS 。

启用 TLS

要为与MongoDB 部署的连接启用TLS，设立 tls连接选项设置为true 。您可以通过两种方式执行此操作：使用MongoDB\Client构造函数的uriOptions参数或通过连接字符串中的参数。

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true';
$client = MongoDB\Client($uri);

提示

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

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

指定 CA 文件

在 TLS 握手期间， MongoDB 部署会向您的应用程序提供证书密钥文件，以确定其身份。通常，部署的证书由知名 CA（证书颁发机构）签名，并且您的应用程序依赖此 CA 来验证证书。

但是，在测试过程中，您可能希望充当自己的 CA。在这种情况下，您必须指示PHP库使用您的 CA 证书，而不是其他 CA 签名的证书。

为此，请使用tlsCAFile连接选项指定包含根证书链的.pem文件的路径。您可以通过两种方式执行此操作：使用MongoDB\Client构造函数的uriOptions参数或通过连接字符串中的参数。

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsCAFile' => '/path/to/ca.pem'
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCAFile=/path/to/ca.pem';
$client = MongoDB\Client($uri);

指定 CA 目录

如果使用 OpenSSL 或 LibreSSL ( libtls ) 来支持TLS，还可以使用ca_dir选项指示PHP库在目录中搜索CA文件。如果驾驶员在tlsCAFile选项指定的路径中找不到 CA文件，则会搜索此目录。

以下代码示例演示如何使用driverOptions参数指定ca_dir选项：

$uri = 'mongodb://<hostname>:<port>';
$uriOptions = [
   'tls' => true,
];
$driverOptions = [
    'ca_dir' => '/path/to/search/'
];
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

提示

该选项对应于 OpenSSL SSL_CTX_load_verify_locations 参数和 LibreSSL tls_config_set_ca_path 参数。

检查证书撤销

当 X. 509证书不再可信时（示例，如果其私钥已泄露），CA 将撤销该证书。 PHP库提供两种方法来检查服务器的证书是否已被撤销。

OCSP

在线证书状态协议 (OCSP)进程因要连接的MongoDB Server版本而异：

MongoDB v 4.4或更高版本：服务器将带时间戳的 OCSP 响应装订到其证书中。 PHP库根据 OCSP 响应验证证书。如果 CA 已撤销证书，或者 OCSP 响应无效，则 TLS 握手失败。
MongoDB v 4.3或更早版本：服务器提供PHP库直接联系的 OCSP 端点。然后， PHP库根据 OCSP 响应验证证书。如果 CA 尚未吊销证书，则即使 OCSP 响应无效或格式不正确，TLS 握手也会继续。

要阻止PHP库联系 OCSP 端点，请将tlsDisableOCSPEndpointCheck连接选项设立为true 。您可以通过两种方式执行此操作：将参数传递给MongoDB\Client构造函数，或通过连接字符串中的参数。

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsDisableOCSPEndpointCheck' => true
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsDisableOCSPEndpointCheck=true';
$client = MongoDB\Client($uri);

注意

即使将tlsDisableOCSPEndpointCheck选项设立为true ， PHP库仍会验证绑定到服务器证书的任何 OCSP 响应。

证书吊销列表

您可以使用PHP库根据 CA 发布的证书吊销列表 (CRL) 检查服务器的证书，而不是使用 OCSP。为此，请将crl_file选项设立为 CRL 的文件路径。将此选项包含在MongoDB\Client构造函数的driverOptions参数中，如以下代码示例：

$uri = 'mongodb://<hostname>:<port>';
$uriOptions = [
   'tls' => true,
];
$driverOptions = [
    'crl_file' => '/path/to/file.pem'
];
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

提示

您可以采用.pem或.der格式指定 CRL文件。

出示客户端证书

某些MongoDB部署要求每个连接的应用程序提供证明其身份的客户端证书。要指定PHP库提供的客户端证书，请将tleCertificateKeyFile选项设立为包含证书和私钥的.pem文件的文件路径。

您可以通过两种方式执行此操作：使用MongoDB\Client构造函数的uriOptions参数，或通过连接字符串中的参数。

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsCertificateKeyFile' => '/path/to/client.pem'
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem';
$client = MongoDB\Client($uri);

重要

客户端证书和私钥必须位于同一.pem文件中。如果它们存储在不同的文件中，则必须将它们连接起来。以下示例展示了如何在 Unix 系统上将密钥文件和证书文件连接到名为combined.pem的第三个文件中：

$ cat key.pem cert.pem > combined.pem

提供密钥密码

如果证书文件中的私钥已加密，则必须使用tlsCertificateKeyFilePassword选项提供密码。您可以通过两种方式执行此操作：使用MongoDB\Client构造函数的uriOptions参数或通过连接字符串中的参数。

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsCertificateKeyFile' => '/path/to/client.pem',
   'tlsCertificateKeyFilePassword' => '<passphrase>'
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword=<passphrase>';
$client = MongoDB\Client($uri);

允许不安全的 TLS

启用 TLS 后， PHP库会自动验证服务器提供的证书。测试代码时，可以禁用此验证。这称为不安全的 TLS。

启用不安全 TLS 后，驾驶员仅要求服务器提供 X. 509证书。即使满足以下任一条件，驾驶员也会接受证书：

服务器的主机名与证书上的主题名称（或主题备用名称）不匹配。
证书过期或无效。
证书链中没有受信任的根证书。
证书用途对服务器标识无效。

注意

即使启用了不安全的 TLS，客户端和服务器之间的通信也会使用 TLS 进行加密。

要启用不安全的 TLS，请将tlsInsecure连接选项设置为true 。您可以通过两种方式执行此操作：将参数传递给 MongoDB\Client 构造函数，或通过连接string中的参数。

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsInsecure' => true
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsInsecure=true';
$client = MongoDB\Client($uri);

要仅禁用证书验证，请将tlsAllowInvalidCertificates选项设置为true ，并将tlsInsecure选项设置为false或省略：

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsAllowInvalidCertificates' => true
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidCertificates=true';
$client = MongoDB\Client($uri);

要仅禁用主机名验证，请将tlsAllowInvalidHostnames选项设置为true ，并将tlsInsecure选项设置为false或省略：

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsAllowInvalidHostnames' => true
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidHostnames=true';
$client = MongoDB\Client($uri);

警告

不要在生产中使用

在生产环境中，始终将tlsInsecure 、 tlsAllowInvalidCertificates和tlsAllowInvalidHostnames选项设置为false 。

在生产环境中将这些选项中的任何一个设置为true都会导致应用程序不安全，并且可能容易受到过期证书和冒充有效客户端实例的外部进程的攻击。

API 文档

要学习；了解有关为PHP库配置 TLS 的更多信息，请参阅以下API文档：

MongoDB\Client

后退

选择连接目标

来年

Stable API

配置传输层安全 (TLS).leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}