Docs Menu
Docs Home
/ / /
PHP Library Manual
/

Configure Transport Layer Security (TLS)

On this page

  • Overview
  • Enable TLS
  • Specify a CA File
  • Specify a CA Directory
  • Check Certificate Revocation
  • OCSP
  • Certificate Revocation List
  • Present a Client Certificate
  • Provide a Key Password
  • Allow Insecure TLS
  • API Documentation

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.

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.

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);

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.

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.

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.

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.

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

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);

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.

To learn more about configuring TLS for the PHP library, see the following API documentation:

  • MongoDB\Client

Back

Choose a Connection Target