[Summary view]

   1  <?php
   2  
   3  /**
   4   * HTML Purifier's internal representation of a URI.
   5   * @note
   6   *      Internal data-structures are completely escaped. If the data needs
   7   *      to be used in a non-URI context (which is very unlikely), be sure
   8   *      to decode it first. The URI may not necessarily be well-formed until
   9   *      validate() is called.
  10   */
  11  class HTMLPurifier_URI
  12  {
  13      /**
  14       * @type string
  15       */
  16      public $scheme;
  17  
  18      /**
  19       * @type string
  20       */
  21      public $userinfo;
  22  
  23      /**
  24       * @type string
  25       */
  26      public $host;
  27  
  28      /**
  29       * @type int
  30       */
  31      public $port;
  32  
  33      /**
  34       * @type string
  35       */
  36      public $path;
  37  
  38      /**
  39       * @type string
  40       */
  41      public $query;
  42  
  43      /**
  44       * @type string
  45       */
  46      public $fragment;
  47  
  48      /**
  49       * @param string $scheme
  50       * @param string $userinfo
  51       * @param string $host
  52       * @param int $port
  53       * @param string $path
  54       * @param string $query
  55       * @param string $fragment
  56       * @note Automatically normalizes scheme and port
  57       */
  58      public function __construct($scheme, $userinfo, $host, $port, $path, $query, $fragment)
  59      {
  60          $this->scheme = is_null($scheme) || ctype_lower($scheme) ? $scheme : strtolower($scheme);
  61          $this->userinfo = $userinfo;
  62          $this->host = $host;
  63          $this->port = is_null($port) ? $port : (int)$port;
  64          $this->path = $path;
  65          $this->query = $query;
  66          $this->fragment = $fragment;
  67      }
  68  
  69      /**
  70       * Retrieves a scheme object corresponding to the URI's scheme/default
  71       * @param HTMLPurifier_Config $config
  72       * @param HTMLPurifier_Context $context
  73       * @return HTMLPurifier_URIScheme Scheme object appropriate for validating this URI
  74       */
  75      public function getSchemeObj($config, $context)
  76      {
  77          $registry = HTMLPurifier_URISchemeRegistry::instance();
  78          if ($this->scheme !== null) {
  79              $scheme_obj = $registry->getScheme($this->scheme, $config, $context);
  80              if (!$scheme_obj) {
  81                  return false;
  82              } // invalid scheme, clean it out
  83          } else {
  84              // no scheme: retrieve the default one
  85              $def = $config->getDefinition('URI');
  86              $scheme_obj = $def->getDefaultScheme($config, $context);
  87              if (!$scheme_obj) {
  88                  if ($def->defaultScheme !== null) {
  89                      // something funky happened to the default scheme object
  90                      trigger_error(
  91                          'Default scheme object "' . $def->defaultScheme . '" was not readable',
  92                          E_USER_WARNING
  93                      );
  94                  } // suppress error if it's null
  95                  return false;
  96              }
  97          }
  98          return $scheme_obj;
  99      }
 100  
 101      /**
 102       * Generic validation method applicable for all schemes. May modify
 103       * this URI in order to get it into a compliant form.
 104       * @param HTMLPurifier_Config $config
 105       * @param HTMLPurifier_Context $context
 106       * @return bool True if validation/filtering succeeds, false if failure
 107       */
 108      public function validate($config, $context)
 109      {
 110          // ABNF definitions from RFC 3986
 111          $chars_sub_delims = '!$&\'()*+,;=';
 112          $chars_gen_delims = ':/?#[]@';
 113          $chars_pchar = $chars_sub_delims . ':@';
 114  
 115          // validate host
 116          if (!is_null($this->host)) {
 117              $host_def = new HTMLPurifier_AttrDef_URI_Host();
 118              $this->host = $host_def->validate($this->host, $config, $context);
 119              if ($this->host === false) {
 120                  $this->host = null;
 121              }
 122          }
 123  
 124          // validate scheme
 125          // NOTE: It's not appropriate to check whether or not this
 126          // scheme is in our registry, since a URIFilter may convert a
 127          // URI that we don't allow into one we do.  So instead, we just
 128          // check if the scheme can be dropped because there is no host
 129          // and it is our default scheme.
 130          if (!is_null($this->scheme) && is_null($this->host) || $this->host === '') {
 131              // support for relative paths is pretty abysmal when the
 132              // scheme is present, so axe it when possible
 133              $def = $config->getDefinition('URI');
 134              if ($def->defaultScheme === $this->scheme) {
 135                  $this->scheme = null;
 136              }
 137          }
 138  
 139          // validate username
 140          if (!is_null($this->userinfo)) {
 141              $encoder = new HTMLPurifier_PercentEncoder($chars_sub_delims . ':');
 142              $this->userinfo = $encoder->encode($this->userinfo);
 143          }
 144  
 145          // validate port
 146          if (!is_null($this->port)) {
 147              if ($this->port < 1 || $this->port > 65535) {
 148                  $this->port = null;
 149              }
 150          }
 151  
 152          // validate path
 153          $segments_encoder = new HTMLPurifier_PercentEncoder($chars_pchar . '/');
 154          if (!is_null($this->host)) { // this catches $this->host === ''
 155              // path-abempty (hier and relative)
 156              // http://www.example.com/my/path
 157              // //www.example.com/my/path (looks odd, but works, and
 158              //                            recognized by most browsers)
 159              // (this set is valid or invalid on a scheme by scheme
 160              // basis, so we'll deal with it later)
 161              // file:///my/path
 162              // ///my/path
 163              $this->path = $segments_encoder->encode($this->path);
 164          } elseif ($this->path !== '') {
 165              if ($this->path[0] === '/') {
 166                  // path-absolute (hier and relative)
 167                  // http:/my/path
 168                  // /my/path
 169                  if (strlen($this->path) >= 2 && $this->path[1] === '/') {
 170                      // This could happen if both the host gets stripped
 171                      // out
 172                      // http://my/path
 173                      // //my/path
 174                      $this->path = '';
 175                  } else {
 176                      $this->path = $segments_encoder->encode($this->path);
 177                  }
 178              } elseif (!is_null($this->scheme)) {
 179                  // path-rootless (hier)
 180                  // http:my/path
 181                  // Short circuit evaluation means we don't need to check nz
 182                  $this->path = $segments_encoder->encode($this->path);
 183              } else {
 184                  // path-noscheme (relative)
 185                  // my/path
 186                  // (once again, not checking nz)
 187                  $segment_nc_encoder = new HTMLPurifier_PercentEncoder($chars_sub_delims . '@');
 188                  $c = strpos($this->path, '/');
 189                  if ($c !== false) {
 190                      $this->path =
 191                          $segment_nc_encoder->encode(substr($this->path, 0, $c)) .
 192                          $segments_encoder->encode(substr($this->path, $c));
 193                  } else {
 194                      $this->path = $segment_nc_encoder->encode($this->path);
 195                  }
 196              }
 197          } else {
 198              // path-empty (hier and relative)
 199              $this->path = ''; // just to be safe
 200          }
 201  
 202          // qf = query and fragment
 203          $qf_encoder = new HTMLPurifier_PercentEncoder($chars_pchar . '/?');
 204  
 205          if (!is_null($this->query)) {
 206              $this->query = $qf_encoder->encode($this->query);
 207          }
 208  
 209          if (!is_null($this->fragment)) {
 210              $this->fragment = $qf_encoder->encode($this->fragment);
 211          }
 212          return true;
 213      }
 214  
 215      /**
 216       * Convert URI back to string
 217       * @return string URI appropriate for output
 218       */
 219      public function toString()
 220      {
 221          // reconstruct authority
 222          $authority = null;
 223          // there is a rendering difference between a null authority
 224          // (http:foo-bar) and an empty string authority
 225          // (http:///foo-bar).
 226          if (!is_null($this->host)) {
 227              $authority = '';
 228              if (!is_null($this->userinfo)) {
 229                  $authority .= $this->userinfo . '@';
 230              }
 231              $authority .= $this->host;
 232              if (!is_null($this->port)) {
 233                  $authority .= ':' . $this->port;
 234              }
 235          }
 236  
 237          // Reconstruct the result
 238          // One might wonder about parsing quirks from browsers after
 239          // this reconstruction.  Unfortunately, parsing behavior depends
 240          // on what *scheme* was employed (file:///foo is handled *very*
 241          // differently than http:///foo), so unfortunately we have to
 242          // defer to the schemes to do the right thing.
 243          $result = '';
 244          if (!is_null($this->scheme)) {
 245              $result .= $this->scheme . ':';
 246          }
 247          if (!is_null($authority)) {
 248              $result .= '//' . $authority;
 249          }
 250          $result .= $this->path;
 251          if (!is_null($this->query)) {
 252              $result .= '?' . $this->query;
 253          }
 254          if (!is_null($this->fragment)) {
 255              $result .= '#' . $this->fragment;
 256          }
 257  
 258          return $result;
 259      }
 260  
 261      /**
 262       * Returns true if this URL might be considered a 'local' URL given
 263       * the current context.  This is true when the host is null, or
 264       * when it matches the host supplied to the configuration.
 265       *
 266       * Note that this does not do any scheme checking, so it is mostly
 267       * only appropriate for metadata that doesn't care about protocol
 268       * security.  isBenign is probably what you actually want.
 269       * @param HTMLPurifier_Config $config
 270       * @param HTMLPurifier_Context $context
 271       * @return bool
 272       */
 273      public function isLocal($config, $context)
 274      {
 275          if ($this->host === null) {
 276              return true;
 277          }
 278          $uri_def = $config->getDefinition('URI');
 279          if ($uri_def->host === $this->host) {
 280              return true;
 281          }
 282          return false;
 283      }
 284  
 285      /**
 286       * Returns true if this URL should be considered a 'benign' URL,
 287       * that is:
 288       *
 289       *      - It is a local URL (isLocal), and
 290       *      - It has a equal or better level of security
 291       * @param HTMLPurifier_Config $config
 292       * @param HTMLPurifier_Context $context
 293       * @return bool
 294       */
 295      public function isBenign($config, $context)
 296      {
 297          if (!$this->isLocal($config, $context)) {
 298              return false;
 299          }
 300  
 301          $scheme_obj = $this->getSchemeObj($config, $context);
 302          if (!$scheme_obj) {
 303              return false;
 304          } // conservative approach
 305  
 306          $current_scheme_obj = $config->getDefinition('URI')->getDefaultScheme($config, $context);
 307          if ($current_scheme_obj->secure) {
 308              if (!$scheme_obj->secure) {
 309                  return false;
 310              }
 311          }
 312          return true;
 313      }
 314  }
 315  
 316  // vim: et sw=4 sts=4