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