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