2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Contains a class providing functions used to check the host/port black/whitelists for curl.
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>
29 defined('MOODLE_INTERNAL') ||
exit();
32 * Host and port checking for curl.
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').
38 * This class is currently used by the 'curl' wrapper class in lib/filelib.php.
40 * core\ip_utils (several functions)
41 * moodlelib (clean_param)
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>
48 class curl_security_helper
extends curl_security_helper_base
{
50 * @var array of supported transport schemes and their respective default ports.
52 protected $transportschemes = [
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.
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.
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()) {
71 // Try to parse the URL to get the 'host' and 'port' components.
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.
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']];
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']);
95 * Returns a string message describing a blocked URL. E.g. 'This URL is blocked'.
97 * @return string the string error.
99 public function get_blocked_url_string() {
100 return get_string('curlsecurityurlblocked', 'admin');
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.
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.
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.
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.
122 protected function host_is_blocked($host) {
123 if (!$this->is_enabled() ||
empty($host) ||
!is_string($host)) {
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)) {
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)) {
144 } else if (ip_utils
::is_domain_name($host)) {
145 if ($this->host_explicitly_blocked($host)) {
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).
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)) {
167 // Was not something we consider to be a valid IP or domain name, block it.
175 * Retrieve all hosts for a domain name.
177 * @param string $param
178 * @return array An array of IPs associated with the host name.
180 protected function get_host_list_by_name($host) {
181 return ($hostips = gethostbynamel($host)) ?
$hostips : [];
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.
188 * @param integer|string $port the port to check against the ports whitelist.
189 * @return bool true if the port is blocked, false otherwise.
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) {
197 $allowedports = $this->get_whitelisted_ports();
198 return !empty($allowedports) && !in_array($portnum, $allowedports);
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.
205 * @return bool true if one or more entries exist, false otherwise.
207 public function is_enabled() {
208 return (!empty($this->get_whitelisted_ports()) ||
!empty($this->get_blacklisted_hosts()));
212 * Checks whether the input address is blocked by at any of the IPv4 or IPv6 address rules.
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.
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));
224 * Checks whether the input hostname is blocked by any of the domain/wildcard rules.
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.
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);
236 * Helper to get all entries from the admin setting, as an array, sorted by classification.
237 * Classifications include 'ipv4', 'ipv6', 'domain', 'domainwildcard'.
239 * @return array of host/domain/ip entries from the 'curlsecurityblockedhosts' config.
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;
260 * Helper that returns the whitelisted ports, as defined in the 'curlsecurityallowedport' setting.
262 * @return array the array of whitelisted ports.
264 protected function get_whitelisted_ports() {
266 if (!isset($CFG->curlsecurityallowedport
)) {
269 return array_filter(array_map('trim', explode("\n", $CFG->curlsecurityallowedport
)), function($entry) {
270 return !empty($entry);
275 * Helper that returns the blacklisted hosts, as defined in the 'curlsecurityblockedhosts' setting.
277 * @return array the array of blacklisted host entries.
279 protected function get_blacklisted_hosts() {
281 if (!isset($CFG->curlsecurityblockedhosts
)) {
284 return array_filter(array_map('trim', explode("\n", $CFG->curlsecurityblockedhosts
)), function($entry) {
285 return !empty($entry);