Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 6dcf5ea

Browse files
DOCSP-35939: TLS docs (#2894)
1 parent ec0d30f commit 6dcf5ea

File tree

2 files changed

+201
-0
lines changed

2 files changed

+201
-0
lines changed

‎docs/fundamentals/connection.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Connections
1515

1616
/fundamentals/connection/connect-to-mongodb
1717
/fundamentals/connection/connection-options
18+
/fundamentals/connection/tls
1819

1920
.. contents:: On this page
2021
:local:
@@ -30,3 +31,4 @@ and specify connection behavior in the following sections:
3031

3132
- :ref:`laravel-connect-to-mongodb`
3233
- :ref:`laravel-fundamentals-connection-options`
34+
- :ref:`laravel-tls`

‎docs/fundamentals/connection/tls.txt‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
.. _laravel-tls:
2+
3+
========================
4+
Enable and Configure TLS
5+
========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, security, connection options, ssl
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the TLS protocol to secure
24+
your connection to a MongoDB deployment. To configure your connection to
25+
use TLS, enable the TLS option and optionally provide your certificates for
26+
validation in your application's ``config/database.php`` file.
27+
28+
.. tip::
29+
30+
To learn more about TLS, see the Wikipedia entry on
31+
:wikipedia:`Transport Layer Security <w/index.php?title=Transport_Layer_Security&oldid=1184063676>`.
32+
33+
Enable TLS
34+
----------
35+
36+
In your application's ``config/database.php`` file, you can enable TLS
37+
on a connection to your MongoDB deployment in one of the following ways:
38+
39+
- Setting the ``tls`` option to ``true`` in your connection string
40+
- Setting the ``tls`` option to ``true`` in the ``options`` property of
41+
your ``mongodb`` connection entry
42+
43+
Select from the following :guilabel:`Connection String` and
44+
:guilabel:`Connection Options` tabs to see a corresponding code sample:
45+
46+
.. tabs::
47+
48+
.. tab:: Connection String
49+
:tabid: connection string tls true
50+
51+
.. code-block:: php
52+
:emphasize-lines: 5
53+
54+
'connections' => [
55+
56+
'mongodb' => [
57+
'driver' => 'mongodb',
58+
'dsn' => 'mongodb://<hostname>:<port>/?tls=true',
59+
'database' => 'myDB',
60+
]
61+
]
62+
63+
.. tab:: Connection Options
64+
:tabid: options tls true
65+
66+
.. code-block:: php
67+
:emphasize-lines: 8
68+
69+
'connections' => [
70+
71+
'mongodb' => [
72+
'driver' => 'mongodb',
73+
'dsn' => '<connection string>',
74+
'database' => 'myDB',
75+
'options' => [
76+
'tls' => true,
77+
],
78+
]
79+
]
80+
81+
To view a full list of connection options, see
82+
:ref:`laravel-fundamentals-connection-options`.
83+
84+
.. note::
85+
86+
If your connection string uses a DNS SRV record by including
87+
the ``mongodb+srv`` prefix, TLS is enabled on your connection by
88+
default.
89+
90+
Configure Certificates
91+
----------------------
92+
93+
To successfully initiate a TLS request, your application might need to present
94+
cryptographic certificates to prove its identity. Your application's
95+
certificates must be stored as PEM files to enable TLS when connecting.
96+
97+
.. important::
98+
99+
For production use, we recommend that your MongoDB deployment use valid
100+
certificates generated and signed by the same certificate authority.
101+
For testing, your deployment can use self-signed certificates.
102+
103+
The following list describes the components that your client can
104+
present to establish a TLS-enabled connection:
105+
106+
.. list-table::
107+
:header-rows: 1
108+
:widths: 30 70
109+
110+
* - TLS Component
111+
- Description
112+
113+
* - Certificate Authority (CA)
114+
- One or more certificate authorities to
115+
trust when making a TLS connection. You can pass this file's path
116+
to the ``tlsCAFile`` option.
117+
118+
* - Client Certificate
119+
- A digital certificate that allows the server to verify the identity
120+
of your application to establish an encrypted network connection.
121+
You can pass this file's path to the ``tlsCertificateKeyFile`` option.
122+
123+
* - Certificate Key
124+
- The client certificate private key file. This key is often
125+
included within the certificate file itself. If you must
126+
provide this item, the certificate and key should be concatenated
127+
in one file that you can pass to the ``tlsCertificateKeyFile``
128+
option.
129+
130+
* - Passphrase
131+
- The password to decrypt the private client key if it is
132+
encrypted. You can pass this file's path to the
133+
``tlsCertificateKeyFilePassword`` option.
134+
135+
Reference Certificates
136+
----------------------
137+
138+
If required, you must reference your certificates when configuring your ``mongodb``
139+
connection so that the server can validate them before the client connects.
140+
141+
We recommend that you reference your certificates and set other TLS
142+
options in the ``options`` property of your connection configuration
143+
instead of in the connection string. This improves code readability in
144+
your application.
145+
146+
Set the following options in the ``options`` property to reference your
147+
certificates:
148+
149+
- ``tlsCAFile``
150+
- ``tlsCertificateKeyFile``
151+
- ``tlsCertificateKeyFilePassword``
152+
153+
.. note::
154+
155+
For **testing purposes**, you can set the following options to
156+
``true`` to disable validation:
157+
158+
- ``tlsAllowInvalidCertificates``
159+
- ``tlsAllowInvalidHostnames``
160+
161+
Or, you can set the ``tlsInsecure`` option to ``true`` to implicitly set
162+
both of the preceding options.
163+
164+
Specifying these options in a production environment might make
165+
your application insecure. To learn more, see the :manual:`Connection
166+
Options </reference/connection-string/#connection-options>`
167+
reference in the Server manual.
168+
169+
The following example configures a connection with TLS enabled:
170+
171+
.. code-block:: php
172+
173+
'connections' => [
174+
175+
'mongodb' => [
176+
'driver' => 'mongodb',
177+
'dsn' => '<connection string>',
178+
'database' => 'myDB',
179+
'options' => [
180+
'tls' => true,
181+
'tlsCAFile' => '<path to CA certificate>',
182+
'tlsCertificateKeyFile' => '<path to private client certificate>',
183+
'tlsCertificateKeyFilePassword' => '<path to client key passphrase>',
184+
]
185+
]
186+
]
187+
188+
Additional Information
189+
----------------------
190+
191+
To learn more about setting URI options, see the `MongoDB\Driver\Manager::__construct()
192+
<https://www.php.net/manual/en/mongodb-driver-manager.construct.php>`__
193+
API documentation.
194+
195+
To learn more about enabling TLS on a connection, see the
196+
following Server manual documentation:
197+
198+
- :manual:`TLS/SSL (Transport Encryption) </core/security-transport-encryption/>`
199+
- :manual:`TLS/SSL Configuration for Clients </tutorial/configure-ssl-clients/>`

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /