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      * Check if the Principal's URI is contained in the given list
 325      * @param list The list to be checked
 326      */
 327     [infallible]
 328     boolean isURIInList(in ACString list);
 329
 330     /*
 331     * Uses NS_Security Compare to determine if the
 332     * other URI is same-origin as the uri of the Principal
 333     */
 334     [infallible]
 335     boolean isSameOrigin(in nsIURI otherURI);
 336
 337     /*
 338     * Checks if the Principal is allowed to load the Provided file:// URI
 339     * using NS_RelaxStrictFileOriginPolicy
 340     */
 341     bool allowsRelaxStrictFileOriginPolicy(in nsIURI aURI);
 342
 343
 344     /*
 345     *  Generates a Cache-Key for the Cors-Preflight Cache
 346     */
 347     [noscript]
 348     ACString getPrefLightCacheKey(in nsIURI aURI ,in bool aWithCredentials,
 349                                   in const_OriginAttributes aOriginAttributes);
 350
 351
 352     /*
 353     *  Checks if the Principals URI has first party storage access
 354     *  when loaded inside the provided 3rd party resource window.
 355     *  See also: ContentBlocking::ShouldAllowAccessFor
 356     */
 357     bool hasFirstpartyStorageAccess(in mozIDOMWindow aWindow, out uint32_t rejectedReason);
 358
 359
 360     /*
 361     * Returns a Key for the LocalStorage Manager, used to
 362     * check the Principals Origin Storage usage.
 363     */
 364     readonly attribute ACString localStorageQuotaKey;
 365
 366     /**
 367      * Implementation of
 368      * https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy
 369      *
 370      * The value returned by this method feeds into the the Secure Context
 371      * algorithm that determins the value of Window.isSecureContext and
 372      * WorkerGlobalScope.isSecureContext.
 373      *
 374      * This method returns false instead of throwing upon errors.
 375      */
 376     [infallible]
 377     readonly attribute boolean isOriginPotentiallyTrustworthy;
 378
 379     /**
 380      * Returns the Flags of the Principals
 381      * associated AboutModule, in case there is one.
 382      */
 383     uint32_t getAboutModuleFlags();
 384
 385     /*
 386     * Returns the Key to access the Principals
 387     * Origin Local/Session Storage
 388     */
 389     readonly attribute ACString storageOriginKey;
 390
 391     /**
 392      * Creates and Returns a new ReferrerInfo with the
 393      * Principals URI
 394      */
 395     nsIReferrerInfo createReferrerInfo(in ReferrerPolicy aReferrerPolicy);
 396
 397     /**
 398      * The base part of |origin| without the concatenation with |originSuffix|.
 399      * This doesn't have the important invariants described above with |origin|,
 400      * and as such should only be used for legacy situations.
 401      */
 402     readonly attribute ACString originNoSuffix;
 403
 404     /**
 405      * A string of the form ^key1=value1&key2=value2, where each pair represents
 406      * an attribute with a non-default value. If all attributes have default
 407      * values, this is the empty string.
 408      *
 409      * The value of .originSuffix is automatically serialized into .origin, so any
 410      * consumers using that are automatically origin-attribute-aware. Consumers with
 411      * special requirements must inspect and compare .originSuffix manually.
 412      */
 413     readonly attribute AUTF8String originSuffix;
 414
 415     /**
 416      * A canonical representation of the site-origin for this principal.
 417      * This string has the same format as |origin| (see above). Two principals
 418      * with differing |siteOrigin| values will never compare equal, even when
 419      * considering domain mutations.
 420      *
 421      * For most principals, |siteOrigin| matches |origin| precisely. Only
 422      * principals which allow mutating |domain|, such as ContentPrincipal,
 423      * override the default implementation in BasePrincipal.
 424      */
 425     readonly attribute ACString siteOrigin;
 426
 427     /**
 428      * The base part of |siteOrigin| without the concatenation with
 429      * |originSuffix|.
 430      */
 431     readonly attribute ACString siteOriginNoSuffix;
 432
 433     /**
 434      * The base domain of the principal URI to which this principal pertains
 435      * (generally the document URI), handling null principals and
 436      * non-hierarchical schemes correctly.
 437      */
 438     readonly attribute ACString baseDomain;
 439
 440     /**
 441      * Gets the ID of the add-on this principal belongs to.
 442      */
 443     readonly attribute AString addonId;
 444
 445     readonly attribute WebExtensionPolicy addonPolicy;
 446
 447     /**
 448      * Gets the id of the user context this principal is inside.  If this
 449      * principal is inside the default userContext, this returns
 450      * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID.
 451      */
 452     [infallible] readonly attribute unsigned long userContextId;
 453
 454     /**
 455      * Gets the id of the private browsing state of the context containing
 456      * this principal. If the principal has a private browsing value of 0, it
 457      * is not in private browsing.
 458      */
 459     [infallible] readonly attribute unsigned long privateBrowsingId;
 460
 461     /**
 462      * Returns true iff the principal is inside an isolated mozbrowser element.
 463      * <xul:browser> is not considered to be a mozbrowser element.
 464      * <iframe mozbrowser noisolation> does not count as isolated since
 465      * isolation is disabled.  Isolation can only be disabled if the
 466      * containing document is chrome.
 467      */
 468     [infallible] readonly attribute boolean isInIsolatedMozBrowserElement;
 469
 470     /**
 471      * Returns true iff this is a null principal (corresponding to an
 472      * unknown, hence assumed minimally privileged, security context).
 473      */
 474     [infallible] readonly attribute boolean isNullPrincipal;
 475
 476     /**
 477      * Returns true iff this principal corresponds to a principal origin.
 478      */
 479     [infallible] readonly attribute boolean isContentPrincipal;
 480
 481     /**
 482      * Returns true iff this is an expanded principal.
 483      */
 484     [infallible] readonly attribute boolean isExpandedPrincipal;
 485
 486     /**
 487      * Returns true iff this is the system principal.  C++ callers should use
 488      * IsSystemPrincipal() instead of this scriptable accessor.
 489      */
 490     readonly attribute boolean isSystemPrincipal;
 491
 492     /**
 493      * Faster and nicer version callable from C++.  Callers must include
 494      * BasePrincipal.h, where it's implemented.
 495      */
 496     %{C++
 497       inline bool IsSystemPrincipal() const;
 498     %}
 499
 500     /**
 501      * Returns true iff the principal is either an addon principal or
 502      * an expanded principal, which contains at least one addon principal.
 503      */
 504     [infallible] readonly attribute boolean isAddonOrExpandedAddonPrincipal;
 505
 506     %{C++
 507     // MOZ_DBG support
 508     friend std::ostream& operator<<(std::ostream& aOut, const nsIPrincipal& aPrincipal) {
 509       nsIPrincipal* principal = const_cast<nsIPrincipal*>(&aPrincipal);
 510       nsAutoCString origin;
 511       mozilla::DebugOnly<nsresult> rv = principal->GetOrigin(origin);
 512       MOZ_ASSERT(NS_SUCCEEDED(rv));
 513       return aOut << "nsIPrincipal { " << origin << " }";
 514     }
 515     %}
 516     /*
 517     * Returns true if the URI is an Onion URI
 518     */
 519     [infallible] readonly attribute boolean isOnion;
 520
 521     /*
 522      * Returns true if the Domain Policy allows js execution
 523      * for the Principals URI
 524      */
 525     readonly attribute boolean isScriptAllowedByPolicy;
 526
 527
 528      /*
 529      * Returns true if the Principal can acess l10n
 530      * features for the Provided DocumentURI
 531      */
 532     boolean isL10nAllowed(in nsIURI aDocumentURI);
 533
 534     /**
 535     * Returns a nsIPrincipal, with one less Subdomain Segment
 536     * Returns `nullptr` if there are no more segments to remove.
 537     */
 538
 539     [infallible] readonly attribute nsIPrincipal nextSubDomainPrincipal;
 540
 541     /**
 542      * Returns if the principal is for an IP address.
 543      */
 544     [infallible] readonly attribute boolean isIpAddress;
 545
 546     /**
 547      * Returns if the principal is for a local IP address.
 548      */
 549     [infallible] readonly attribute boolean isLocalIpAddress;
 550
 551     /**
 552      * If this principal is a null principal, reconstruct the precursor
 553      * principal which this null principal was derived from. This may be null,
 554      * in which case this is not a null principal, there is no known precursor
 555      * to this null principal, it was created by a privileged context, or there
 556      * was a bugged origin in the precursor string.
 557      *
 558      * WARNING: Be careful when using this principal, as it is not part of the
 559      * security properties of the null principal, and should NOT be used to
 560      * grant a resource with a null principal access to resources from its
 561      * precursor origin. This is only to be used for places where tracking how
 562      * null principals were created is necessary.
 563      */
 564     [infallible] readonly attribute nsIPrincipal precursorPrincipal;
 565 };
 566
 567 /**
 568  * If SystemPrincipal is too risky to use, but we want a principal to access
 569  * more than one origin, ExpandedPrincipals letting us define an array of
 570  * principals it subsumes. So script with an ExpandedPrincipals will gain
 571  * same origin access when at least one of its principals it contains gained
 572  * sameorigin acccess. An ExpandedPrincipal will be subsumed by the system
 573  * principal, and by another ExpandedPrincipal that has all its principals.
 574  * It is added for jetpack content-scripts to let them interact with the
 575  * content and a well defined set of other domains, without the risk of
 576  * leaking out a system principal to the content. See: Bug 734891
 577  */
 578 [uuid(f3e177Df-6a5e-489f-80a7-2dd1481471d8)]
 579 interface nsIExpandedPrincipal : nsISupports
 580 {
 581   /**
 582    * An array of principals that the expanded principal subsumes.
 583    *
 584    * When an expanded principal is used as a triggering principal for a
 585    * request that inherits a security context, one of its constitutent
 586    * principals is inherited rather than the expanded principal itself. The
 587    * last principal in the allowlist is the default principal to inherit.
 588    *
 589    * Note: this list is not reference counted, it is shared, so
 590    * should not be changed and should only be used ephemerally.
 591    */
 592   [noscript, notxpcom, nostdcall]
 593   PrincipalArray AllowList();
 594
 595
 596   /**
 597    * Bug 1548468: Move CSP off ExpandedPrincipal.
 598    *
 599    * A Content Security Policy associated with this principal. Use this function
 600    * to query the associated CSP with this principal.
 601    */
 602   readonly attribute nsIContentSecurityPolicy csp;
 603
 604 %{ C++
 605   inline already_AddRefed<nsIContentSecurityPolicy> GetCsp()
 606   {
 607     nsCOMPtr<nsIContentSecurityPolicy> result;
 608     mozilla::DebugOnly<nsresult> rv = GetCsp(getter_AddRefs(result));
 609     MOZ_ASSERT(NS_SUCCEEDED(rv));
 610     return result.forget();
 611   }
 612 %}
 613
 614 };