Configure Transport Layer Security (TLS)

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.

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

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

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

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.

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

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

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

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

$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.

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

API Documentation

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

• MongoDB\Client