nsIParserUtils.idl (5429B)
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 %}