parser/html/nsIParserUtils.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIURI;
   8
   9 webidl DocumentFragment;
  10 webidl Element;
  11
  12 /**
  13  * Non-Web HTML parser functionality to Firefox extensions and XULRunner apps.
  14  * Don't use this from within Gecko--use nsContentUtils, nsTreeSanitizer, etc.
  15  * directly instead.
  16  */
  17 [builtinclass, scriptable, uuid(a1101145-0025-411e-8873-fdf57bf28128)]
  18 interface nsIParserUtils : nsISupports
  19 {
  20   /**
  21    * Flag for sanitizer: Allow comment nodes.
  22    */
  23   const unsigned long SanitizerAllowComments = (1 << 0);
  24
  25   /**
  26    * Flag for sanitizer: Allow <style> and style="" (with contents sanitized
  27    * in case of -moz-binding). Note! If -moz-binding is absent, properties
  28    * that might be XSS risks in other Web engines are preserved!
  29    */
  30   const unsigned long SanitizerAllowStyle = (1 << 1);
  31
  32   /**
  33    * Flag for sanitizer: Only allow cid: URLs for embedded content.
  34    *
  35    * At present, sanitizing CSS backgrounds, etc., is not supported, so setting
  36    * this together with SanitizerAllowStyle doesn't make sense.
  37    *
  38    * At present, sanitizing CSS syntax in SVG presentational attributes is not
  39    * supported, so this option flattens out SVG.
  40    */
  41   const unsigned long SanitizerCidEmbedsOnly = (1 << 2);
  42
  43   /**
  44    * Flag for sanitizer: Drop non-CSS presentational HTML elements and
  45    * attributes, such as <font>, <center> and bgcolor="".
  46    */
  47   const unsigned long SanitizerDropNonCSSPresentation = (1 << 3);
  48
  49   /**
  50    * Flag for sanitizer: Drop forms and form controls (excluding
  51    * fieldset/legend).
  52    */
  53   const unsigned long SanitizerDropForms = (1 << 4);
  54
  55   /**
  56    * Flag for sanitizer: Drop <img>, <video>, <audio> and <source> and flatten
  57    * out SVG.
  58    */
  59   const unsigned long SanitizerDropMedia = (1 << 5);
  60
  61   /**
  62    * Flag for sanitizer: Log messages to the console for everything that gets
  63    * sanitized
  64    */
  65   const unsigned long SanitizerLogRemovals = (1 << 6);
  66
  67   /**
  68    * Parses a string into an HTML document, sanitizes the document and
  69    * returns the result serialized to a string.
  70    *
  71    * The sanitizer is designed to protect against XSS when sanitized content
  72    * is inserted into a different-origin context without an iframe-equivalent
  73    * sandboxing mechanism.
  74    *
  75    * By default, the sanitizer doesn't try to avoid leaking information that
  76    * the content was viewed to third parties. That is, by default, e.g.
  77    * <img src> pointing to an HTTP server potentially controlled by a third
  78    * party is not removed. To avoid ambient information leakage upon loading
  79    * the sanitized content, use the SanitizerInternalEmbedsOnly flag. In that
  80    * case, <a href> links (and similar) to other content are preserved, so an
  81    * explicit user action (following a link) after the content has been loaded
  82    * can still leak information.
  83    *
  84    * By default, non-dangerous non-CSS presentational HTML elements and
  85    * attributes or forms are not removed. To remove these, use
  86    * SanitizerDropNonCSSPresentation and/or SanitizerDropForms.
  87    *
  88    * By default, comments and CSS is removed. To preserve comments, use
  89    * SanitizerAllowComments. To preserve <style> and style="", use
  90    * SanitizerAllowStyle. -moz-binding is removed from <style> and style="" if
  91    * present. In this case, properties that Gecko doesn't recognize can get
  92    * removed as a side effect. Note! If -moz-binding is not present, <style>
  93    * and style="" and SanitizerAllowStyle is specified, the sanitized content
  94    * may still be XSS dangerous if loaded into a non-Gecko Web engine!
  95    *
  96    * @param src the HTML source to parse (C++ callers are allowed but not
  97    *            required to use the same string for the return value.)
  98    * @param flags sanitization option flags defined above
  99    */
 100   AString sanitize(in AString src, in unsigned long flags);
 101
 102   /**
 103    * Removes conditional CSS (@media / etc) from the input string.
 104    */
 105   AString removeConditionalCSS(in AString src);
 106
 107   /**
 108    * Convert HTML to plain text.
 109    *
 110    * @param src the HTML source to parse (C++ callers are allowed but not
 111    *            required to use the same string for the return value.)
 112    * @param flags conversion option flags defined in nsIDocumentEncoder
 113    * @param wrapCol number of characters per line; 0 for no auto-wrapping
 114    */
 115   AString convertToPlainText(in AString src,
 116                              in unsigned long flags,
 117                              in unsigned long wrapCol);
 118
 119   /**
 120    * Parses markup into a sanitized document fragment.
 121    *
 122    * @param fragment the input markup
 123    * @param flags sanitization option flags defined above
 124    * @param isXML true if |fragment| is XML and false if HTML
 125    * @param baseURI the base URL for this fragment
 126    * @param element the context node for the fragment parsing algorithm
 127    */
 128   DocumentFragment parseFragment(in AString fragment,
 129                                  in unsigned long flags,
 130                                  in boolean isXML,
 131                                  in nsIURI baseURI,
 132                                  in Element element);
 133
 134 };
 135
 136 %{ C++
 137 #define NS_PARSERUTILS_CONTRACTID \
 138     "@mozilla.org/parserutils;1"
 139 #define NS_PARSERUTILS_CID  \
 140 { 0xaf7b24cb, 0x893f, 0x41bb, { 0x96, 0x1f, 0x5a, 0x69, 0x38, 0x8e, 0x27, 0xc3 } }
 141 %}