dom/base/nsIContentPolicy.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ft=cpp tw=78 sw=2 et ts=8 : */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsIURI;
  10 interface nsILoadInfo;
  11
  12 /**
  13  * Interface for content policy mechanism.  Implementations of this
  14  * interface can be used to control loading of various types of out-of-line
  15  * content, or processing of certain types of in-line content.
  16  *
  17  * WARNING: do not block the caller from shouldLoad or shouldProcess (e.g.,
  18  * by launching a dialog to prompt the user for something).
  19  */
  20
  21 [scriptable, uuid(caad4f1f-d047-46ac-ae9d-dc598e4fb91b)]
  22 interface nsIContentPolicy : nsISupports
  23 {
  24   /**
  25    * The type of nsIContentPolicy::TYPE_*
  26    */
  27   cenum nsContentPolicyType : 8 {
  28     /**
  29      * Indicates a unset or bogus policy type.
  30      */
  31     TYPE_INVALID = 0,
  32
  33     /**
  34      * Gecko/Firefox developers: Avoid using TYPE_OTHER. Especially for
  35      * requests that are coming from webpages. Or requests in general which
  36      * you expect that security checks will be done on.
  37      * Always use a more specific type if one is available. And do not hesitate
  38      * to add more types as appropriate.
  39      * But if you are fairly sure that no one would care about your more specific
  40      * type, then it's ok to use TYPE_OTHER.
  41      *
  42      * Implementations of nsIContentPolicy should treat this the same way they
  43      * treat unknown types, because existing users of TYPE_OTHER may be converted
  44      * to use new content types.
  45      *
  46      * Note that the TYPE_INTERNAL_* constants are never passed to content
  47      * policy implementations.  They are mapped to other TYPE_* constants, and
  48      * are only intended for internal usage inside Gecko.
  49      */
  50     TYPE_OTHER = 1,
  51
  52     /**
  53      * Indicates an executable script (such as JavaScript).
  54      */
  55     TYPE_SCRIPT = 2,
  56
  57     /**
  58      * Indicates an image (e.g., IMG elements).
  59      */
  60     TYPE_IMAGE = 3,
  61
  62     /**
  63      * Indicates a stylesheet (e.g., STYLE elements).
  64      */
  65     TYPE_STYLESHEET = 4,
  66
  67     /**
  68      * Indicates a generic object (plugin-handled content typically falls under
  69      * this category).
  70      */
  71     TYPE_OBJECT = 5,
  72
  73     /**
  74      * Indicates a document at the top-level (i.e., in a browser).
  75      */
  76     TYPE_DOCUMENT = 6,
  77
  78     /**
  79      * Indicates a document contained within another document (e.g., IFRAMEs,
  80      * FRAMES, and OBJECTs).
  81      */
  82     TYPE_SUBDOCUMENT = 7,
  83
  84     /*
  85      * XXX: nsContentPolicyType = 8 used to inicate a timed refresh request.
  86      */
  87
  88     /*
  89      * XXX: nsContentPolicyType = 9 used to inicate an XBL binding request.
  90      */
  91
  92     /**
  93      * Indicates a ping triggered by a click on <A PING="..."> element.
  94      */
  95     TYPE_PING = 10,
  96
  97     /**
  98      * Indicates an XMLHttpRequest. Also used for document.load and for EventSource.
  99      */
 100     TYPE_XMLHTTPREQUEST = 11,
 101
 102     /**
 103      * Indicates a request by a plugin.
 104      */
 105     TYPE_OBJECT_SUBREQUEST = 12,
 106
 107     /**
 108      * Indicates a DTD loaded by an XML document.
 109      */
 110     TYPE_DTD = 13,
 111
 112     /**
 113      * Indicates a font loaded via @font-face rule.
 114      */
 115     TYPE_FONT = 14,
 116
 117     /**
 118      * Indicates a video or audio load.
 119      */
 120     TYPE_MEDIA = 15,
 121
 122     /**
 123      * Indicates a WebSocket load.
 124      */
 125     TYPE_WEBSOCKET = 16,
 126
 127     /**
 128      * Indicates a Content Security Policy report.
 129      */
 130     TYPE_CSP_REPORT = 17,
 131
 132     /**
 133      * Indicates a style sheet transformation.
 134      */
 135     TYPE_XSLT = 18,
 136
 137     /**
 138      * Indicates a beacon post.
 139      */
 140     TYPE_BEACON = 19,
 141
 142     /**
 143      * Indicates a load initiated by the fetch() function from the Fetch
 144      * specification.
 145      */
 146     TYPE_FETCH = 20,
 147
 148     /**
 149      * Indicates a <img srcset> or <picture> request.
 150      */
 151     TYPE_IMAGESET = 21,
 152
 153     /**
 154      * Indicates a web manifest.
 155      */
 156     TYPE_WEB_MANIFEST = 22,
 157
 158     /**
 159      * Indicates an internal constant for scripts loaded through script
 160      * elements.
 161      *
 162      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 163      * implementations.
 164      */
 165     TYPE_INTERNAL_SCRIPT = 23,
 166
 167     /**
 168      * Indicates an internal constant for scripts loaded through a dedicated
 169      * worker.
 170      *
 171      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 172      * implementations.
 173      */
 174     TYPE_INTERNAL_WORKER = 24,
 175
 176     /**
 177      * Indicates an internal constant for scripts loaded through a shared
 178      * worker.
 179      *
 180      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 181      * implementations.
 182      */
 183     TYPE_INTERNAL_SHARED_WORKER = 25,
 184
 185     /**
 186      * Indicates an internal constant for content loaded from embed elements.
 187      *
 188      * This will be mapped to TYPE_OBJECT.
 189      */
 190     TYPE_INTERNAL_EMBED = 26,
 191
 192     /**
 193      * Indicates an internal constant for content loaded from object elements.
 194      *
 195      * This will be mapped to TYPE_OBJECT.
 196      */
 197     TYPE_INTERNAL_OBJECT = 27,
 198
 199     /**
 200      * Indicates an internal constant for content loaded from frame elements.
 201      *
 202      * This will be mapped to TYPE_SUBDOCUMENT.
 203      */
 204     TYPE_INTERNAL_FRAME = 28,
 205
 206     /**
 207      * Indicates an internal constant for content loaded from iframe elements.
 208      *
 209      * This will be mapped to TYPE_SUBDOCUMENT.
 210      */
 211     TYPE_INTERNAL_IFRAME = 29,
 212
 213     /**
 214      * Indicates an internal constant for content loaded from audio elements.
 215      *
 216      * This will be mapped to TYPE_MEDIA.
 217      */
 218     TYPE_INTERNAL_AUDIO = 30,
 219
 220     /**
 221      * Indicates an internal constant for content loaded from video elements.
 222      *
 223      * This will be mapped to TYPE_MEDIA.
 224      */
 225     TYPE_INTERNAL_VIDEO = 31,
 226
 227     /**
 228      * Indicates an internal constant for content loaded from track elements.
 229      *
 230      * This will be mapped to TYPE_MEDIA.
 231      */
 232     TYPE_INTERNAL_TRACK = 32,
 233
 234     /**
 235      * Indicates an internal constant for an XMLHttpRequest.
 236      *
 237      * This will be mapped to TYPE_XMLHTTPREQUEST.
 238      */
 239     TYPE_INTERNAL_XMLHTTPREQUEST = 33,
 240
 241     /**
 242      * Indicates an internal constant for EventSource.
 243      *
 244      * This will be mapped to TYPE_XMLHTTPREQUEST.
 245      */
 246     TYPE_INTERNAL_EVENTSOURCE = 34,
 247
 248     /**
 249      * Indicates an internal constant for scripts loaded through a service
 250      * worker.
 251      *
 252      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 253      * implementations.
 254      */
 255     TYPE_INTERNAL_SERVICE_WORKER = 35,
 256
 257     /**
 258      * Indicates an internal constant for *preloaded* scripts
 259      * loaded through script elements.
 260      *
 261      * This will be mapped to TYPE_SCRIPT before being passed
 262      * to content policy implementations.
 263      */
 264     TYPE_INTERNAL_SCRIPT_PRELOAD = 36,
 265
 266     /**
 267      * Indicates an internal constant for normal images.
 268      *
 269      * This will be mapped to TYPE_IMAGE before being passed
 270      * to content policy implementations.
 271      */
 272     TYPE_INTERNAL_IMAGE = 37,
 273
 274     /**
 275      * Indicates an internal constant for *preloaded* images.
 276      *
 277      * This will be mapped to TYPE_IMAGE before being passed
 278      * to content policy implementations.
 279      */
 280     TYPE_INTERNAL_IMAGE_PRELOAD = 38,
 281
 282     /**
 283      * Indicates an internal constant for normal stylesheets.
 284      *
 285      * This will be mapped to TYPE_STYLESHEET before being passed
 286      * to content policy implementations.
 287      */
 288     TYPE_INTERNAL_STYLESHEET = 39,
 289
 290     /**
 291      * Indicates an internal constant for *preloaded* stylesheets.
 292      *
 293      * This will be mapped to TYPE_STYLESHEET before being passed
 294      * to content policy implementations.
 295      */
 296     TYPE_INTERNAL_STYLESHEET_PRELOAD = 40,
 297
 298     /**
 299      * Indicates an internal constant for favicon.
 300      *
 301      * This will be mapped to TYPE_IMAGE before being passed
 302      * to content policy implementations.
 303      */
 304     TYPE_INTERNAL_IMAGE_FAVICON = 41,
 305
 306     /**
 307      * Indicates an importScripts() inside a worker script.
 308      *
 309      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 310      * implementations.
 311      */
 312     TYPE_INTERNAL_WORKER_IMPORT_SCRIPTS = 42,
 313
 314     /**
 315      * Indicates an save-as link download from the front-end code.
 316      */
 317     TYPE_SAVEAS_DOWNLOAD = 43,
 318
 319     /**
 320      * Indicates a speculative connection.
 321      */
 322     TYPE_SPECULATIVE = 44,
 323
 324     /**
 325      * Indicates an internal constant for ES6 module scripts
 326      * loaded through script elements or an import statement (static import) or
 327      * an import expression (dynamic import).
 328      * It also indicates the load for dynamic import in workers.
 329      * For static import in module workers,
 330      * please check TYPE_INTERNAL_WORKER_STATIC_MODULE.
 331      *
 332      * This will be mapped to TYPE_SCRIPT before being passed
 333      * to content policy implementations.
 334      */
 335     TYPE_INTERNAL_MODULE = 45,
 336
 337     /**
 338      * Indicates an internal constant for *preloaded* ES6 module scripts
 339      * loaded through script elements or an import statement.
 340      *
 341      * This will be mapped to TYPE_SCRIPT before being passed
 342      * to content policy implementations.
 343      */
 344     TYPE_INTERNAL_MODULE_PRELOAD = 46,
 345
 346     /**
 347      * Indicates a DTD loaded by an XML document the URI of which could
 348      * not be mapped to a known local DTD.
 349      */
 350     TYPE_INTERNAL_DTD = 47,
 351
 352     /**
 353      * Indicates a TYPE_INTERNAL_DTD which will not be blocked no matter
 354      * what principal is being loaded from.
 355      */
 356     TYPE_INTERNAL_FORCE_ALLOWED_DTD = 48,
 357
 358     /**
 359      * Indicates an internal constant for scripts loaded through an
 360      * audioWorklet.
 361      *
 362      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 363      * implementations.
 364      */
 365     TYPE_INTERNAL_AUDIOWORKLET = 49,
 366
 367     /**
 368      * Indicates an internal constant for scripts loaded through an
 369      * paintWorklet.
 370      *
 371      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 372      * implementations.
 373      */
 374     TYPE_INTERNAL_PAINTWORKLET = 50,
 375
 376     /**
 377      * Same as TYPE_FONT but indicates this is a <link rel=preload as=font>
 378      * preload initiated load.
 379      */
 380     TYPE_INTERNAL_FONT_PRELOAD = 51,
 381
 382     /**
 383      * Indicates the load of a (Firefox-internal) script through ChromeUtils
 384      *
 385      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 386      * implementations.
 387     */
 388     TYPE_INTERNAL_CHROMEUTILS_COMPILED_SCRIPT = 52,
 389
 390     /**
 391      * Indicates the load of a script through FrameMessageManager
 392      *
 393      * This will be mapped to TYPE_SCRIPT before being passed to content policy
 394      * implementations.
 395     */
 396     TYPE_INTERNAL_FRAME_MESSAGEMANAGER_SCRIPT = 53,
 397
 398     /**
 399      * Indicates an internal constant for *preloaded* fetch
 400      * loaded through link elements.
 401      *
 402      * This will be mapped to TYPE_FETCH before being passed
 403      * to content policy implementations.
 404      */
 405     TYPE_INTERNAL_FETCH_PRELOAD = 54,
 406
 407     /**
 408      * Indicates a font loaded via @font-face rule in an UA style sheet.
 409      * (CSP does not apply.)
 410      */
 411     TYPE_UA_FONT = 55,
 412
 413     /**
 414      * Indicates the establishment of a TCP or TLS connection via an
 415      * http/https proxy that will be used for webrtc media. When no web proxy
 416      * is involved, webrtc uses lower level sockets that are not subject to
 417      * any sort of content policy.
 418      */
 419     TYPE_PROXIED_WEBRTC_MEDIA = 56,
 420
 421     /**
 422      * Indicates the load of data via the Federated Credential Management API
 423      * with data destined for a browser context.
 424      */
 425      TYPE_WEB_IDENTITY = 57,
 426
 427     /**
 428      * Indicates the load of a static module on workers.
 429      */
 430     TYPE_INTERNAL_WORKER_STATIC_MODULE = 58,
 431
 432     /**
 433      * Indicates Webtransport request
 434      */
 435     TYPE_WEB_TRANSPORT = 59,
 436
 437     /**
 438      * Used to indicate the end of this list, not a content policy. If you want
 439      * to add a new content policy type, place it before this sentinel value
 440      * TYPE_END, have it use TYPE_END's current value, and increment TYPE_END by
 441      * one. (TYPE_END should always have the highest numerical value.)
 442      */
 443     TYPE_END = 60,
 444
 445
 446     /* When adding new content types, please update
 447      * NS_CP_ContentTypeName, nsCSPContext, CSP_ContentTypeToDirective,
 448      * DoContentSecurityChecks, all nsIContentPolicy implementations, the
 449      * static_assert in dom/cache/DBSchema.cpp, ChannelWrapper.webidl,
 450      * ChannelWrapper.cpp, PermissionManager.cpp,
 451      * IPCMessageUtilsSpecializations.h, and other things that are not
 452      * listed here that are related to nsIContentPolicy. */
 453   };
 454
 455   //////////////////////////////////////////////////////////////////////
 456
 457   /**
 458    * Returned from shouldLoad or shouldProcess if the load or process request
 459    * is rejected based on details of the request.
 460    */
 461   const short REJECT_REQUEST = -1;
 462
 463   /**
 464    * Returned from shouldLoad or shouldProcess if the load/process is rejected
 465    * based solely on its type (of the above flags).
 466    *
 467    * NOTE that it is not meant to stop future requests for this type--only the
 468    * current request.
 469    */
 470   const short REJECT_TYPE = -2;
 471
 472   /**
 473    * Returned from shouldLoad or shouldProcess if the load/process is rejected
 474    * based on the server it is hosted on or requested from (aContentLocation or
 475    * aRequestOrigin), e.g., if you block an IMAGE because it is served from
 476    * goatse.cx (even if you don't necessarily block other types from that
 477    * server/domain).
 478    *
 479    * NOTE that it is not meant to stop future requests for this server--only the
 480    * current request.
 481    */
 482   const short REJECT_SERVER = -3;
 483
 484   /**
 485    * Returned from shouldLoad or shouldProcess if the load/process is rejected
 486    * based on some other criteria. Mozilla callers will handle this like
 487    * REJECT_REQUEST; third-party implementors may, for example, use this to
 488    * direct their own callers to consult the extra parameter for additional
 489    * details.
 490    */
 491   const short REJECT_OTHER = -4;
 492
 493   /**
 494    * Returned from shouldLoad or shouldProcess if the load/process is forbiddden
 495    * based on enterprise policy.
 496    */
 497   const short REJECT_POLICY = -5;
 498
 499   /**
 500    * Returned from shouldLoad or shouldProcess if the load or process request
 501    * is not rejected.
 502    */
 503   const short ACCEPT = 1;
 504
 505   /**
 506    * Should the resource at this location be loaded?
 507    * ShouldLoad will be called before loading the resource at aContentLocation
 508    * to determine whether to start the load at all.
 509    *
 510    * @param aContentLocation  the location of the content being checked; must
 511    *                          not be null
 512    *
 513    * @param aLoadInfo         the loadinfo of the channel being evaluated.
 514    *
 515    * @return ACCEPT or REJECT_*
 516    *
 517    * @note shouldLoad can be called while the DOM and layout of the document
 518    * involved is in an inconsistent state.  This means that implementors of
 519    * this method MUST NOT do any of the following:
 520    * 1)  Modify the DOM in any way (e.g. setting attributes is a no-no).
 521    * 2)  Query any DOM properties that depend on layout (e.g. offset*
 522    *     properties).
 523    * 3)  Query any DOM properties that depend on style (e.g. computed style).
 524    * 4)  Query any DOM properties that depend on the current state of the DOM
 525    *     outside the "context" node (e.g. lengths of node lists).
 526    * 5)  [JavaScript implementations only] Access properties of any sort on any
 527    *     object without using XPCNativeWrapper (either explicitly or
 528    *     implicitly).  Due to various DOM0 things, this leads to item 4.
 529    * If you do any of these things in your shouldLoad implementation, expect
 530    * unpredictable behavior, possibly including crashes, content not showing
 531    * up, content showing up doubled, etc.  If you need to do any of the things
 532    * above, do them off timeout or event.
 533    */
 534   short shouldLoad(in nsIURI      aContentLocation,
 535                    in nsILoadInfo aLoadInfo);
 536
 537   /**
 538    * Should the resource be processed?
 539    * ShouldProcess will be called once all the information passed to it has
 540    * been determined about the resource, typically after part of the resource
 541    * has been loaded.
 542    *
 543    * @param aContentLocation  OPTIONAL; the location of the resource being
 544    *                          requested: MAY be, e.g., a post-redirection URI
 545    *                          for the resource.
 546    *
 547    * @param aLoadInfo         the loadinfo of the channel being evaluated.
 548    *
 549    * @return ACCEPT or REJECT_*
 550    *
 551    * @note shouldProcess can be called while the DOM and layout of the document
 552    * involved is in an inconsistent state.  See the note on shouldLoad to see
 553    * what this means for implementors of this method.
 554    */
 555   short shouldProcess(in nsIURI      aContentLocation,
 556                       in nsILoadInfo aLoadInfo);
 557 };
 558
 559 typedef nsIContentPolicy_nsContentPolicyType nsContentPolicyType;
 560
 561 %{C++
 562 enum class ExtContentPolicyType : uint8_t {
 563   /**
 564    * The type of ExtContentPolicy::TYPE_*
 565    */
 566   TYPE_INVALID = nsIContentPolicy::TYPE_INVALID,
 567   TYPE_OTHER = nsIContentPolicy::TYPE_OTHER,
 568   TYPE_SCRIPT = nsIContentPolicy::TYPE_SCRIPT,
 569   TYPE_IMAGE = nsIContentPolicy::TYPE_IMAGE,
 570   TYPE_STYLESHEET = nsIContentPolicy::TYPE_STYLESHEET,
 571   TYPE_OBJECT = nsIContentPolicy::TYPE_OBJECT,
 572   TYPE_DOCUMENT = nsIContentPolicy::TYPE_DOCUMENT,
 573   TYPE_SUBDOCUMENT = nsIContentPolicy::TYPE_SUBDOCUMENT,
 574   TYPE_PING = nsIContentPolicy::TYPE_PING,
 575   TYPE_XMLHTTPREQUEST = nsIContentPolicy::TYPE_XMLHTTPREQUEST,
 576   TYPE_OBJECT_SUBREQUEST = nsIContentPolicy::TYPE_OBJECT_SUBREQUEST,
 577   TYPE_DTD = nsIContentPolicy::TYPE_DTD,
 578   TYPE_FONT = nsIContentPolicy::TYPE_FONT,
 579   TYPE_MEDIA = nsIContentPolicy::TYPE_MEDIA,
 580   TYPE_WEBSOCKET = nsIContentPolicy::TYPE_WEBSOCKET,
 581   TYPE_CSP_REPORT = nsIContentPolicy::TYPE_CSP_REPORT,
 582   TYPE_XSLT = nsIContentPolicy::TYPE_XSLT,
 583   TYPE_BEACON = nsIContentPolicy::TYPE_BEACON,
 584   TYPE_FETCH = nsIContentPolicy::TYPE_FETCH,
 585   TYPE_IMAGESET = nsIContentPolicy::TYPE_IMAGESET,
 586   TYPE_WEB_MANIFEST = nsIContentPolicy::TYPE_WEB_MANIFEST,
 587   TYPE_SAVEAS_DOWNLOAD = nsIContentPolicy::TYPE_SAVEAS_DOWNLOAD,
 588   TYPE_SPECULATIVE = nsIContentPolicy::TYPE_SPECULATIVE,
 589   TYPE_UA_FONT = nsIContentPolicy::TYPE_UA_FONT,
 590   TYPE_PROXIED_WEBRTC_MEDIA = nsIContentPolicy::TYPE_PROXIED_WEBRTC_MEDIA,
 591   TYPE_WEB_IDENTITY = nsIContentPolicy::TYPE_WEB_IDENTITY,
 592   TYPE_WEB_TRANSPORT = nsIContentPolicy::TYPE_WEB_TRANSPORT,
 593 };
 594
 595 typedef ExtContentPolicyType ExtContentPolicy;
 596 %}