diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 551de4696..0003d3e7b 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -126,8 +126,8 @@ To check whether a collection exists, call the ``hasCollection()`` method on the ``Schema`` facade in your migration file. You can use this to perform migration logic conditionally. -The following example migration creates a ``stars`` collection if a collection -named ``telescopes`` exists: +The following example migration creates a ``telescopes`` collection if a collection +named ``stars`` exists: .. literalinclude:: /includes/schema-builder/stars_migration.php :language: php diff --git a/docs/fundamentals/connection.txt b/docs/fundamentals/connection.txt index b9d371c6b..3141cfeaf 100644 --- a/docs/fundamentals/connection.txt +++ b/docs/fundamentals/connection.txt @@ -15,6 +15,7 @@ Connections /fundamentals/connection/connect-to-mongodb /fundamentals/connection/connection-options + /fundamentals/connection/tls .. contents:: On this page :local: @@ -30,3 +31,4 @@ and specify connection behavior in the following sections: - :ref:`laravel-connect-to-mongodb` - :ref:`laravel-fundamentals-connection-options` +- :ref:`laravel-tls` diff --git a/docs/fundamentals/connection/tls.txt b/docs/fundamentals/connection/tls.txt new file mode 100644 index 000000000..793157286 --- /dev/null +++ b/docs/fundamentals/connection/tls.txt @@ -0,0 +1,199 @@ +.. _laravel-tls: + +======================== +Enable and Configure TLS +======================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, security, connection options, ssl + +.. 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 optionally provide your certificates for +validation 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 of + your ``mongodb`` connection entry + +Select from the following :guilabel:`Connection String` and +:guilabel:`Connection 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:: Connection Options + :tabid: options tls true + + .. code-block:: php + :emphasize-lines: 8 + + 'connections' => [ + + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => '', + 'database' => 'myDB', + '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 + the ``mongodb+srv`` prefix, TLS is enabled on your connection by + default. + +Configure Certificates +---------------------- + +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. + +.. 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 can +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. 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. 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. You can pass this file's path to the + ``tlsCertificateKeyFilePassword`` option. + +Reference Certificates +---------------------- + +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 +options in the ``options`` property of your connection configuration +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: + +- ``tlsCAFile`` +- ``tlsCertificateKeyFile`` +- ``tlsCertificateKeyFilePassword`` + +.. note:: + + For **testing purposes**, you can set the following options to + ``true`` to disable validation: + + - ``tlsAllowInvalidCertificates`` + - ``tlsAllowInvalidHostnames`` + + 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 + Options ` + reference in the Server manual. + +The following example configures a connection with TLS enabled: + +.. code-block:: php + + 'connections' => [ + + 'mongodb' => [ + 'driver' => 'mongodb', + 'dsn' => '', + 'database' => 'myDB', + 'options' => [ + 'tls' => true, + 'tlsCAFile' => '', + 'tlsCertificateKeyFile' => '', + 'tlsCertificateKeyFilePassword' => '', + ] + ] + ] + +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: + +- :manual:`TLS/SSL (Transport Encryption) ` +- :manual:`TLS/SSL Configuration for Clients `