Added documentation about Host header attack (yiisoft#13073)

* Added documentation about Host header attack

Added info about Host header attack (yiisoft#13050) to the guide and the Request class.
When we introduce a filter or property to protect against this, these
sections should be updated to link to that option.

docs/guide/security-best-practices.md

@@ -221,3 +221,25 @@ provided by H5BP project:
 - [Apache](https://github.com/h5bp/server-configs-apache).
 - [IIS](https://github.com/h5bp/server-configs-iis).
 - [Lighttpd](https://github.com/h5bp/server-configs-lighttpd).
+
+Secure Server configuration
+---------------------------
+
+The purpose of this section is to highlight risks that need to be considered when creating a
+server configuration for serving a Yii based website. Besides the points covered here there may
+be other security related configuration options to be considered, so do not consider this section to
+be complete.
+
+### Avoiding `Host`-header attacks
+
+Classes like [[yii\web\UrlManager]] and [[yii\helpers\Url]] may use the [[yii\web\Request::getHostInfo()|currently requested host name]]
+for generating links.
+If the webserver is configured to serve the same site independent of the value of the `Host` header, this information may not be reliable
+and [may be faked by the user sending the HTTP request](https://www.acunetix.com/vulnerabilities/web/host-header-attack).
+In such situations you should either fix your webserver configuration to serve the site only for specified host names
+or explicitly set or filter the value by setting the [[yii\web\Request::setHostInfo()|hostInfo]] property of the `request` application component.
+
+For more information about the server configuration, please refer to the documentation of your webserver:
+
+- Apache 2: <http://httpd.apache.org/docs/trunk/vhosts/examples.html#defaultallports>
+- Nginx: <https://www.nginx.com/resources/wiki/start/topics/examples/server_blocks/>

framework/web/Request.php

@@ -529,9 +529,25 @@ public function getQueryParam($name, $defaultValue = null)
 
     /**
      * Returns the schema and host part of the current request URL.
+     *
      * The returned URL does not have an ending slash.
-     * By default this is determined based on the user request information.
+     *
+     * By default this value is based on the user request information. This method will
+     * return the value of `$_SERVER['HTTP_HOST']` if it is available or `$_SERVER['SERVER_NAME']` if not.
+     * You may want to check out the [PHP documentation](http://php.net/manual/en/reserved.variables.server.php)
+     * for more information on these variables.
+     *
      * You may explicitly specify it by setting the [[setHostInfo()|hostInfo]] property.
+     *
+     * > Warning: Dependent on the server configuration this information may not be
+     * > reliable and [may be faked by the user sending the HTTP request](https://www.acunetix.com/vulnerabilities/web/host-header-attack).
+     * > If the webserver is configured to serve the same site independent of the value of
+     * > the `Host` header, this value is not reliable. In such situations you should either
+     * > fix your webserver configuration or explicitly set the value by setting the [[setHostInfo()|hostInfo]] property.
+     *
+     * @property string|null schema and hostname part (with port number if needed) of the request URL
+     * (e.g. `http://www.yiiframework.com`), null if can't be obtained from `$_SERVER` and wasn't set.
+     * See [[getHostInfo()]] for security related notes on this property.
      * @return string|null schema and hostname part (with port number if needed) of the request URL
      * (e.g. `http://www.yiiframework.com`), null if can't be obtained from `$_SERVER` and wasn't set.
      * @see setHostInfo()
@@ -560,6 +576,7 @@ public function getHostInfo()
      * This setter is provided in case the schema and hostname cannot be determined
      * on certain Web servers.
      * @param string|null $value the schema and host part of the application URL. The trailing slashes will be removed.
+     * @see getHostInfo() for security related notes on this property.
      */
     public function setHostInfo($value)
     {