Configure Transport Layer Security (TLS)
On this page
Overview
In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment.
When you enable TLS for a connection, the PHP library performs the following actions:
Uses TLS to connect to the MongoDB deployment
Verifies the deployment's certificate
Ensures that the certificate certifies the deployment
To learn how to configure your MongoDB deployment for TLS, see the TLS configuration guide in the MongoDB Server manual.
Note
This page assumes prior knowledge of TLS/SSL and access to valid certificates. A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authorities (CAs) is beyond the scope of this documentation.
Tip
The PHP library delegates most TLS behavior to the MongoDB C Driver. For information about how the C driver handles TLS, including configuration steps and expected behavior, see Configuring TLS in the C driver Documentation.
Enable TLS
To enable TLS for the connection to your MongoDB deployment, set the tls
connection
option to true
. You can do this in two ways: by using the uriOptions
parameter
of the MongoDB\Client
constructor or through a parameter in your connection string.
$uri = 'mongodb://<hostname>:<port>'; $options = [ 'tls' => true ]; $client = new MongoDB\Client($uri, $options);
$uri = 'mongodb://<hostname>:<port>/?tls=true'; $client = MongoDB\Client($uri);
Tip
If your connection string includes the +srv
modification, which specifies the
SRV connection format, TLS is enabled on your connection by default.
To learn more about the SRV connection format, see SRV Connection Format in the MongoDB Server documentation.
Specify a CA File
During the TLS handshake, the MongoDB deployment presents a certificate key file to your application to establish its identity. Usually, a deployment's certificate has been signed by a well-known CA (certificate authority), and your application relies on this CA to validate the certificate.
During testing, however, you might want to act as your own CA. In this case, you must instruct the PHP library to use your CA certificates instead of ones signed by another CA.
To do so, use the tlsCAFile
connection option to specify the path to a .pem
file
containing the root certificate chain.
You can do this in two ways: by using the uriOptions
parameter
of the MongoDB\Client
constructor or through a parameter in your connection string.
$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);
Specify a CA Directory
If you are using OpenSSL or LibreSSL (libtls
) for TLS support, you can also use
the ca_dir
option to instruct
the PHP library to search for a CA file within a directory. The driver searches this
directory if it doesn't find a CA file at the path specified in the tlsCAFile
option.
The following code example shows how to use the driverOptions
parameter to specify the
ca_dir
option:
$uri = 'mongodb://<hostname>:<port>'; $uriOptions = [ 'tls' => true, ]; $driverOptions = [ 'ca_dir' => '/path/to/search/' ]; $client = new MongoDB\Client($uri, $uriOptions, $driverOptions);
Tip
This option corresponds to the OpenSSL SSL_CTX_load_verify_locations parameter and the LibreSSL tls_config_set_ca_path parameter.
Check Certificate Revocation
When an X.509 certificate is no longer trustworthy—for example, if its private key has been compromised—the CA revokes the certificate. The PHP library includes two ways to check whether a server's certificate has been revoked.
OCSP
The Online Certificate Status Protocol (OCSP) process varies depending on the version of MongoDB Server you're connecting to:
MongoDB v4.4 or later: The server staples a time-stamped OCSP response to its certificate. The PHP library validates the certificate against the OCSP response. If the CA has revoked the certificate, or if the OCSP response is otherwise invalid, the TLS handshake fails.
MongoDB v4.3 or earlier: The server supplies an OCSP endpoint, which the PHP library contacts directly. The PHP library then validates the certificate against the OCSP response. If the CA hasn't revoked the certificate, the TLS handshake continues, even if the OCSP response is invalid or malformed.
To stop the PHP library from contacting the OCSP endpoint, set the
tlsDisableOCSPEndpointCheck
connection option to true
.
You can do this in two ways: by passing an argument to the
MongoDB\Client
constructor or through a parameter in your connection string.
$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);
Note
Even if the tlsDisableOCSPEndpointCheck
option is set to true
, the PHP library
still verifies any OCSP response stapled to a server's certificate.
Certificate Revocation List
Instead of using OCSP, you can use the instruct the PHP library
to check the server's certificate
against a Certificate Revocation List (CRL) published by the CA. To do so, set the
crl_file
option to the file path of the CRL. Include this option in the
driverOptions
parameter of the MongoDB\Client
constructor, as shown
in the following code example:
$uri = 'mongodb://<hostname>:<port>'; $uriOptions = [ 'tls' => true, ]; $driverOptions = [ 'crl_file' => '/path/to/file.pem' ]; $client = new MongoDB\Client($uri, $uriOptions, $driverOptions);
Tip
You can specify a CRL file in either the .pem
or .der
format.
Present a Client Certificate
Some MongoDB deployments require every connecting application to present a client certificate
that proves its identity. To specify the client certificate for the PHP library to
present, set the tleCertificateKeyFile
option to the file path of the .pem
file that
contains your certificate and private key.
You can do this in two ways: by using the uriOptions
parameter
of the MongoDB\Client
constructor or through a parameter in your connection string.
$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);
Important
Your client certificate and private key must be in the same .pem
file. If they
are stored in different files, you must concatenate them. The following example
shows how to concatenate a key file and a certificate file into a third file called
combined.pem
on a Unix system:
cat key.pem cert.pem > combined.pem
Provide a Key Password
If the private key in your certificate file is encrypted, you must use the
tlsCertificateKeyFilePassword
option to provide the password.
You can do this in two ways: by using the uriOptions
parameter
of the MongoDB\Client
constructor or through a parameter in your connection string.
$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);
Allow Insecure TLS
When TLS is enabled, the PHP library automatically verifies the certificate that the server presents. When testing your code, you can disable this verification. This is known as insecure TLS.
When insecure TLS is enabled, the driver requires only that the server present an X.509 certificate. The driver accepts a certificate even if any of the following are true:
The hostname of the server and the subject name (or subject alternative name) on the certificate don't match.
The certificate is expired or not yet valid.
The certificate doesn't have a trusted root certificate in the chain.
The certificate purpose isn't valid for server identification.
Note
Even when insecure TLS is enabled, communication between the client and server is encrypted with TLS.
To enable insecure TLS, set the tlsInsecure
connection
option to true
. You can do this in two ways: by passing an argument to the
MongoDB\Client
constructor or through a parameter in your connection 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);
To disable only certificate validation, set the tlsAllowInvalidCertificates
option to
true
, and set the tlsInsecure
option to false
or omit it:
$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);
To disable only hostname verification, set the tlsAllowInvalidHostnames
option to
true
, and set the tlsInsecure
option to false
or omit it:
$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);
Warning
Don't Use in Production
Always set the tlsInsecure
, tlsAllowInvalidCertificates
, and
tlsAllowInvalidHostnames
options to false
in production.
Setting any of these options to true
in a production environment makes
your application insecure and potentially
vulnerable to expired certificates and to foreign processes posing
as valid client instances.
API Documentation
To learn more about configuring TLS for the PHP library, see the following API documentation: