[Summary view]

Differences Between: [Versions 310 and 311] [Versions 39 and 311]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * Contains a class providing functions used to check the allowed/blocked host/ports for curl.
  19   *
  20   * @package   core
  21   * @copyright 2016 Jake Dallimore
  22   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   * @author    Jake Dallimore <jrhdallimore@gmail.com>
  24   */
  25  
  26  namespace core\files;
  27  use core\ip_utils;
  28  
  29  defined('MOODLE_INTERNAL') || exit();
  30  
  31  /**
  32   * Host and port checking for curl.
  33   *
  34   * This class provides a means to check URL/host/port against the system-level cURL security entries.
  35   * It does not provide a means to add URLs, hosts or ports to the allowed/blocked lists; this is configured manually
  36   * via the site admin section of Moodle (See: 'Site admin' > 'Security' > 'HTTP Security').
  37   *
  38   * This class is currently used by the 'curl' wrapper class in lib/filelib.php.
  39   * Depends on:
  40   *  core\ip_utils (several functions)
  41   *  moodlelib (clean_param)
  42   *
  43   * @package   core
  44   * @copyright 2016 Jake Dallimore
  45   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  46   * @author    Jake Dallimore <jrhdallimore@gmail.com>
  47   */
  48  class curl_security_helper extends curl_security_helper_base {
  49      /**
  50       * @var array of supported transport schemes and their respective default ports.
  51       */
  52      protected $transportschemes = [
  53          'http' => 80,
  54          'https' => 443
  55      ];
  56  
  57      /**
  58       * Checks whether the given URL is blocked by checking its address and port number against the allow/block lists.
  59       * The behaviour of this function can be classified as strict, as it returns true for URLs which are invalid or
  60       * could not be parsed, as well as those valid URLs which were found in the blocklist.
  61       *
  62       * @param string $urlstring the URL to check.
  63       * @param int $notused There used to be an optional parameter $maxredirects for a short while here, not used any more.
  64       * @return bool true if the URL is blocked or invalid and false if the URL is not blocked.
  65       */
  66      public function url_is_blocked($urlstring, $notused = null) {
  67  
  68          if ($notused !== null) {
  69              debugging('The $maxredirects parameter of curl_security_helper::url_is_blocked() has been dropped!', DEBUG_DEVELOPER);
  70          }
  71  
  72          // If no config data is present, then all hosts/ports are allowed.
  73          if (!$this->is_enabled()) {
  74              return false;
  75          }
  76  
  77          // Try to parse the URL to get the 'host' and 'port' components.
  78          try {
  79              $url = new \moodle_url($urlstring);
  80              $parsed['scheme'] = $url->get_scheme();
  81              $parsed['host'] = $url->get_host();
  82              $parsed['port'] = $url->get_port();
  83          } catch (\moodle_exception $e) {
  84              // Moodle exception is thrown if the $urlstring is invalid. Treat as blocked.
  85              return true;
  86          }
  87  
  88          // The port will be empty unless explicitly set in the $url (uncommon), so try to infer it from the supported schemes.
  89          if (!$parsed['port'] && $parsed['scheme'] && isset($this->transportschemes[$parsed['scheme']])) {
  90              $parsed['port'] = $this->transportschemes[$parsed['scheme']];
  91          }
  92  
  93          if ($parsed['port'] && $parsed['host']) {
  94              // Check the host and port against the allow/block entries.
  95              return $this->host_is_blocked($parsed['host']) || $this->port_is_blocked($parsed['port']);
  96          }
  97          return true;
  98      }
  99  
 100      /**
 101       * Returns a string message describing a blocked URL. E.g. 'This URL is blocked'.
 102       *
 103       * @return string the string error.
 104       */
 105      public function get_blocked_url_string() {
 106          return get_string('curlsecurityurlblocked', 'admin');
 107      }
 108  
 109      /**
 110       * Checks whether the host portion of a url is blocked.
 111       * The host portion may be a FQDN, IPv4 address or a IPv6 address wrapped in square brackets, as per standard URL notation.
 112       * E.g.
 113       *     images.example.com
 114       *     127.0.0.1
 115       *     [0.0.0.0.0.0.0.1]
 116       * The method logic is as follows:
 117       * 1. Check the host component against the list of IPv4/IPv6 addresses and ranges.
 118       *  - This will perform a DNS forward lookup if required.
 119       * 2. Check the host component against the list of domain names and wildcard domain names.
 120       *  - This will perform a DNS reverse lookup if required.
 121       *
 122       * The behaviour of this function can be classified as strict, as it returns true for hosts which are invalid or
 123       * could not be parsed, as well as those valid URLs which were found in the blocklist.
 124       *
 125       * @param string $host the host component of the URL to check against the blocklist.
 126       * @return bool true if the host is both valid and blocked, false otherwise.
 127       */
 128      protected function host_is_blocked($host) {
 129          if (!$this->is_enabled() || empty($host) || !is_string($host)) {
 130              return false;
 131          }
 132  
 133          // Fix for square brackets in the 'host' portion of the URL (only occurs if an IPv6 address is specified).
 134          $host = str_replace(array('[', ']'), '', $host); // RFC3986, section 3.2.2.
 135          $blockedhosts = $this->get_blocked_hosts_by_category();
 136  
 137          if (ip_utils::is_ip_address($host)) {
 138              if ($this->address_explicitly_blocked($host)) {
 139                  return true;
 140              }
 141  
 142              // Only perform a reverse lookup if there is a point to it (i.e. we have rules to check against).
 143              if ($blockedhosts['domain'] || $blockedhosts['domainwildcard']) {
 144                  // DNS reverse lookup - supports both IPv4 and IPv6 address formats.
 145                  $hostname = gethostbyaddr($host);
 146                  if ($hostname !== $host && $this->host_explicitly_blocked($hostname)) {
 147                      return true;
 148                  }
 149              }
 150          } else if (ip_utils::is_domain_name($host)) {
 151              if ($this->host_explicitly_blocked($host)) {
 152                  return true;
 153              }
 154  
 155              // Only perform a forward lookup if there are IP rules to check against.
 156              if ($blockedhosts['ipv4'] || $blockedhosts['ipv6']) {
 157                  // DNS forward lookup - returns a list of only IPv4 addresses!
 158                  $hostips = $this->get_host_list_by_name($host);
 159  
 160                  // If we don't get a valid record, bail (so cURL is never called).
 161                  if (!$hostips) {
 162                      return true;
 163                  }
 164  
 165                  // If any of the returned IPs are in the blocklist, block the request.
 166                  foreach ($hostips as $hostip) {
 167                      if ($this->address_explicitly_blocked($hostip)) {
 168                          return true;
 169                      }
 170                  }
 171              }
 172          } else {
 173              // Was not something we consider to be a valid IP or domain name, block it.
 174              return true;
 175          }
 176  
 177          return false;
 178      }
 179  
 180      /**
 181       * Retrieve all hosts for a domain name.
 182       *
 183       * @param string $param
 184       * @return array An array of IPs associated with the host name.
 185       */
 186      protected function get_host_list_by_name($host) {
 187          return ($hostips = gethostbynamel($host)) ? $hostips : [];
 188      }
 189  
 190      /**
 191       * Checks whether the given port is blocked, as determined by its absence on the ports allowlist.
 192       * Ports are assumed to be blocked unless found in the allowlist.
 193       *
 194       * @param integer|string $port the port to check against the ports allowlist.
 195       * @return bool true if the port is blocked, false otherwise.
 196       */
 197      protected function port_is_blocked($port) {
 198          $portnum = intval($port);
 199          // Intentionally block port 0 and below and check the int cast was valid.
 200          if (empty($port) || (string)$portnum !== (string)$port || $port < 0) {
 201              return true;
 202          }
 203          $allowedports = $this->get_allowed_ports();
 204          return !empty($allowedports) && !in_array($portnum, $allowedports);
 205      }
 206  
 207      /**
 208       * Convenience method to check whether we have any entries in the host blocklist or ports allowlist admin settings.
 209       * If no entries are found at all, the assumption is that the blocklist is disabled entirely.
 210       *
 211       * @return bool true if one or more entries exist, false otherwise.
 212       */
 213      public function is_enabled() {
 214          return (!empty($this->get_allowed_ports()) || !empty($this->get_blocked_hosts()));
 215      }
 216  
 217      /**
 218       * Checks whether the input address is blocked by at any of the IPv4 or IPv6 address rules.
 219       *
 220       * @param string $addr the ip address to check.
 221       * @return bool true if the address is covered by an entry in the blocklist, false otherwise.
 222       */
 223      protected function address_explicitly_blocked($addr) {
 224          $blockedhosts = $this->get_blocked_hosts_by_category();
 225          $iphostsblocked = array_merge($blockedhosts['ipv4'], $blockedhosts['ipv6']);
 226          return address_in_subnet($addr, implode(',', $iphostsblocked), true);
 227      }
 228  
 229      /**
 230       * Checks whether the input hostname is blocked by any of the domain/wildcard rules.
 231       *
 232       * @param string $host the hostname to check
 233       * @return bool true if the host is covered by an entry in the blocklist, false otherwise.
 234       */
 235      protected function host_explicitly_blocked($host) {
 236          $blockedhosts = $this->get_blocked_hosts_by_category();
 237          $domainhostsblocked = array_merge($blockedhosts['domain'], $blockedhosts['domainwildcard']);
 238          return ip_utils::is_domain_in_allowed_list($host, $domainhostsblocked);
 239      }
 240  
 241      /**
 242       * Helper to get all entries from the admin setting, as an array, sorted by classification.
 243       * Classifications include 'ipv4', 'ipv6', 'domain', 'domainwildcard'.
 244       *
 245       * @return array of host/domain/ip entries from the 'curlsecurityblockedhosts' config.
 246       */
 247      protected function get_blocked_hosts_by_category() {
 248          // For each of the admin setting entries, check and place in the correct section of the config array.
 249          $config = ['ipv6' => [], 'ipv4' => [], 'domain' => [], 'domainwildcard' => []];
 250          $entries = $this->get_blocked_hosts();
 251          foreach ($entries as $entry) {
 252              if (ip_utils::is_ipv6_address($entry) || ip_utils::is_ipv6_range($entry)) {
 253                  $config['ipv6'][] = $entry;
 254              } else if (ip_utils::is_ipv4_address($entry) || ip_utils::is_ipv4_range($entry)) {
 255                  $config['ipv4'][] = $entry;
 256              } else if (ip_utils::is_domain_name($entry)) {
 257                  $config['domain'][] = $entry;
 258              } else if (ip_utils::is_domain_matching_pattern($entry)) {
 259                  $config['domainwildcard'][] = $entry;
 260              }
 261          }
 262          return $config;
 263      }
 264  
 265      /**
 266       * Helper that returns the allowed ports, as defined in the 'curlsecurityallowedport' setting.
 267       *
 268       * @return array the array of allowed ports.
 269       */
 270      protected function get_allowed_ports() {
 271          global $CFG;
 272          if (!isset($CFG->curlsecurityallowedport)) {
 273              return [];
 274          }
 275          return array_filter(array_map('trim', explode("\n", $CFG->curlsecurityallowedport)), function($entry) {
 276              return !empty($entry);
 277          });
 278      }
 279  
 280      /**
 281       * Helper that returns the blocked hosts, as defined in the 'curlsecurityblockedhosts' setting.
 282       *
 283       * @return array the array of blocked host entries.
 284       */
 285      protected function get_blocked_hosts() {
 286          global $CFG;
 287          if (!isset($CFG->curlsecurityblockedhosts)) {
 288              return [];
 289          }
 290          return array_filter(array_map('trim', explode("\n", $CFG->curlsecurityblockedhosts)), function($entry) {
 291              return !empty($entry);
 292          });
 293      }
 294  }