Skip to content

Commit bdd0fca

Browse files
mongoKartmongoKart
authored
DOCSP-41960 - TLS (#114)
1 parent ad5b511 commit bdd0fca

13 files changed

+500
-1
lines changed

‎snooty.toml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ toc_landing_pages = [
2424
php-library = "MongoDB PHP Library"
2525

2626
[constants]
27+
2728
php-library = "MongoDB PHP Library"
2829
driver-short = "PHP library"
2930
mdb-server = "MongoDB Server"
30-
api = "https://www.mongodb.com/docs/php-library/current/reference"
31+
driver-short = "PHP library"
32+
api = "https://www.mongodb.com/docs/php-library/current/reference"

‎source/connect/tls.txt

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
.. _php-tls:
2+
3+
========================================
4+
Configure Transport Layer Security (TLS)
5+
========================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: security, authentication, transport layer security, encrypt
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the :wikipedia:`TLS <Transport_Layer_Security>`
24+
protocol to secure your connection to a MongoDB deployment.
25+
26+
When you enable TLS for a connection, the {+driver-short+} performs the following actions:
27+
28+
- Uses TLS to connect to the MongoDB deployment
29+
- Verifies the deployment's certificate
30+
- Ensures that the certificate certifies the deployment
31+
32+
To learn how to configure your MongoDB deployment for TLS, see the
33+
:manual:`TLS configuration guide </tutorial/configure-ssl/>` in the
34+
{+mdb-server+} manual.
35+
36+
.. note::
37+
38+
This page assumes prior knowledge of TLS/SSL and access to valid certificates.
39+
A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and
40+
Certificate Authorities (CAs) is beyond the scope of this documentation.
41+
42+
.. tip::
43+
44+
The {+driver-short+} delegates most TLS behavior to the MongoDB C Driver.
45+
For information about how the C driver handles TLS, including configuration steps
46+
and expected behavior, see
47+
`Configuring TLS <https://www.mongodb.com/docs/languages/c/c-driver/current/libmongoc/guides/configuring_tls/#supported-libraries>`__
48+
in the C driver Documentation.
49+
50+
.. _php-enable-tls:
51+
52+
Enable TLS
53+
----------
54+
55+
To enable TLS for the connection to your MongoDB deployment, set the ``tls`` connection
56+
option to ``true``. You can do this in two ways: by using the ``uriOptions`` parameter
57+
of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
58+
59+
.. include:: /includes/connect/tls-tabs.rst
60+
61+
.. tip::
62+
63+
If your connection string includes the ``+srv`` modification, which specifies the
64+
SRV connection format, TLS is enabled on your connection by default.
65+
66+
To learn more about the SRV connection format, see
67+
:manual:`SRV Connection Format </reference/connection-string/#srv-connection-format>`
68+
in the {+mdb-server+} documentation.
69+
70+
.. _php-specify-ca-file:
71+
72+
Specify a CA File
73+
------------------
74+
75+
During the TLS handshake, the MongoDB deployment presents a certificate key file to your
76+
application to establish its identity. Usually, a deployment's certificate has been
77+
signed by a well-known CA (certificate authority), and your application relies on this CA
78+
to validate the certificate.
79+
80+
During testing, however, you might want to act as your own CA.
81+
In this case, you must instruct the {+driver-short+} to
82+
use your CA certificates instead of ones signed by another CA.
83+
84+
To do so, use the ``tlsCAFile`` connection option to specify the path to a ``.pem`` file
85+
containing the root certificate chain.
86+
You can do this in two ways: by using the ``uriOptions`` parameter
87+
of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
88+
89+
.. include:: /includes/connect/ca-file-tabs.rst
90+
91+
.. _php-specify-ca-directory:
92+
93+
Specify a CA Directory
94+
~~~~~~~~~~~~~~~~~~~~~~
95+
96+
If you are using OpenSSL or LibreSSL (``libtls``) for TLS support, you can also use
97+
the ``ca_dir`` option to instruct
98+
the {+driver-short+} to search for a CA file within a directory. The driver searches this
99+
directory if it doesn't find a CA file at the path specified in the ``tlsCAFile`` option.
100+
101+
The following code example shows how to use the ``driverOptions`` parameter to specify the
102+
``ca_dir`` option:
103+
104+
.. literalinclude:: /includes/connect/ca-dir.php
105+
:language: php
106+
:copyable: true
107+
108+
.. tip::
109+
110+
This option corresponds to the OpenSSL
111+
`SSL_CTX_load_verify_locations <https://linux.die.net/man/3/ssl_ctx_load_verify_locations>`__
112+
parameter and
113+
the LibreSSL `tls_config_set_ca_path <https://man.openbsd.org/tls_load_file.3>`__
114+
parameter.
115+
116+
.. _php-certificate-revocation:
117+
118+
Check Certificate Revocation
119+
----------------------------
120+
121+
When an X.509 certificate is no longer trustworthy—for example, if its private key
122+
has been compromised—the CA revokes the certificate. The {+driver-short+} includes two ways
123+
to check whether a server's certificate has been revoked.
124+
125+
.. _php-disable-ocsp:
126+
127+
OCSP
128+
~~~~
129+
130+
The Online Certificate Status Protocol (OCSP) process varies depending on the version of
131+
{+mdb-server+} you're connecting to:
132+
133+
- **MongoDB v4.4 or later:** The server staples a
134+
time-stamped OCSP response to its certificate. The {+driver-short+} validates the certificate
135+
against the OCSP response. If the CA has revoked the certificate, or if the OCSP response
136+
is otherwise invalid, the TLS handshake fails.
137+
- **MongoDB v4.3 or earlier:** The server supplies an OCSP endpoint, which the {+driver-short+}
138+
contacts directly. The {+driver-short+} then validates the certificate against the OCSP
139+
response. If the CA hasn't revoked the certificate, the TLS handshake continues, even if
140+
the OCSP response is invalid or malformed.
141+
142+
To stop the {+driver-short+} from contacting the OCSP endpoint, set the
143+
``tlsDisableOCSPEndpointCheck`` connection option to ``true``.
144+
You can do this in two ways: by passing an argument to the
145+
``MongoDB\Client`` constructor or through a parameter in your connection string.
146+
147+
.. include:: /includes/connect/ocsp-tabs.rst
148+
149+
.. note::
150+
151+
Even if the ``tlsDisableOCSPEndpointCheck`` option is set to ``true``, the {+driver-short+}
152+
still verifies any OCSP response stapled to a server's certificate.
153+
154+
.. _php-crl:
155+
156+
Certificate Revocation List
157+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
158+
159+
Instead of using OCSP, you can use the instruct the {+driver-short+}
160+
to check the server's certificate
161+
against a Certificate Revocation List (CRL) published by the CA. To do so, set the
162+
``crl_file`` option to the file path of the CRL. Include this option in the
163+
``driverOptions`` parameter of the ``MongoDB\Client`` constructor, as shown
164+
in the following code example:
165+
166+
.. literalinclude:: /includes/connect/crl-file.php
167+
:language: php
168+
:copyable: true
169+
170+
.. tip::
171+
172+
You can specify a CRL file in either the ``.pem`` or ``.der`` format.
173+
174+
.. _php-client-cert:
175+
176+
Present a Client Certificate
177+
----------------------------
178+
179+
Some MongoDB deployments require every connecting application to present a client certificate
180+
that proves its identity. To specify the client certificate for the {+driver-short+} to
181+
present, set the ``tleCertificateKeyFile`` option to the file path of the ``.pem`` file that
182+
contains your certificate and private key.
183+
184+
You can do this in two ways: by using the ``uriOptions`` parameter
185+
of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
186+
187+
.. include:: /includes/connect/client-cert-tabs.rst
188+
189+
.. important::
190+
191+
Your client certificate and private key must be in the same ``.pem`` file. If they
192+
are stored in different files, you must concatenate them. The following example
193+
shows how to concatenate a key file and a certificate file into a third file called
194+
``combined.pem`` on a Unix system:
195+
196+
.. code-block:: sh
197+
198+
$ cat key.pem cert.pem > combined.pem
199+
200+
.. _php-key-file-password:
201+
202+
Provide a Key Password
203+
~~~~~~~~~~~~~~~~~~~~~~
204+
205+
If the private key in your certificate file is encrypted, you must use the
206+
``tlsCertificateKeyFilePassword`` option to provide the password.
207+
You can do this in two ways: by using the ``uriOptions`` parameter
208+
of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
209+
210+
.. include:: /includes/connect/key-file-password.rst
211+
212+
.. _php-insecure-tls:
213+
214+
Allow Insecure TLS
215+
------------------
216+
217+
When TLS is enabled, the {+driver-short+} automatically verifies the certificate that
218+
the server presents. When testing your code, you can disable this verification.
219+
This is known as *insecure TLS.*
220+
221+
When insecure TLS is enabled, the driver requires only that the server present an
222+
X.509 certificate. The driver accepts a certificate even if any of the following are
223+
true:
224+
225+
- The hostname of the server and the subject name (or subject alternative name)
226+
on the certificate don't match.
227+
- The certificate is expired or not yet valid.
228+
- The certificate doesn't have a trusted root certificate in the chain.
229+
- The certificate purpose isn't valid for server identification.
230+
231+
.. note::
232+
233+
Even when insecure TLS is enabled, communication between the client and server
234+
is encrypted with TLS.
235+
236+
To enable insecure TLS, set the ``tlsInsecure`` connection
237+
option to ``true``. You can do this in two ways: by passing an argument to the
238+
``MongoDB\Client`` constructor or through a parameter in your connection string.
239+
240+
.. include:: /includes/connect/insecure-tls-tabs.rst
241+
242+
To disable only certificate validation, set the ``tlsAllowInvalidCertificates`` option to
243+
``true``, and set the ``tlsInsecure`` option to ``false`` or omit it:
244+
245+
.. include:: /includes/connect/disable-cert-validation-tabs.rst
246+
247+
To disable only hostname verification, set the ``tlsAllowInvalidHostnames`` option to
248+
``true``, and set the ``tlsInsecure`` option to ``false`` or omit it:
249+
250+
.. include:: /includes/connect/disable-host-verification-tabs.rst
251+
252+
.. warning:: Don't Use in Production
253+
254+
Always set the ``tlsInsecure``, ``tlsAllowInvalidCertificates``, and
255+
``tlsAllowInvalidHostnames`` options to ``false`` in production.
256+
257+
Setting any of these options to ``true`` in a production environment makes
258+
your application insecure and potentially
259+
vulnerable to expired certificates and to foreign processes posing
260+
as valid client instances.
261+
262+
API Documentation
263+
-----------------
264+
265+
To learn more about configuring TLS for the {+driver-short+},
266+
see the following API documentation:
267+
268+
- :ref:`MongoDB\Client <php-mongodb-client>`

‎source/includes/connect/ca-dir.php

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
$uri = "mongodb://<hostname>:<port>";
2+
3+
$uriOptions = [
4+
'tls' => true,
5+
];
6+
7+
$driverOptions = [
8+
'ca_dir' => '/path/to/search/'
9+
];
10+
11+
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

‎source/includes/connect/ca-file-tabs.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. tabs::
2+
3+
.. tab:: MongoDB\\Client
4+
:tabid: mongoclient
5+
6+
.. code-block:: php
7+
8+
$uri = "mongodb://<hostname>:<port>";
9+
10+
$options = [
11+
'tls' => true,
12+
'tlsCAFile' => '/path/to/ca.pem'
13+
];
14+
15+
$client = new MongoDB\Client($uri, $options);
16+
17+
.. tab:: Connection String
18+
:tabid: connectionstring
19+
20+
.. code-block:: php
21+
22+
$uri = "mongodb://<hostname>:<port>/?tls=true&tlsCAFile=/path/to/ca.pem";
23+
$client = MongoDB\Client($uri);

‎source/includes/connect/client-cert-tabs.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. tabs::
2+
3+
.. tab:: MongoDB\\Client
4+
:tabid: mongoclient
5+
6+
.. code-block:: php
7+
8+
$uri = "mongodb://<hostname>:<port>";
9+
10+
$options = [
11+
'tls' => true,
12+
'tlsCertificateKeyFile' => '/path/to/client.pem'
13+
];
14+
15+
$client = new MongoDB\Client($uri, $options);
16+
17+
.. tab:: Connection String
18+
:tabid: connectionstring
19+
20+
.. code-block:: php
21+
22+
$uri = "mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem";
23+
$client = MongoDB\Client($uri);

‎source/includes/connect/crl-file.php

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
$uri = "mongodb://<hostname>:<port>";
2+
3+
$uriOptions = [
4+
'tls' => true,
5+
];
6+
7+
$driverOptions = [
8+
'crl_file' => '/path/to/file.pem'
9+
];
10+
11+
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

‎source/includes/connect/crl-tabs.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. tabs::
2+
3+
.. tab:: MongoDB\\Client
4+
:tabid: mongoclient
5+
6+
.. code-block:: php
7+
8+
$uri = "mongodb://<hostname>:<port>";
9+
10+
$options = [
11+
'tls' => true,
12+
'tlsCRLFile' => '/path/to/crl.pem'
13+
];
14+
15+
$client = new MongoDB\Client($uri, $options);
16+
17+
.. tab:: Connection String
18+
:tabid: connectionstring
19+
20+
.. code-block:: php
21+
22+
$uri = "mongodb://<hostname>:<port>/?tls=true&tlsCRLFile=/path/to/crl.pem";
23+
$client = MongoDB\Client($uri);

0 commit comments

Comments
 (0)