MDL-65074 mod_quiz: Quiz navigation buttons shouldnt use btn-secondary
[moodle.git] / lib / classes / files / curl_security_helper.php
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/>.
17 /**
18  * Contains a class providing functions used to check the host/port black/whitelists 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  */
26 namespace core\files;
27 use core\ip_utils;
29 defined('MOODLE_INTERNAL') || exit();
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 black/white 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     ];
57     /**
58      * Checks whether the given URL is blacklisted by checking its address and port number against the black/white 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 blacklist.
61      *
62      * @param string $urlstring the URL to check.
63      * @return bool true if the URL is blacklisted or invalid and false if the URL is not blacklisted.
64      */
65     public function url_is_blocked($urlstring) {
66         // If no config data is present, then all hosts/ports are allowed.
67         if (!$this->is_enabled()) {
68             return false;
69         }
71         // Try to parse the URL to get the 'host' and 'port' components.
72         try {
73             $url = new \moodle_url($urlstring);
74             $parsed['scheme'] = $url->get_scheme();
75             $parsed['host'] = $url->get_host();
76             $parsed['port'] = $url->get_port();
77         } catch (\moodle_exception $e) {
78             // Moodle exception is thrown if the $urlstring is invalid. Treat as blocked.
79             return true;
80         }
82         // The port will be empty unless explicitly set in the $url (uncommon), so try to infer it from the supported schemes.
83         if (!$parsed['port'] && $parsed['scheme'] && isset($this->transportschemes[$parsed['scheme']])) {
84             $parsed['port'] = $this->transportschemes[$parsed['scheme']];
85         }
87         if ($parsed['port'] && $parsed['host']) {
88             // Check the host and port against the blacklist/whitelist entries.
89             return $this->host_is_blocked($parsed['host']) || $this->port_is_blocked($parsed['port']);
90         }
91         return true;
92     }
94     /**
95      * Returns a string message describing a blocked URL. E.g. 'This URL is blocked'.
96      *
97      * @return string the string error.
98      */
99     public function get_blocked_url_string() {
100         return get_string('curlsecurityurlblocked', 'admin');
101     }
103     /**
104      * Checks whether the host portion of a url is blocked.
105      * The host portion may be a FQDN, IPv4 address or a IPv6 address wrapped in square brackets, as per standard URL notation.
106      * E.g.
107      *     images.example.com
108      *     127.0.0.1
109      *     [0.0.0.0.0.0.0.1]
110      * The method logic is as follows:
111      * 1. Check the host component against the list of IPv4/IPv6 addresses and ranges.
112      *  - This will perform a DNS forward lookup if required.
113      * 2. Check the host component against the list of domain names and wildcard domain names.
114      *  - This will perform a DNS reverse lookup if required.
115      *
116      * The behaviour of this function can be classified as strict, as it returns true for hosts which are invalid or
117      * could not be parsed, as well as those valid URLs which were found in the blacklist.
118      *
119      * @param string $host the host component of the URL to check against the blacklist.
120      * @return bool true if the host is both valid and blocked, false otherwise.
121      */
122     protected function host_is_blocked($host) {
123         if (!$this->is_enabled() || empty($host) || !is_string($host)) {
124             return false;
125         }
127         // Fix for square brackets in the 'host' portion of the URL (only occurs if an IPv6 address is specified).
128         $host = str_replace(array('[', ']'), '', $host); // RFC3986, section 3.2.2.
129         $blacklistedhosts = $this->get_blacklisted_hosts_by_category();
131         if (ip_utils::is_ip_address($host)) {
132             if ($this->address_explicitly_blocked($host)) {
133                 return true;
134             }
136             // Only perform a reverse lookup if there is a point to it (i.e. we have rules to check against).
137             if ($blacklistedhosts['domain'] || $blacklistedhosts['domainwildcard']) {
138                 // DNS reverse lookup - supports both IPv4 and IPv6 address formats.
139                 $hostname = gethostbyaddr($host);
140                 if ($hostname !== $host && $this->host_explicitly_blocked($hostname)) {
141                     return true;
142                 }
143             }
144         } else if (ip_utils::is_domain_name($host)) {
145             if ($this->host_explicitly_blocked($host)) {
146                 return true;
147             }
149             // Only perform a forward lookup if there are IP rules to check against.
150             if ($blacklistedhosts['ipv4'] || $blacklistedhosts['ipv6']) {
151                 // DNS forward lookup - returns a list of only IPv4 addresses!
152                 $hostips = $this->get_host_list_by_name($host);
154                 // If we don't get a valid record, bail (so cURL is never called).
155                 if (!$hostips) {
156                     return true;
157                 }
159                 // If any of the returned IPs are in the blacklist, block the request.
160                 foreach ($hostips as $hostip) {
161                     if ($this->address_explicitly_blocked($hostip)) {
162                         return true;
163                     }
164                 }
165             }
166         } else {
167             // Was not something we consider to be a valid IP or domain name, block it.
168             return true;
169         }
171         return false;
172     }
174     /**
175      * Retrieve all hosts for a domain name.
176      *
177      * @param string $param
178      * @return array An array of IPs associated with the host name.
179      */
180     protected function get_host_list_by_name($host) {
181         return ($hostips = gethostbynamel($host)) ? $hostips : [];
182     }
184     /**
185      * Checks whether the given port is blocked, as determined by its absence on the ports whitelist.
186      * Ports are assumed to be blocked unless found in the whitelist.
187      *
188      * @param integer|string $port the port to check against the ports whitelist.
189      * @return bool true if the port is blocked, false otherwise.
190      */
191     protected function port_is_blocked($port) {
192         $portnum = intval($port);
193         // Intentionally block port 0 and below and check the int cast was valid.
194         if (empty($port) || (string)$portnum !== (string)$port || $port < 0) {
195             return true;
196         }
197         $allowedports = $this->get_whitelisted_ports();
198         return !empty($allowedports) && !in_array($portnum, $allowedports);
199     }
201     /**
202      * Convenience method to check whether we have any entries in the host blacklist or ports whitelist admin settings.
203      * If no entries are found at all, the assumption is that the blacklist is disabled entirely.
204      *
205      * @return bool true if one or more entries exist, false otherwise.
206      */
207     public function is_enabled() {
208         return (!empty($this->get_whitelisted_ports()) || !empty($this->get_blacklisted_hosts()));
209     }
211     /**
212      * Checks whether the input address is blocked by at any of the IPv4 or IPv6 address rules.
213      *
214      * @param string $addr the ip address to check.
215      * @return bool true if the address is covered by an entry in the blacklist, false otherwise.
216      */
217     protected function address_explicitly_blocked($addr) {
218         $blockedhosts = $this->get_blacklisted_hosts_by_category();
219         $iphostsblocked = array_merge($blockedhosts['ipv4'], $blockedhosts['ipv6']);
220         return address_in_subnet($addr, implode(',', $iphostsblocked));
221     }
223     /**
224      * Checks whether the input hostname is blocked by any of the domain/wildcard rules.
225      *
226      * @param string $host the hostname to check
227      * @return bool true if the host is covered by an entry in the blacklist, false otherwise.
228      */
229     protected function host_explicitly_blocked($host) {
230         $blockedhosts = $this->get_blacklisted_hosts_by_category();
231         $domainhostsblocked = array_merge($blockedhosts['domain'], $blockedhosts['domainwildcard']);
232         return ip_utils::is_domain_in_allowed_list($host, $domainhostsblocked);
233     }
235     /**
236      * Helper to get all entries from the admin setting, as an array, sorted by classification.
237      * Classifications include 'ipv4', 'ipv6', 'domain', 'domainwildcard'.
238      *
239      * @return array of host/domain/ip entries from the 'curlsecurityblockedhosts' config.
240      */
241     protected function get_blacklisted_hosts_by_category() {
242         // For each of the admin setting entries, check and place in the correct section of the config array.
243         $config = ['ipv6' => [], 'ipv4' => [], 'domain' => [], 'domainwildcard' => []];
244         $entries = $this->get_blacklisted_hosts();
245         foreach ($entries as $entry) {
246             if (ip_utils::is_ipv6_address($entry) || ip_utils::is_ipv6_range($entry)) {
247                 $config['ipv6'][] = $entry;
248             } else if (ip_utils::is_ipv4_address($entry) || ip_utils::is_ipv4_range($entry)) {
249                 $config['ipv4'][] = $entry;
250             } else if (ip_utils::is_domain_name($entry)) {
251                 $config['domain'][] = $entry;
252             } else if (ip_utils::is_domain_matching_pattern($entry)) {
253                 $config['domainwildcard'][] = $entry;
254             }
255         }
256         return $config;
257     }
259     /**
260      * Helper that returns the whitelisted ports, as defined in the 'curlsecurityallowedport' setting.
261      *
262      * @return array the array of whitelisted ports.
263      */
264     protected function get_whitelisted_ports() {
265         global $CFG;
266         if (!isset($CFG->curlsecurityallowedport)) {
267             return [];
268         }
269         return array_filter(array_map('trim', explode("\n", $CFG->curlsecurityallowedport)), function($entry) {
270             return !empty($entry);
271         });
272     }
274     /**
275      * Helper that returns the blacklisted hosts, as defined in the 'curlsecurityblockedhosts' setting.
276      *
277      * @return array the array of blacklisted host entries.
278      */
279     protected function get_blacklisted_hosts() {
280         global $CFG;
281         if (!isset($CFG->curlsecurityblockedhosts)) {
282             return [];
283         }
284         return array_filter(array_map('trim', explode("\n", $CFG->curlsecurityblockedhosts)), function($entry) {
285             return !empty($entry);
286         });
287     }