Updated trusted_hosts documentation with #3876

Author: wouterj

reference/configuration/framework.rst

@@ -249,33 +249,81 @@ used. It becomes the service container parameter called
 trusted_hosts
 ~~~~~~~~~~~~~
 
-**type**: ``array`` | ``string``
+**type**: ``array`` | ``string`` **default**: ``array()``
 
-To prevent `HTTP Host header attacks`_, you need to configure a list of trusted
-hosts. This is an array of regexes (or a single regex) which define the trusted
-hosts.
+A lot of different attacks have been discovered relying on inconsistencies
+between the handling of the ``Host`` header by various software (web servers,
+reverse proxies, web frameworks, etc.). Basically, everytime the framework is
+generating an absolute URL (when sending an email to reset a password for
+instance), the host might have been manipulated by an attacker.
+
+.. seealso::
+
+    You can read "`HTTP Host header attacks`_" for more information about these
+    kinds of attacks.
+
+The Symfony :method:`Request::getHost()
+<Symfony\\Component\\HttpFoundation\\Request:getHost>` method might be
+vulnerable to some of these attacks because it depends on the configuration of
+your web server. One simple solution to avoid these attacks is to whitelist the
+hosts that your Symfony application can respond to. That's the purpose of this
+``trusted_hosts`` option. If the incoming request's hostname doesn't match one
+in this list, the application won't respond and the user will receive a 500
+response.
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         framework:
-            trusted_hosts: '(^|\.)trusted\.com$'
+            trusted_hosts:  ['acme.com', 'acme.org']
 
     .. code-block:: xml
 
         <framework:config>
-            <trusted-host>(^|\.)trusted\.com$</trusted-host>
-        </framework:config>
+            <trusted-host>acme.com</trusted-host>
+            <trusted-host>acme.org</trusted-host>
+            <!-- ... -->
+        </framework>
 
     .. code-block:: php
 
         $container->loadFromExtension('framework', array(
-            'trusted_hosts' => '(^|\.)trusted\.com$',
+            'trusted_hosts' => array('acme.com', 'acme.org'),
         ));
 
-The above configuration allows for the ``trusted.com`` host (and all its
-subdomains).
+Hosts can also be configured using regular expressions, which make it easier to
+respond to any subdomain:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        framework:
+            trusted_hosts:  ['.*\.?acme.com$', '.*\.?acme.org$']
+
+    .. code-block:: xml
+
+        <framework:config>
+            <trusted-host>.*\.?acme.com$</trusted-host>
+            <trusted-host>.*\.?acme.org$</trusted-host>
+            <!-- ... -->
+        </framework>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('framework', array(
+            'trusted_hosts' => array('.*\.?acme.com$', '.*\.?acme.org$'),
+        ));
+
+In addition, you can also set the trusted hosts in the front controller using
+the ``Request::setTrustedHosts()`` method::
+
+    // web/app.php
+    Request::setTrustedHosts(array('.*\.?acme.com$', '.*\.?acme.org$'));
+
+The default value for this option is an empty array, meaning that the application
+can respond to any given host.
 
 .. seealso::