Skip to content

Commit c7f80a4

Browse files
mongoKartmongoKart
committed
first draft
1 parent f4d7b49 commit c7f80a4

15 files changed

+517
-0
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,4 @@ php-library = "MongoDB PHP Library"
2727
php-library = "MongoDB PHP Library"
2828
mdb-server = "MongoDB Server"
2929
api = "https://www.mongodb.com/docs/php-library/current/reference"
30+
mdb-servewr = "MongoDB Server"

‎source/connect/tls.txt

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
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 instance, 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, and your application relies on this CA to validate the certificate.
78+
79+
During testing, however, you might want to act as your own CA.
80+
In this case, you must instruct {+driver-short+} to
81+
use your CA certificates instead of ones signed by another CA.
82+
83+
To do so, use the ``tlsCAFile`` connection option to specify the path to a ``.pem`` file
84+
containing the root certificate chain.
85+
You can do this in two ways: by using the ``uriOptions`` parameter
86+
of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
87+
88+
.. include:: /includes/connect/ca-file-tabs.rst
89+
90+
.. _php-specify-ca-directory:
91+
92+
Specify a CA Directory
93+
~~~~~~~~~~~~~~~~~~~~~~
94+
95+
If you are using OpenSSL or LibreSSL (``libtls``) for TLS support, you can also use
96+
the ``ca_dir`` option to instruct
97+
the {+driver-short+} to search for a CA file within a directory. The driver searches this
98+
directory if it doesn't find a CA file at the path specified in the ``tlsCAFile`` option.
99+
100+
The following code example shows how to use the ``driverOptions`` parameter to specify the
101+
``ca_dir`` option:
102+
103+
.. literalinclude:: /includes/connect/ca-dir.php
104+
:language: php
105+
:copyable: true
106+
107+
.. tip::
108+
109+
This option corresponds to the OpenSSL
110+
`SSL_CTX_load_verify_locations <https://linux.die.net/man/3/ssl_ctx_load_verify_locations>`__
111+
parameter and
112+
the LibreSSL `tls_config_set_ca_path <https://man.openbsd.org/tls_load_file.3>`__
113+
parameter.
114+
115+
.. _php-certificate-revocation:
116+
117+
Check Certificate Revocation
118+
----------------------------
119+
120+
When an X.509 certificate is no longer trustworthy—for example, if its private key
121+
has been compromised—the CA revokes the certificate. The {+driver-short+} includes two ways
122+
to check whether a server's certificate has been revoked.
123+
124+
.. _php-disable-ocsp:
125+
126+
OCSP
127+
~~~~
128+
129+
The Online Certificate Status Protocol (OCSP) process varies depending on the version of
130+
{+mdb-server+} you're connecting to:
131+
132+
- **MongoDB v4.4 or later:** The server staples a
133+
time-stamped OCSP response to its certificate. The {+driver-short+} validates the certificate
134+
against the OCSP response. If the CA has revoked the certificate, or if the OCSP response
135+
is otherwise invalid, the TLS handshake fails.
136+
- **MongoDB v4.3 or earlier:** The server supplies an OCSP endpoint, which the {+driver-short+}
137+
contacts directly. The {+driver-short+} then validates the certificate against the OCSP
138+
response. If the CA hasn't revoked the certificate, the TLS handshake continues, even if
139+
the OCSP response is invalid or malformed.
140+
141+
To stop the {+driver-short+} from contacting the OCSP endpoint, set the
142+
``tlsDisableOCSPEndpointCheck`` connection option to ``true``.
143+
You can do this in two ways: by passing an argument to the
144+
``MongoDB\Client`` constructor or through a parameter in your connection string.
145+
146+
.. include:: /includes/connect/ocsp-tabs.rst
147+
148+
.. note::
149+
150+
Even if the ``tlsDisableOCSPEndpointCheck`` option is set to ``true``, {+driver-short+}
151+
still verifies any OCSP response stapled to a server's certificate.
152+
153+
.. _php-crl:
154+
155+
Certificate Revocation List
156+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
157+
158+
Instead of using OCSP, you can use the instruct the {+driver-short+}
159+
to check the server's certificate
160+
against a Certificate Revocation List (CRL) published by the CA. To do so, set the
161+
``crl_file`` option to the file path of the CRL. Include this option in the
162+
``driverOptions`` parameter of the ``MongoDB\Client`` constructor, as shown
163+
in the following code example:
164+
165+
.. literalinclude:: /includes/connect/crl-file.php
166+
:language: php
167+
:copyable: true
168+
169+
.. tip::
170+
171+
You can specify a CRL file in either the ``.pem`` or ``.der`` format.
172+
173+
.. _php-client-cert:
174+
175+
Present a Client Certificate
176+
----------------------------
177+
178+
Some MongoDB deployments require every connecting application to present a client certificate
179+
that proves its identity. To specify the client certificate for the {+driver-short+} to
180+
present, set the ``tleCertificateKeyFile`` option to the file path of the ``.pem`` file that
181+
contains your certificate and private key.
182+
183+
You can do this in two ways: by using the ``uriOptions`` parameter
184+
of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
185+
186+
.. include:: /includes/connect/client-cert-tabs.rst
187+
188+
.. important::
189+
190+
Your client certificate and private key must be in the same ``.pem`` file. If they
191+
are stored in different files, you must concatenate them. The following example
192+
shows how to concatenate a key file and a certificate file into a third file called
193+
``combined.pem`` on a Unix system:
194+
195+
.. code-block:: sh
196+
197+
$ cat key.pem cert.pem > combined.pem
198+
199+
.. _php-key-file-password:
200+
201+
Provide a Key Password
202+
~~~~~~~~~~~~~~~~~~~~~~
203+
204+
If the private key in your certificate file is encrypted, you must use the
205+
``tlsCertificateKeyFilePassword`` option to provide the password.
206+
You can do this in two ways: by using the ``uriOptions`` parameter
207+
of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
208+
209+
.. include:: /includes/connect/key-file-password.rst
210+
211+
.. _php-insecure-tls:
212+
213+
Allow Insecure TLS
214+
------------------
215+
216+
When TLS is enabled, the {+driver-short+} automatically verifies the certificate that
217+
the server presents. When testing your code, you can disable this verification.
218+
This is known as *insecure TLS.*
219+
220+
When insecure TLS is enabled, the driver requires only that the server present an
221+
X.509 certificate. The driver accepts a certificate even if any of the following are
222+
true:
223+
224+
- The hostname of the server and the subject name (or subject alternative name)
225+
on the certificate don't match.
226+
- The certificate is expired or not yet valid.
227+
- The certificate doesn't have a trusted root certificate in the chain.
228+
- The certificate purpose isn't valid for server identification.
229+
230+
.. note::
231+
232+
Even when insecure TLS is enabled, communication between the client and server
233+
is encrypted with TLS.
234+
235+
To enable insecure TLS, set the ``tlsInsecure`` connection
236+
option to ``true``. You can do this in two ways: by passing an argument to the
237+
``MongoDB\Client`` constructor or through a parameter in your connection string.
238+
239+
.. include:: /includes/connect/insecure-tls-tabs.rst
240+
241+
To disable only certificate validation, set the ``tlsAllowInvalidCertificates`` option to
242+
``true``, and set the ``tlsInsecure`` option to ``false`` or omit it:
243+
244+
.. include:: /includes/connect/disable-cert-validation-tabs.rst
245+
246+
To disable only hostname verification, set the ``tlsAllowInvalidHostnames`` option to
247+
``true``, and set the ``tlsInsecure`` option to ``false`` or omit it:
248+
249+
.. include:: /includes/connect/disable-host-verification-tabs.rst
250+
251+
.. warning:: Don't Use in Production
252+
253+
Always set the ``tlsInsecure``, ``tlsAllowInvalidCertificates``, and
254+
``tlsAllowInvalidHostnames`` options to ``false`` in production.
255+
256+
Setting any of these options to ``true`` in a production environment makes
257+
your application insecure and potentially
258+
vulnerable to expired certificates and to foreign processes posing
259+
as valid client instances.
260+
261+
API Documentation
262+
-----------------
263+
264+
To learn more about configuring TLS for the {+driver-short+},
265+
see the following API documentation:
266+
267+
- :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/compression-tabs.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. tabs::
2+
3+
.. tab:: MongoClient
4+
:tabid: mongoclient
5+
6+
.. code-block:: python
7+
8+
client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
9+
compressors = "snappy,zstd,zlib")
10+
11+
.. tab:: Connection String
12+
:tabid: connectionstring
13+
14+
.. code-block:: python
15+
16+
uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
17+
"compressors=snappy,zstd,zlib")
18+
client = pymongo.MongoClient(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)