From 4c67a95d160e551c061d3ad4b10f1b0cd9bedf16 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 22 Apr 2024 13:27:31 -0400 Subject: [PATCH 1/6] DOCSP-35939: tls --- docs/fundamentals/connection/tls.txt | 192 +++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/fundamentals/connection/tls.txt diff --git a/docs/fundamentals/connection/tls.txt b/docs/fundamentals/connection/tls.txt new file mode 100644 index 000000000..7f2e8a253 --- /dev/null +++ b/docs/fundamentals/connection/tls.txt @@ -0,0 +1,192 @@ +.. _laravel-tls: + +======================== +Enable and Configure TLS +======================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, security, connection options + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the TLS protocol to secure +your connection to a MongoDB deployment. To configure your connection to +use TLS, enable the TLS option and provide your certificates for +validation when configuring a connection in your application's +``config/database.php`` file. + +.. tip:: + + To learn more about TLS, see the Wikipedia entry on + :wikipedia:`Transport Layer Security `. + +Enable TLS +---------- + +In your application's ``config/database.php`` file, you can enable TLS +on a connection to your MongoDB deployment in one of the following ways: + +- Setting the ``tls`` option to ``true`` in your connection string +- Setting the ``tls`` option to ``true`` in the ``options`` property + +Select from the following :guilabel:`Connection String` and +:guilabel:`URI Options` tabs to see a corresponding code sample: + +.. tabs:: + + .. tab:: Connection String + :tabid: connection string tls true + + .. code-block:: php + :emphasize-lines: 5 + + 'connections' => [ + + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => 'mongodb://:?tls=true', + 'database' => 'myDB', + ], ... + ] + + .. tab:: URI Options + :tabid: urioptions tls true + + .. code-block:: php + :emphasize-lines: 8 + + 'connections' => [ + + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => '', + 'database' => 'myDB', + 'options' => [ + 'tls' => true, + ], + ], ... + ] + +.. note:: + + If your connection string uses a DNS SRV record by including + the ``mongodb+srv`` prefix, TLS is enabled on your connection by + default. + +Configure Certificates +---------------------- + +To successfully initiate a TLS request, your application must present +cryptographic certificates to prove its identity. Your application's +certificates must be stored as PEM files to enable TLS when connecting. + +.. important:: + + For production use, we recommend that your MongoDB deployment use valid + certificates generated and signed by the same certificate authority. + For testing, your deployment can use self-signed certificates. + +The following list describes the components that your client must +present to establish a TLS-enabled connection: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - TLS Component + - Description + + * - Certificate Authority (CA) + - One or more certificate authorities to + trust when making a TLS connection. + + * - Client Certificate + - A digital certificate that allows the server to verify the identity + of your application to establish an encrypted network connection. + + * - Certificate Key + - The client certificate private key file. This key is often + included within the certificate file itself. + + * - Passphrase + - The password to decrypt the private client key if it is encrypted. + +Reference Certificates +---------------------- + +You must reference your certificates when configuring your ``mongodb`` +connection so that the server can validate them before the client connects. + +We recommend that you reference your certificates and set other TLS +options in the ``options`` property of your connection configuration +instead of in the connection string. This improves readability and +flexibility in your application. + +Set the following options in the ``options`` property to reference your +certificates: + +- ``tlsCAFile`` +- ``tlsCertificateKeyFile`` +- ``tlsCertificateKeyFilePassword`` + +You can specify additional options to configure TLS on your connection. +For **testing purposes**, you can set the +``tlsAllowInvalidCertificates``, ``tlsAllowInvalidHostnames``, or +``tlsInsecure`` fields to ``true``. + +.. warning:: + + Setting these options to ``true`` disables + certificate and hostname validation. + + Specifying these options in a production environment makes + your application insecure and potentially + vulnerable to expired certificates and foreign processes posing + as valid client instances. + +The following example configures a connection with TLS enabled: + +.. code-block:: php + + 'connections' => [ + + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => '', + 'database' => 'myDB', + 'options' => [ + 'tls' => true, + 'tlsCAFile' => '', + 'tlsCertificateKeyFile' => '', + ], + ], ... + ] + +.. note:: + + You can alternatively reference your certificates by setting options + in the ``driverOptions`` property in your connection configuration. + To learn more about these options, see the + `MongoDB\Driver\Manager::__construct() + `__ + API documentation. + +Additional Information +---------------------- + +To learn more about enabling TLS on a connection, see the +following Server manual documentation: + +- :manual:`TLS/SSL (Transport Encryption) ` +- :manual:`TLS/SSL Configuration for Clients ` \ No newline at end of file From c92f572c6eff329b04356443d8fdb7defb328927 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 22 Apr 2024 13:28:32 -0400 Subject: [PATCH 2/6] merge --- docs/fundamentals/connection.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index b1d11c58a..0105aea33 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -7,6 +7,7 @@ Connections .. toctree:: /fundamentals/connection/connect-to-mongodb + /fundamentals/connection/tls .. contents:: On this page :local: @@ -22,4 +23,4 @@ deployment and specify the connection behavior by using {+odm-short+} in the following sections: - :ref:`laravel-connect-to-mongodb` - +- :ref:`laravel-tls` From 603089fc89b69e7be9ae525d14f4a40e60451220 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 22 Apr 2024 16:04:03 -0400 Subject: [PATCH 3/6] CC PR fixes --- docs/fundamentals/connection/tls.txt | 72 ++++++++++++++++------------ 1 file changed, 41 insertions(+), 31 deletions(-) diff --git a/docs/fundamentals/connection/tls.txt b/docs/fundamentals/connection/tls.txt index 7f2e8a253..1f15f2a89 100644 --- a/docs/fundamentals/connection/tls.txt +++ b/docs/fundamentals/connection/tls.txt @@ -9,7 +9,7 @@ Enable and Configure TLS :values: reference .. meta:: - :keywords: code example, security, connection options + :keywords: code example, security, connection options, ssl .. contents:: On this page :local: @@ -23,8 +23,7 @@ Overview In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment. To configure your connection to use TLS, enable the TLS option and provide your certificates for -validation when configuring a connection in your application's -``config/database.php`` file. +validation in your application's ``config/database.php`` file. .. tip:: @@ -38,10 +37,11 @@ In your application's ``config/database.php`` file, you can enable TLS on a connection to your MongoDB deployment in one of the following ways: - Setting the ``tls`` option to ``true`` in your connection string -- Setting the ``tls`` option to ``true`` in the ``options`` property +- Setting the ``tls`` option to ``true`` in the ``options`` property of + your ``mongodb`` connection entry Select from the following :guilabel:`Connection String` and -:guilabel:`URI Options` tabs to see a corresponding code sample: +:guilabel:`Connection Options` tabs to see a corresponding code sample: .. tabs:: @@ -55,13 +55,13 @@ Select from the following :guilabel:`Connection String` and 'mongodb' => [ 'driver' => 'mongodb', - 'dsn' => 'mongodb://:?tls=true', + 'dsn' => 'mongodb://:/?tls=true', 'database' => 'myDB', - ], ... + ] ] - .. tab:: URI Options - :tabid: urioptions tls true + .. tab:: Connection Options + :tabid: options tls true .. code-block:: php :emphasize-lines: 8 @@ -75,9 +75,12 @@ Select from the following :guilabel:`Connection String` and 'options' => [ 'tls' => true, ], - ], ... + ] ] + To view a full list of connection options, see + :ref:`laravel-fundamentals-connection-options`. + .. note:: If your connection string uses a DNS SRV record by including @@ -109,18 +112,25 @@ present to establish a TLS-enabled connection: * - Certificate Authority (CA) - One or more certificate authorities to - trust when making a TLS connection. + trust when making a TLS connection. You can pass this file's path + to the ``tlsCAFile`` option. * - Client Certificate - A digital certificate that allows the server to verify the identity of your application to establish an encrypted network connection. + You can pass this file's path to the ``tlsCertificateKeyFile`` option. * - Certificate Key - The client certificate private key file. This key is often - included within the certificate file itself. + included within the certificate file itself. If you must + provide this item, the certificate and key should be concatenated + in one file that you can pass to the ``tlsCertificateKeyFile`` + option. * - Passphrase - - The password to decrypt the private client key if it is encrypted. + - The password to decrypt the private client key if it is + encrypted. You can pass this file's path to the + ``tlsCertificateKeyFilePassword`` option. Reference Certificates ---------------------- @@ -130,8 +140,8 @@ connection so that the server can validate them before the client connects. We recommend that you reference your certificates and set other TLS options in the ``options`` property of your connection configuration -instead of in the connection string. This improves readability and -flexibility in your application. +instead of in the connection string. This improves code readability in +your application. Set the following options in the ``options`` property to reference your certificates: @@ -139,21 +149,20 @@ certificates: - ``tlsCAFile`` - ``tlsCertificateKeyFile`` - ``tlsCertificateKeyFilePassword`` - -You can specify additional options to configure TLS on your connection. -For **testing purposes**, you can set the -``tlsAllowInvalidCertificates``, ``tlsAllowInvalidHostnames``, or -``tlsInsecure`` fields to ``true``. -.. warning:: +.. note:: + + For **testing purposes**, you can set the following options to + disable validation: - Setting these options to ``true`` disables - certificate and hostname validation. + - ``tlsAllowInvalidCertificates`` + - ``tlsAllowInvalidHostnames`` + - ``tlsInsecure`` - Specifying these options in a production environment makes - your application insecure and potentially - vulnerable to expired certificates and foreign processes posing - as valid client instances. + Specifying these options in a production environment might + your application insecure. To learn more, see the :manual:`Connection + Options ` + reference in the Server manual. The following example configures a connection with TLS enabled: @@ -168,9 +177,10 @@ The following example configures a connection with TLS enabled: 'options' => [ 'tls' => true, 'tlsCAFile' => '', - 'tlsCertificateKeyFile' => '', - ], - ], ... + 'tlsCertificateKeyFile' => '', + 'tlsCertificateKeyFilePassword' => '', + ] + ] ] .. note:: @@ -189,4 +199,4 @@ To learn more about enabling TLS on a connection, see the following Server manual documentation: - :manual:`TLS/SSL (Transport Encryption) ` -- :manual:`TLS/SSL Configuration for Clients ` \ No newline at end of file +- :manual:`TLS/SSL Configuration for Clients ` From a320a482edf5859cf93acad75cecf34cae9c8e75 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 23 Apr 2024 13:44:16 -0400 Subject: [PATCH 4/6] JM tech review --- docs/fundamentals/connection/tls.txt | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/fundamentals/connection/tls.txt b/docs/fundamentals/connection/tls.txt index 1f15f2a89..66c9b6e34 100644 --- a/docs/fundamentals/connection/tls.txt +++ b/docs/fundamentals/connection/tls.txt @@ -159,7 +159,7 @@ certificates: - ``tlsAllowInvalidHostnames`` - ``tlsInsecure`` - Specifying these options in a production environment might + Specifying these options in a production environment might make your application insecure. To learn more, see the :manual:`Connection Options ` reference in the Server manual. @@ -183,18 +183,13 @@ The following example configures a connection with TLS enabled: ] ] -.. note:: - - You can alternatively reference your certificates by setting options - in the ``driverOptions`` property in your connection configuration. - To learn more about these options, see the - `MongoDB\Driver\Manager::__construct() - `__ - API documentation. - Additional Information ---------------------- +To learn more about setting URI options, see the `MongoDB\Driver\Manager::__construct() +`__ +API documentation. + To learn more about enabling TLS on a connection, see the following Server manual documentation: From d9687eddf94e6b2979a7966528a1ffd3203e2d70 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 30 Apr 2024 10:03:50 -0400 Subject: [PATCH 5/6] merge and fix JM tech comments --- docs/fundamentals/connection/tls.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/connection/tls.txt b/docs/fundamentals/connection/tls.txt index 66c9b6e34..697d6613d 100644 --- a/docs/fundamentals/connection/tls.txt +++ b/docs/fundamentals/connection/tls.txt @@ -22,7 +22,7 @@ Overview In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment. To configure your connection to -use TLS, enable the TLS option and provide your certificates for +use TLS, enable the TLS option and optionally provide your certificates for validation in your application's ``config/database.php`` file. .. tip:: @@ -90,7 +90,7 @@ Select from the following :guilabel:`Connection String` and Configure Certificates ---------------------- -To successfully initiate a TLS request, your application must present +To successfully initiate a TLS request, your application might need to present cryptographic certificates to prove its identity. Your application's certificates must be stored as PEM files to enable TLS when connecting. @@ -100,7 +100,7 @@ certificates must be stored as PEM files to enable TLS when connecting. certificates generated and signed by the same certificate authority. For testing, your deployment can use self-signed certificates. -The following list describes the components that your client must +The following list describes the components that your client can present to establish a TLS-enabled connection: .. list-table:: @@ -135,7 +135,7 @@ present to establish a TLS-enabled connection: Reference Certificates ---------------------- -You must reference your certificates when configuring your ``mongodb`` +If required, you must reference your certificates when configuring your ``mongodb`` connection so that the server can validate them before the client connects. We recommend that you reference your certificates and set other TLS From dcffaaab582ea961b29f8bf100d6ebc06d237b03 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 1 May 2024 10:12:24 -0400 Subject: [PATCH 6/6] tlsinsecure clarification --- docs/fundamentals/connection/tls.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/connection/tls.txt b/docs/fundamentals/connection/tls.txt index 697d6613d..793157286 100644 --- a/docs/fundamentals/connection/tls.txt +++ b/docs/fundamentals/connection/tls.txt @@ -153,11 +153,13 @@ certificates: .. note:: For **testing purposes**, you can set the following options to - disable validation: + ``true`` to disable validation: - ``tlsAllowInvalidCertificates`` - ``tlsAllowInvalidHostnames`` - - ``tlsInsecure`` + + Or, you can set the ``tlsInsecure`` option to ``true`` to implicitly set + both of the preceding options. Specifying these options in a production environment might make your application insecure. To learn more, see the :manual:`Connection