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
  12 %{C++
  13 struct JSPrincipals;
  14 #include "nsCOMPtr.h"
  15 #include "nsTArray.h"
  16 #include "nsString.h"
  17 #include "mozilla/DebugOnly.h"
  18 namespace mozilla {
  19 class OriginAttributes;
  20 }
  21
  22 /**
  23  * Some methods have a fast path for the case when we're comparing a principal
  24  * to itself. The situation may happen for example with about:blank documents.
  25  */
  26
  27 #define DECL_FAST_INLINE_HELPER(method_)                       \
  28   inline bool method_(nsIPrincipal* aOther)                    \
  29   {                                                            \
  30     mozilla::DebugOnly<bool> val = false;                      \
  31     MOZ_ASSERT_IF(this == aOther,                              \
  32                   NS_SUCCEEDED(method_(aOther, &val)) && val); \
  33                                                                \
  34     bool retVal = false;                                       \
  35     return                                                     \
  36       this == aOther ||                                        \
  37       (NS_SUCCEEDED(method_(aOther, &retVal)) && retVal);      \
  38   }
  39
  40 %}
  41
  42 interface nsIURI;
  43
  44 [ptr] native JSContext(JSContext);
  45 [ptr] native JSPrincipals(JSPrincipals);
  46 [ref] native PrincipalArray(const nsTArray<nsCOMPtr<nsIPrincipal>>);
  47 [ref] native const_OriginAttributes(const mozilla::OriginAttributes);
  48
  49 [scriptable, builtinclass, uuid(f75f502d-79fd-48be-a079-e5a7b8f80c8b)]
  50 interface nsIPrincipal : nsISerializable
  51 {
  52     /**
  53      * Returns whether the other principal is equivalent to this principal.
  54      * Principals are considered equal if they are the same principal, or
  55      * they have the same origin.
  56      */
  57     boolean equals(in nsIPrincipal other);
  58
  59     /**
  60      * Like equals, but takes document.domain changes into account.
  61      */
  62     boolean equalsConsideringDomain(in nsIPrincipal other);
  63
  64     %{C++
  65       DECL_FAST_INLINE_HELPER(Equals)
  66       DECL_FAST_INLINE_HELPER(EqualsConsideringDomain)
  67     %}
  68
  69     /**
  70      * Returns a hash value for the principal.
  71      */
  72     [notxpcom, nostdcall] readonly attribute unsigned long hashValue;
  73
  74     /**
  75      * The principal URI to which this principal pertains.  This is
  76      * generally the document URI.
  77      */
  78     [infallible] readonly attribute nsIURI URI;
  79
  80     /**
  81      * The domain URI to which this principal pertains.
  82      * This is null unless script successfully sets document.domain to our URI
  83      * or a superdomain of our URI.
  84      * Setting this has no effect on the URI.
  85      * See https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#Changing_origin
  86      */
  87     [noscript] attribute nsIURI domain;
  88
  89     /**
  90      * Returns whether the other principal is equal to or weaker than this
  91      * principal. Principals are equal if they are the same object or they
  92      * have the same origin.
  93      *
  94      * Thus a principal always subsumes itself.
  95      *
  96      * The system principal subsumes itself and all other principals.
  97      *
  98      * A null principal (corresponding to an unknown, hence assumed minimally
  99      * privileged, security context) is not equal to any other principal
 100      * (including other null principals), and therefore does not subsume
 101      * anything but itself.
 102      */
 103     boolean subsumes(in nsIPrincipal other);
 104
 105     /**
 106      * Same as the previous method, subsumes(), but takes document.domain into
 107      * account.
 108      */
 109     boolean subsumesConsideringDomain(in nsIPrincipal other);
 110
 111     /**
 112      * Same as the subsumesConsideringDomain(), but ignores the first party
 113      * domain in its originAttributes.
 114      */
 115     boolean subsumesConsideringDomainIgnoringFPD(in nsIPrincipal other);
 116
 117     %{C++
 118       DECL_FAST_INLINE_HELPER(Subsumes)
 119       DECL_FAST_INLINE_HELPER(SubsumesConsideringDomain)
 120       DECL_FAST_INLINE_HELPER(SubsumesConsideringDomainIgnoringFPD)
 121 #undef DECL_FAST_INLINE_HELPER
 122     %}
 123
 124     /**
 125      * Checks whether this principal is allowed to load the network resource
 126      * located at the given URI under the same-origin policy. This means that
 127      * content principals are only allowed to load resources from the same
 128      * domain, the system principal is allowed to load anything, and null
 129      * principals can only load URIs where they are the principal. This is
 130      * changed by the optional flag allowIfInheritsPrincipal (which defaults to
 131      * false) which allows URIs that inherit their loader's principal.
 132      *
 133      * If the load is allowed this function does nothing. If the load is not
 134      * allowed the function throws NS_ERROR_DOM_BAD_URI.
 135      *
 136      * NOTE: Other policies might override this, such as the Access-Control
 137      *       specification.
 138      * NOTE: The 'domain' attribute has no effect on the behaviour of this
 139      *       function.
 140      *
 141      *
 142      * @param uri    The URI about to be loaded.
 143      * @param report If true, will report a warning to the console service
 144      *               if the load is not allowed.
 145      * @param allowIfInheritsPrincipal   If true, the load is allowed if the
 146      *                                   loadee inherits the principal of the
 147      *                                   loader.
 148      * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed.
 149      */
 150     void checkMayLoad(in nsIURI uri, in boolean report,
 151                       in boolean allowIfInheritsPrincipal);
 152
 153     /**
 154     * Checks if the provided URI is concidered third-party to the
 155     * URI of the principal.
 156     * Returns true if the URI is third-party.
 157     *
 158     * @param uri - The URI to check
 159     */
 160     boolean isThirdPartyURI(in nsIURI uri);
 161
 162     /**
 163     * Checks if the provided principal is concidered third-party to the
 164     * URI of the Principal.
 165     * Returns true if the principal is third-party.
 166     *
 167     * @param principal - The principal to check
 168     */
 169     boolean isThirdPartyPrincipal(in nsIPrincipal principal);
 170
 171     /**
 172      * A dictionary of the non-default origin attributes associated with this
 173      * nsIPrincipal.
 174      *
 175      * Attributes are tokens that are taken into account when determining whether
 176      * two principals are same-origin - if any attributes differ, the principals
 177      * are cross-origin, even if the scheme, host, and port are the same.
 178      * Attributes should also be considered for all security and bucketing decisions,
 179      * even those which make non-standard comparisons (like cookies, which ignore
 180      * scheme, or quotas, which ignore subdomains).
 181      *
 182      * If you're looking for an easy-to-use canonical stringification of the origin
 183      * attributes, see |originSuffix| below.
 184      */
 185     [implicit_jscontext]
 186     readonly attribute jsval originAttributes;
 187
 188     [noscript, notxpcom, nostdcall, binaryname(OriginAttributesRef)]
 189     const_OriginAttributes OriginAttributesRef();
 190
 191     /**
 192      * A canonical representation of the origin for this principal. This
 193      * consists of a base string (which, for content principals, is of the
 194      * format scheme://host:port), concatenated with |originAttributes| (see
 195      * below).
 196      *
 197      * We maintain the invariant that principalA.equals(principalB) if and only
 198      * if principalA.origin == principalB.origin.
 199      */
 200     readonly attribute ACString origin;
 201
 202     /**
 203       * Returns the ASCII Spec from the Principals URI.
 204       * Might return the empty string, e.g. for the case of
 205       * a SystemPrincipal or an EpxandedPrincipal.
 206       *
 207       * WARNING: DO NOT USE FOR SECURITY CHECKS.
 208       * just for logging purposes!
 209      */
 210      readonly attribute ACString AsciiSpec;
 211
 212     /**
 213     * Checks if the Principal's URI Scheme matches with the parameter
 214     *
 215     * @param scheme    The scheme to be checked
 216     */
 217     boolean schemeIs(in string scheme);
 218
 219     // Nicer, C++ Callable Version of SchemeIs
 220     %{C++
 221       inline bool SchemeIs(const char* aScheme) {
 222         bool ret;
 223         SchemeIs(aScheme, &ret);
 224         return ret;
 225       }
 226     %}
 227
 228     /**
 229      * Returns the Flags of the Principals
 230      * associated AboutModule, in case there is one.
 231      */
 232     uint32_t GetAboutModuleFlags();
 233
 234     /**
 235      * The base part of |origin| without the concatenation with |originSuffix|.
 236      * This doesn't have the important invariants described above with |origin|,
 237      * and as such should only be used for legacy situations.
 238      */
 239     readonly attribute ACString originNoSuffix;
 240
 241     /**
 242      * A string of the form !key1=value1&key2=value2, where each pair represents
 243      * an attribute with a non-default value. If all attributes have default
 244      * values, this is the empty string.
 245      *
 246      * The value of .originSuffix is automatically serialized into .origin, so any
 247      * consumers using that are automatically origin-attribute-aware. Consumers with
 248      * special requirements must inspect and compare .originSuffix manually.
 249      */
 250     readonly attribute AUTF8String originSuffix;
 251
 252     /**
 253      * A canonical representation of the site-origin for this principal.
 254      * This string has the same format as |origin| (see above). Two principals
 255      * with differing |siteOrigin| values will never compare equal, even when
 256      * considering domain mutations.
 257      *
 258      * For most principals, |siteOrigin| matches |origin| precisely. Only
 259      * principals which allow mutating |domain|, such as ContentPrincipal,
 260      * override the default implementation in BasePrincipal.
 261      *
 262      * TODO(nika): Use this in DocGroup.
 263      */
 264     readonly attribute ACString siteOrigin;
 265
 266     /**
 267      * The base domain of the principal URI to which this principal pertains
 268      * (generally the document URI), handling null principals and
 269      * non-hierarchical schemes correctly.
 270      */
 271     readonly attribute ACString baseDomain;
 272
 273     /**
 274      * Gets the ID of the add-on this principal belongs to.
 275      */
 276     readonly attribute AString addonId;
 277
 278     readonly attribute nsISupports addonPolicy;
 279
 280     /**
 281      * Gets the id of the user context this principal is inside.  If this
 282      * principal is inside the default userContext, this returns
 283      * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID.
 284      */
 285     [infallible] readonly attribute unsigned long userContextId;
 286
 287     /**
 288      * Gets the id of the private browsing state of the context containing
 289      * this principal. If the principal has a private browsing value of 0, it
 290      * is not in private browsing.
 291      */
 292     [infallible] readonly attribute unsigned long privateBrowsingId;
 293
 294     /**
 295      * Returns true iff the principal is inside an isolated mozbrowser element.
 296      * <xul:browser> is not considered to be a mozbrowser element.
 297      * <iframe mozbrowser noisolation> does not count as isolated since
 298      * isolation is disabled.  Isolation can only be disabled if the
 299      * containing document is chrome.
 300      */
 301     [infallible] readonly attribute boolean isInIsolatedMozBrowserElement;
 302
 303     /**
 304      * Returns true iff this is a null principal (corresponding to an
 305      * unknown, hence assumed minimally privileged, security context).
 306      */
 307     [infallible] readonly attribute boolean isNullPrincipal;
 308
 309     /**
 310      * Returns true iff this principal corresponds to a principal origin.
 311      */
 312     [infallible] readonly attribute boolean isContentPrincipal;
 313
 314     /**
 315      * Returns true iff this is an expanded principal.
 316      */
 317     [infallible] readonly attribute boolean isExpandedPrincipal;
 318
 319     /**
 320      * Returns true iff this is the system principal.  C++ callers should use
 321      * IsSystemPrincipal() instead of this scriptable accessor.
 322      */
 323     readonly attribute boolean isSystemPrincipal;
 324
 325     /**
 326      * Faster and nicer version callable from C++.  Callers must include
 327      * BasePrincipal.h, where it's implemented.
 328      */
 329     %{C++
 330       inline bool IsSystemPrincipal() const;
 331     %}
 332
 333     /**
 334      * Returns true iff the principal is either an addon principal or
 335      * an expanded principal, which contains at least one addon principal.
 336      */
 337     [infallible] readonly attribute boolean isAddonOrExpandedAddonPrincipal;
 338
 339     %{C++
 340     // MOZ_DBG support
 341     friend std::ostream& operator<<(std::ostream& aOut, const nsIPrincipal& aPrincipal) {
 342       nsIPrincipal* principal = const_cast<nsIPrincipal*>(&aPrincipal);
 343       nsAutoCString origin;
 344       mozilla::DebugOnly<nsresult> rv = principal->GetOrigin(origin);
 345       MOZ_ASSERT(NS_SUCCEEDED(rv));
 346       return aOut << "nsIPrincipal { " << origin << " }";
 347     }
 348     %}
 349 };
 350
 351 /**
 352  * If SystemPrincipal is too risky to use, but we want a principal to access
 353  * more than one origin, ExpandedPrincipals letting us define an array of
 354  * principals it subsumes. So script with an ExpandedPrincipals will gain
 355  * same origin access when at least one of its principals it contains gained
 356  * sameorigin acccess. An ExpandedPrincipal will be subsumed by the system
 357  * principal, and by another ExpandedPrincipal that has all its principals.
 358  * It is added for jetpack content-scripts to let them interact with the
 359  * content and a well defined set of other domains, without the risk of
 360  * leaking out a system principal to the content. See: Bug 734891
 361  */
 362 [uuid(f3e177Df-6a5e-489f-80a7-2dd1481471d8)]
 363 interface nsIExpandedPrincipal : nsISupports
 364 {
 365   /**
 366    * An array of principals that the expanded principal subsumes.
 367    *
 368    * When an expanded principal is used as a triggering principal for a
 369    * request that inherits a security context, one of its constitutent
 370    * principals is inherited rather than the expanded principal itself. The
 371    * last principal in the allowlist is the default principal to inherit.
 372    *
 373    * Note: this list is not reference counted, it is shared, so
 374    * should not be changed and should only be used ephemerally.
 375    */
 376   [noscript, notxpcom, nostdcall]
 377   PrincipalArray AllowList();
 378
 379
 380   /**
 381    * Bug 1548468: Move CSP off ExpandedPrincipal.
 382    *
 383    * A Content Security Policy associated with this principal. Use this function
 384    * to query the associated CSP with this principal.
 385    */
 386   readonly attribute nsIContentSecurityPolicy csp;
 387
 388 %{ C++
 389   inline already_AddRefed<nsIContentSecurityPolicy> GetCsp()
 390   {
 391     nsCOMPtr<nsIContentSecurityPolicy> result;
 392     mozilla::DebugOnly<nsresult> rv = GetCsp(getter_AddRefs(result));
 393     MOZ_ASSERT(NS_SUCCEEDED(rv));
 394     return result.forget();
 395   }
 396 %}
 397
 398 };