caps/nsIPrincipal.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /* Defines the abstract interface for a principal. */
   7
   8 #include "nsIContentSecurityPolicy.idl"
   9 #include "nsISerializable.idl"
  10 #include "nsIAboutModule.idl"
  11 #include "nsIReferrerInfo.idl"
  12 interface nsIChannel;
  13 #include "mozIDOMWindow.idl"
  14
  15 %{C++
  16 struct JSPrincipals;
  17 #include "nsCOMPtr.h"
  18 #include "nsTArray.h"
  19 #include "nsString.h"
  20 #include "mozilla/DebugOnly.h"
  21 namespace mozilla {
  22 class OriginAttributes;
  23 }
  24
  25 /**
  26  * Some methods have a fast path for the case when we're comparing a principal
  27  * to itself. The situation may happen for example with about:blank documents.
  28  */
  29
  30 #define DECL_FAST_INLINE_HELPER(method_)                       \
  31   inline bool method_(nsIPrincipal* aOther)                    \
  32   {                                                            \
  33     mozilla::DebugOnly<bool> val = false;                      \
  34     MOZ_ASSERT_IF(this == aOther,                              \
  35                   NS_SUCCEEDED(method_(aOther, &val)) && val); \
  36                                                                \
  37     bool retVal = false;                                       \
  38     return                                                     \
  39       this == aOther ||                                        \
  40       (NS_SUCCEEDED(method_(aOther, &retVal)) && retVal);      \
  41   }
  42
  43 %}
  44
  45 interface nsIURI;
  46
  47 [ptr] native JSContext(JSContext);
  48 [ptr] native JSPrincipals(JSPrincipals);
  49 [ref] native PrincipalArray(const nsTArray<nsCOMPtr<nsIPrincipal>>);
  50 [ref] native const_OriginAttributes(const mozilla::OriginAttributes);
  51 native ReferrerPolicy(mozilla::dom::ReferrerPolicy);
  52
  53 [scriptable, builtinclass, uuid(f75f502d-79fd-48be-a079-e5a7b8f80c8b)]
  54 interface nsIPrincipal : nsISupports
  55 {
  56     /**
  57      * Returns whether the other principal is equivalent to this principal.
  58      * Principals are considered equal if they are the same principal, or
  59      * they have the same origin.
  60      */
  61     boolean equals(in nsIPrincipal other);
  62
  63     /**
  64      * Returns whether the other principal is equivalent to this principal
  65      * for permission purposes
  66      * Matches {originAttributes ,equalsURIForPermission}
  67      */
  68
  69     boolean equalsForPermission(in nsIPrincipal other, in bool aExactHost);
  70
  71     /**
  72      * Like equals, but takes document.domain changes into account.
  73      */
  74     boolean equalsConsideringDomain(in nsIPrincipal other);
  75
  76     %{C++
  77       DECL_FAST_INLINE_HELPER(Equals)
  78       DECL_FAST_INLINE_HELPER(EqualsConsideringDomain)
  79     %}
  80
  81     /*
  82     * Returns whether the Principals URI is equal to the other URI
  83     */
  84     boolean equalsURI(in nsIURI aOtherURI);
  85
  86     /**
  87      * Returns a hash value for the principal.
  88      */
  89     [notxpcom, nostdcall] readonly attribute unsigned long hashValue;
  90
  91     /**
  92      * The principal URI to which this principal pertains.  This is
  93      * generally the document URI.
  94      */
  95     [infallible] readonly attribute nsIURI URI;
  96
  97     /**
  98      * The domain URI to which this principal pertains.
  99      * This is null unless script successfully sets document.domain to our URI
 100      * or a superdomain of our URI.
 101      * Setting this has no effect on the URI.
 102      * See https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#Changing_origin
 103      */
 104     [noscript] attribute nsIURI domain;
 105
 106     /**
 107      * Returns whether the other principal is equal to or weaker than this
 108      * principal. Principals are equal if they are the same object or they
 109      * have the same origin.
 110      *
 111      * Thus a principal always subsumes itself.
 112      *
 113      * The system principal subsumes itself and all other principals.
 114      *
 115      * A null principal (corresponding to an unknown, hence assumed minimally
 116      * privileged, security context) is not equal to any other principal
 117      * (including other null principals), and therefore does not subsume
 118      * anything but itself.
 119      */
 120     boolean subsumes(in nsIPrincipal other);
 121
 122     /**
 123      * Same as the previous method, subsumes(), but takes document.domain into
 124      * account.
 125      */
 126     boolean subsumesConsideringDomain(in nsIPrincipal other);
 127
 128     /**
 129      * Same as the subsumesConsideringDomain(), but ignores the first party
 130      * domain in its originAttributes.
 131      */
 132     boolean subsumesConsideringDomainIgnoringFPD(in nsIPrincipal other);
 133
 134     %{C++
 135       DECL_FAST_INLINE_HELPER(Subsumes)
 136       DECL_FAST_INLINE_HELPER(SubsumesConsideringDomain)
 137       DECL_FAST_INLINE_HELPER(SubsumesConsideringDomainIgnoringFPD)
 138 #undef DECL_FAST_INLINE_HELPER
 139     %}
 140
 141     /**
 142      * Checks whether this principal is allowed to load the network resource
 143      * located at the given URI under the same-origin policy. This means that
 144      * content principals are only allowed to load resources from the same
 145      * domain, the system principal is allowed to load anything, and null
 146      * principals can only load URIs where they are the principal. This is
 147      * changed by the optional flag allowIfInheritsPrincipal (which defaults to
 148      * false) which allows URIs that inherit their loader's principal.
 149      *
 150      * If the load is allowed this function does nothing. If the load is not
 151      * allowed the function throws NS_ERROR_DOM_BAD_URI.
 152      *
 153      * NOTE: Other policies might override this, such as the Access-Control
 154      *       specification.
 155      * NOTE: The 'domain' attribute has no effect on the behaviour of this
 156      *       function.
 157      *
 158      *
 159      * @param uri    The URI about to be loaded.
 160      * @param allowIfInheritsPrincipal   If true, the load is allowed if the
 161      *                                   loadee inherits the principal of the
 162      *                                   loader.
 163      * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed.
 164      */
 165     void checkMayLoad(in nsIURI uri,
 166                       in boolean allowIfInheritsPrincipal);
 167
 168     /**
 169      * Like checkMayLoad, but if returning an error will also report that error
 170      * to the console, using the provided window id.  The window id may be 0 to
 171      * report to just the browser console, not web consoles.
 172      */
 173     void checkMayLoadWithReporting(in nsIURI uri,
 174                                    in boolean allowIfInheritsPrincipal,
 175                                    in unsigned long long innerWindowID);
 176
 177     /**
 178     * Checks if the provided URI is considered third-party to the
 179     * URI of the principal.
 180     * Returns true if the URI is third-party.
 181     *
 182     * @param uri - The URI to check
 183     */
 184     boolean isThirdPartyURI(in nsIURI uri);
 185
 186     /**
 187     * Checks if the provided principal is considered third-party to the
 188     * URI of the Principal.
 189     * Returns true if the principal is third-party.
 190     *
 191     * @param principal - The principal to check
 192     */
 193     boolean isThirdPartyPrincipal(in nsIPrincipal principal);
 194
 195     /**
 196     * Checks if the provided channel is considered third-party to the
 197     * URI of the principal.
 198     * Returns true if the channel is third-party.
 199     * Returns false if the Principal is a System Principal
 200     *
 201     * @param channel - The Channel to check
 202     */
 203     boolean isThirdPartyChannel(in nsIChannel channel);
 204
 205     /**
 206      * A dictionary of the non-default origin attributes associated with this
 207      * nsIPrincipal.
 208      *
 209      * Attributes are tokens that are taken into account when determining whether
 210      * two principals are same-origin - if any attributes differ, the principals
 211      * are cross-origin, even if the scheme, host, and port are the same.
 212      * Attributes should also be considered for all security and bucketing decisions,
 213      * even those which make non-standard comparisons (like cookies, which ignore
 214      * scheme, or quotas, which ignore subdomains).
 215      *
 216      * If you're looking for an easy-to-use canonical stringification of the origin
 217      * attributes, see |originSuffix| below.
 218      */
 219     [implicit_jscontext]
 220     readonly attribute jsval originAttributes;
 221
 222     [noscript, notxpcom, nostdcall, binaryname(OriginAttributesRef)]
 223     const_OriginAttributes OriginAttributesRef();
 224
 225     /**
 226      * A canonical representation of the origin for this principal. This
 227      * consists of a base string (which, for content principals, is of the
 228      * format scheme://host:port), concatenated with |originAttributes| (see
 229      * below).
 230      *
 231      * We maintain the invariant that principalA.equals(principalB) if and only
 232      * if principalA.origin == principalB.origin.
 233      */
 234     readonly attribute ACString origin;
 235
 236     /**
 237      * Returns an ASCII compatible representation
 238      * of the principals Origin
 239      */
 240     [noscript] readonly attribute ACString asciiOrigin;
 241
 242     /**
 243      * Returns the "host:port" portion of the
 244      * Principals URI, if any.
 245      */
 246     readonly attribute ACString hostPort;
 247
 248     /**
 249      * Returns the "host:port" portion of the
 250      * Principals URI, if any.
 251      */
 252     readonly attribute ACString asciiHost;
 253
 254     /**
 255      * Returns the "host" portion of the
 256      * Principals URI, if any.
 257      */
 258     readonly attribute ACString host;
 259
 260     /**
 261      * Returns the prePath of the principals uri
 262      * follows the format scheme:
 263      * "scheme://username:password@hostname:portnumber/"
 264      */
 265     readonly attribute ACString prePath;
 266
 267     /**
 268      * Returns the filePath of the principals uri. See nsIURI.
 269      */
 270     readonly attribute ACString filePath;
 271
 272     /**
 273       * Returns the ASCII Spec from the Principals URI.
 274       * Might return the empty string, e.g. for the case of
 275       * a SystemPrincipal or an EpxandedPrincipal.
 276       *
 277       * WARNING: DO NOT USE FOR SECURITY CHECKS.
 278       * just for logging purposes!
 279      */
 280     readonly attribute ACString asciiSpec;
 281
 282     /**
 283       * Returns the Spec from the Principals URI.
 284       * Might return the empty string, e.g. for the case of
 285       * a SystemPrincipal or an EpxandedPrincipal.
 286       *
 287       * WARNING: Do not land new Code using, as this will be removed soon
 288      */
 289     readonly attribute ACString spec;
 290
 291     /* Returns the Pre Path of the Principals URI with
 292     * user:pass stripped for privacy and spoof prevention
 293     */
 294     readonly attribute ACString exposablePrePath;
 295
 296     /* Returns the Spec of the Principals URI with
 297     * user/pass/ref/query stripped for privacy and spoof prevention
 298     */
 299     readonly attribute ACString exposableSpec;
 300
 301     /**
 302      * Return the scheme of the principals URI
 303      */
 304     readonly attribute ACString scheme;
 305
 306     /**
 307     * Checks if the Principal's URI Scheme matches with the parameter
 308     *
 309     * @param scheme    The scheme to be checked
 310     */
 311     [infallible]
 312     boolean schemeIs(in string scheme);
 313
 314     /*
 315      * Checks if the Principal's URI is contained in the given Pref
 316      * @param pref    The pref to be checked
 317      */
 318     [infallible]
 319     boolean isURIInPrefList(in string pref);
 320
 321     /*
 322     * Uses NS_Security Compare to determine if the
 323     * other URI is same-origin as the uri of the Principal
 324     */
 325     bool isSameOrigin(in nsIURI otherURI, in bool aIsPrivateWin);
 326
 327     /*
 328     * Checks if the Principal is allowed to load the Provided file:// URI
 329     * using NS_RelaxStrictFileOriginPolicy
 330     */
 331     bool allowsRelaxStrictFileOriginPolicy(in nsIURI aURI);
 332
 333
 334     /*
 335     *  Generates a Cache-Key for the Cors-Preflight Cache
 336     */
 337     [noscript]
 338     ACString getPrefLightCacheKey(in nsIURI aURI ,in bool aWithCredentials,
 339                                   in const_OriginAttributes aOriginAttributes);
 340
 341
 342     /*
 343     *  Checks if the Principals URI has first party storage access
 344     *  when loaded inside the provided 3rd party resource window.
 345     *  See also: ContentBlocking::ShouldAllowAccessFor
 346     */
 347     bool hasFirstpartyStorageAccess(in mozIDOMWindow aWindow, out uint32_t rejectedReason);
 348
 349
 350     /*
 351     * Returns a Key for the LocalStorage Manager, used to
 352     * check the Principals Origin Storage usage.
 353     */
 354     readonly attribute ACString localStorageQuotaKey;
 355
 356     /**
 357      * Implementation of
 358      * https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy
 359      *
 360      * The value returned by this method feeds into the the Secure Context
 361      * algorithm that determins the value of Window.isSecureContext and
 362      * WorkerGlobalScope.isSecureContext.
 363      *
 364      * This method returns false instead of throwing upon errors.
 365      */
 366     [infallible]
 367     readonly attribute boolean isOriginPotentiallyTrustworthy;
 368
 369     /**
 370      * Returns the Flags of the Principals
 371      * associated AboutModule, in case there is one.
 372      */
 373     uint32_t getAboutModuleFlags();
 374
 375     /*
 376     * Returns the Key to access the Principals
 377     * Origin Local/Session Storage
 378     */
 379     readonly attribute ACString storageOriginKey;
 380
 381     /**
 382      * Creates and Returns a new ReferrerInfo with the
 383      * Principals URI
 384      */
 385     nsIReferrerInfo createReferrerInfo(in ReferrerPolicy aReferrerPolicy);
 386
 387     /**
 388      * The base part of |origin| without the concatenation with |originSuffix|.
 389      * This doesn't have the important invariants described above with |origin|,
 390      * and as such should only be used for legacy situations.
 391      */
 392     readonly attribute ACString originNoSuffix;
 393
 394     /**
 395      * A string of the form !key1=value1&key2=value2, where each pair represents
 396      * an attribute with a non-default value. If all attributes have default
 397      * values, this is the empty string.
 398      *
 399      * The value of .originSuffix is automatically serialized into .origin, so any
 400      * consumers using that are automatically origin-attribute-aware. Consumers with
 401      * special requirements must inspect and compare .originSuffix manually.
 402      */
 403     readonly attribute AUTF8String originSuffix;
 404
 405     /**
 406      * A canonical representation of the site-origin for this principal.
 407      * This string has the same format as |origin| (see above). Two principals
 408      * with differing |siteOrigin| values will never compare equal, even when
 409      * considering domain mutations.
 410      *
 411      * For most principals, |siteOrigin| matches |origin| precisely. Only
 412      * principals which allow mutating |domain|, such as ContentPrincipal,
 413      * override the default implementation in BasePrincipal.
 414      */
 415     readonly attribute ACString siteOrigin;
 416
 417     /**
 418      * The base part of |siteOrigin| without the concatenation with
 419      * |originSuffix|.
 420      */
 421     readonly attribute ACString siteOriginNoSuffix;
 422
 423     /**
 424      * The base domain of the principal URI to which this principal pertains
 425      * (generally the document URI), handling null principals and
 426      * non-hierarchical schemes correctly.
 427      */
 428     readonly attribute ACString baseDomain;
 429
 430     /**
 431      * Gets the ID of the add-on this principal belongs to.
 432      */
 433     readonly attribute AString addonId;
 434
 435     readonly attribute nsISupports addonPolicy;
 436
 437     /**
 438      * Gets the id of the user context this principal is inside.  If this
 439      * principal is inside the default userContext, this returns
 440      * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID.
 441      */
 442     [infallible] readonly attribute unsigned long userContextId;
 443
 444     /**
 445      * Gets the id of the private browsing state of the context containing
 446      * this principal. If the principal has a private browsing value of 0, it
 447      * is not in private browsing.
 448      */
 449     [infallible] readonly attribute unsigned long privateBrowsingId;
 450
 451     /**
 452      * Returns true iff the principal is inside an isolated mozbrowser element.
 453      * <xul:browser> is not considered to be a mozbrowser element.
 454      * <iframe mozbrowser noisolation> does not count as isolated since
 455      * isolation is disabled.  Isolation can only be disabled if the
 456      * containing document is chrome.
 457      */
 458     [infallible] readonly attribute boolean isInIsolatedMozBrowserElement;
 459
 460     /**
 461      * Returns true iff this is a null principal (corresponding to an
 462      * unknown, hence assumed minimally privileged, security context).
 463      */
 464     [infallible] readonly attribute boolean isNullPrincipal;
 465
 466     /**
 467      * Returns true iff this principal corresponds to a principal origin.
 468      */
 469     [infallible] readonly attribute boolean isContentPrincipal;
 470
 471     /**
 472      * Returns true iff this is an expanded principal.
 473      */
 474     [infallible] readonly attribute boolean isExpandedPrincipal;
 475
 476     /**
 477      * Returns true iff this is the system principal.  C++ callers should use
 478      * IsSystemPrincipal() instead of this scriptable accessor.
 479      */
 480     readonly attribute boolean isSystemPrincipal;
 481
 482     /**
 483      * Faster and nicer version callable from C++.  Callers must include
 484      * BasePrincipal.h, where it's implemented.
 485      */
 486     %{C++
 487       inline bool IsSystemPrincipal() const;
 488     %}
 489
 490     /**
 491      * Returns true iff the principal is either an addon principal or
 492      * an expanded principal, which contains at least one addon principal.
 493      */
 494     [infallible] readonly attribute boolean isAddonOrExpandedAddonPrincipal;
 495
 496     %{C++
 497     // MOZ_DBG support
 498     friend std::ostream& operator<<(std::ostream& aOut, const nsIPrincipal& aPrincipal) {
 499       nsIPrincipal* principal = const_cast<nsIPrincipal*>(&aPrincipal);
 500       nsAutoCString origin;
 501       mozilla::DebugOnly<nsresult> rv = principal->GetOrigin(origin);
 502       MOZ_ASSERT(NS_SUCCEEDED(rv));
 503       return aOut << "nsIPrincipal { " << origin << " }";
 504     }
 505     %}
 506     /*
 507     * Returns true if the URI is an Onion URI
 508     */
 509     [infallible] readonly attribute boolean isOnion;
 510
 511     /*
 512      * Returns true if the Domain Policy allows js execution
 513      * for the Principals URI
 514      */
 515     readonly attribute boolean isScriptAllowedByPolicy;
 516
 517
 518      /*
 519      * Returns true if the Principal can acess l10n
 520      * features for the Provided DocumentURI
 521      */
 522     boolean isL10nAllowed(in nsIURI aDocumentURI);
 523
 524     /**
 525     * Returns a nsIPrincipal, with one less Subdomain Segment
 526     * Returns `nullptr` if there are no more segments to remove.
 527     */
 528
 529     [infallible] readonly attribute nsIPrincipal nextSubDomainPrincipal;
 530
 531     /**
 532      * Returns if the principal is for an IP address.
 533      */
 534     [infallible] readonly attribute boolean isIpAddress;
 535
 536     /**
 537      * Returns if the principal is for a local IP address.
 538      */
 539     [infallible] readonly attribute boolean isLocalIpAddress;
 540
 541 };
 542
 543 /**
 544  * If SystemPrincipal is too risky to use, but we want a principal to access
 545  * more than one origin, ExpandedPrincipals letting us define an array of
 546  * principals it subsumes. So script with an ExpandedPrincipals will gain
 547  * same origin access when at least one of its principals it contains gained
 548  * sameorigin acccess. An ExpandedPrincipal will be subsumed by the system
 549  * principal, and by another ExpandedPrincipal that has all its principals.
 550  * It is added for jetpack content-scripts to let them interact with the
 551  * content and a well defined set of other domains, without the risk of
 552  * leaking out a system principal to the content. See: Bug 734891
 553  */
 554 [uuid(f3e177Df-6a5e-489f-80a7-2dd1481471d8)]
 555 interface nsIExpandedPrincipal : nsISupports
 556 {
 557   /**
 558    * An array of principals that the expanded principal subsumes.
 559    *
 560    * When an expanded principal is used as a triggering principal for a
 561    * request that inherits a security context, one of its constitutent
 562    * principals is inherited rather than the expanded principal itself. The
 563    * last principal in the allowlist is the default principal to inherit.
 564    *
 565    * Note: this list is not reference counted, it is shared, so
 566    * should not be changed and should only be used ephemerally.
 567    */
 568   [noscript, notxpcom, nostdcall]
 569   PrincipalArray AllowList();
 570
 571
 572   /**
 573    * Bug 1548468: Move CSP off ExpandedPrincipal.
 574    *
 575    * A Content Security Policy associated with this principal. Use this function
 576    * to query the associated CSP with this principal.
 577    */
 578   readonly attribute nsIContentSecurityPolicy csp;
 579
 580 %{ C++
 581   inline already_AddRefed<nsIContentSecurityPolicy> GetCsp()
 582   {
 583     nsCOMPtr<nsIContentSecurityPolicy> result;
 584     mozilla::DebugOnly<nsresult> rv = GetCsp(getter_AddRefs(result));
 585     MOZ_ASSERT(NS_SUCCEEDED(rv));
 586     return result.forget();
 587   }
 588 %}
 589
 590 };