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