Adding a small document on the changes related to trusting proxy data

Author: weaverryan

components/http_foundation/index.rst

@@ -5,3 +5,4 @@ HTTP Foundation
     :maxdepth: 2
 
     introduction
+    trusting_proxies

components/http_foundation/trusting_proxies.rst

@@ -0,0 +1,49 @@
+.. index::
+   single: Request; Trusted Proxies
+
+Trusting Proxies
+================
+
+If you find yourself behind some sort of proxy - like a load balancer - then
+certain header information may be sent to you using special ``X-Forwarded-*``
+headers. For example, the ``Host`` HTTP header is usually used to return
+the requested host. But when you're behind a proxy, the true host may be
+stored in a ``X-Forwarded-Host`` header.
+
+Since HTTP headers can be spoofed, Symfony2 does *not* trust these proxy
+headers by default. If you are behind a proxy, you should manually whitelist
+your proxy::
+
+    use Symfony\Component\HttpFoundation\Request;
+
+    $request = Request::createFromGlobals();
+    // only trust proxy headers coming from this IP address
+    $request->setTrustedProxies(array(192.0.0.1));
+
+Configuring Header Names
+------------------------
+
+By default, the following proxy headers are trusted:
+
+* ``X-Forwarded-For`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
+* ``X-Forwarded-Host`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getHost`;
+* ``X-Forwarded-Port`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getPort`;
+* ``X-Forwarded-Proto`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getScheme` and :method:`Symfony\\Component\\HttpFoundation\\Request::isSecure`;
+
+If your reverse proxy uses a different header name for any of these, you
+can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\Request::setTrustedHeaderName`::
+
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_IP, 'X-Proxy-For');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, 'X-Proxy-Proto');
+
+Not trusting certain Headers
+----------------------------
+
+By default, if you whitelist your proxy's IP address, then all four headers
+listed above are trusted. If you need to trust some of these headers but
+not others, you can do that as well::
+
+    // disables trusting the ``X-Forwarded-Proto`` header, the default header is used
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, '');

components/map.rst.inc

@@ -49,6 +49,7 @@
 * :doc:`/components/http_foundation/index`
 
   * :doc:`/components/http_foundation/introduction`
+  * :doc:`/components/http_foundation/trusting_proxies`
 
 * :doc:`/components/http_kernel/index`
 

reference/configuration/framework.rst

@@ -91,9 +91,30 @@ services related to testing your application (e.g. ``test.client``) are loaded.
 This setting should be present in your ``test`` environment (usually via
 ``app/config/config_test.yml``). For more information, see :doc:`/book/testing`.
 
+trusted_proxies
+~~~~~~~~~~~~~~~
+
+**type**: ``array``
+
+Configures the IP addresses that should be trusted as proxies. For more details,
+see :doc:`/components/http_foundation/trusting_proxies`.
+
+.. code-block:: yaml
+
+    framework:
+        trusted_proxies:  [192.0.0.1]
+
 trust_proxy_headers
 ~~~~~~~~~~~~~~~~~~~
 
+.. caution::
+
+    The ``trust_proxy_headers`` option is deprecated and will be removed in
+    Symfony 2.3. See `trusted_proxies`_ and :doc:`/components/http_foundation/trusting_proxies`
+    for details on how to properly trust proxy data.
+
+**Deprecated**: This option will be removed in Symfony 2.3. Instead, use
+
 **type**: ``Boolean``
 
 Configures if HTTP headers (like ``HTTP_X_FORWARDED_FOR``, ``X_FORWARDED_PROTO``, and