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 "nsISerializable.idl"
   9
  10 %{C++
  11 struct JSPrincipals;
  12 #include "nsCOMPtr.h"
  13 #include "nsTArray.h"
  14 #include "mozilla/DebugOnly.h"
  15 namespace mozilla {
  16 class OriginAttributes;
  17 }
  18
  19 /**
  20  * Some methods have a fast path for the case when we're comparing a principal
  21  * to itself. The situation may happen for example with about:blank documents.
  22  */
  23
  24 #define DECL_FAST_INLINE_HELPER(method_)                       \
  25   inline bool method_(nsIPrincipal* aOther)                    \
  26   {                                                            \
  27     mozilla::DebugOnly<bool> val = false;                      \
  28     MOZ_ASSERT_IF(this == aOther,                              \
  29                   NS_SUCCEEDED(method_(aOther, &val)) && val); \
  30                                                                \
  31     bool retVal = false;                                       \
  32     return                                                     \
  33       this == aOther ||                                        \
  34       (NS_SUCCEEDED(method_(aOther, &retVal)) && retVal);      \
  35   }
  36
  37 %}
  38
  39 interface nsIURI;
  40 interface nsIContentSecurityPolicy;
  41
  42 webidl Document;
  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 codebase 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      * codebase 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      * A Content Security Policy associated with this principal. Use this function to
 155      * query the associated CSP with this principal, but please *only* use this
 156      * function to *set* a CSP when you know exactly what you are doing.
 157      * Most likely you want to call ensureCSP instead of setCSP.
 158      */
 159     readonly attribute nsIContentSecurityPolicy csp;
 160     [noscript] void setCsp(in nsIContentSecurityPolicy aCsp);
 161
 162     /*
 163      * Use this function to query a CSP associated with this principal.
 164      * If no CSP is associated with this principal then one is created
 165      * internally and setRequestContext is called on the CSP using aDocument.
 166      *
 167      * Please note if aDocument is null, then setRequestContext on the
 168      * CSP object is called using the current principal.
 169      */
 170     [noscript] nsIContentSecurityPolicy ensureCSP(in Document aDocument);
 171
 172     /**
 173      * A speculative Content Security Policy associated with this
 174      * principal. Set during speculative loading (preloading) and
 175      * used *only* for preloads.
 176      *
 177      * If you want to query the CSP associated with that principal,
 178      * then this is *not* what you want. Instead query 'csp'.
 179      */
 180     [noscript] readonly attribute nsIContentSecurityPolicy preloadCsp;
 181
 182     /*
 183      * Use this function to query a speculative CSP associated with this
 184      * principal. If no speculative CSP is associated with this principal
 185      * then one is created internally and setRequestContext is called on
 186      * the CSP using aDocument.
 187      *
 188      * Please note if aDocument is null, then setRequestContext on the
 189      * speculative CSP object is called using the current principal.
 190      */
 191     [noscript] nsIContentSecurityPolicy ensurePreloadCSP(in Document aDocument);
 192
 193     /**
 194      * The CSP of the principal in JSON notation.
 195      * Note, that the CSP itself is not exposed to JS, but script
 196      * should be able to obtain a JSON representation of the CSP.
 197      */
 198     readonly attribute AString cspJSON;
 199
 200     /**
 201      * A dictionary of the non-default origin attributes associated with this
 202      * nsIPrincipal.
 203      *
 204      * Attributes are tokens that are taken into account when determining whether
 205      * two principals are same-origin - if any attributes differ, the principals
 206      * are cross-origin, even if the scheme, host, and port are the same.
 207      * Attributes should also be considered for all security and bucketing decisions,
 208      * even those which make non-standard comparisons (like cookies, which ignore
 209      * scheme, or quotas, which ignore subdomains).
 210      *
 211      * If you're looking for an easy-to-use canonical stringification of the origin
 212      * attributes, see |originSuffix| below.
 213      */
 214     [implicit_jscontext]
 215     readonly attribute jsval originAttributes;
 216
 217     [noscript, notxpcom, nostdcall, binaryname(OriginAttributesRef)]
 218     const_OriginAttributes OriginAttributesRef();
 219
 220     /**
 221      * A canonical representation of the origin for this principal. This
 222      * consists of a base string (which, for codebase principals, is of the
 223      * format scheme://host:port), concatenated with |originAttributes| (see
 224      * below).
 225      *
 226      * We maintain the invariant that principalA.equals(principalB) if and only
 227      * if principalA.origin == principalB.origin.
 228      */
 229     readonly attribute ACString origin;
 230
 231     /**
 232      * The base part of |origin| without the concatenation with |originSuffix|.
 233      * This doesn't have the important invariants described above with |origin|,
 234      * and as such should only be used for legacy situations.
 235      */
 236     readonly attribute ACString originNoSuffix;
 237
 238     /**
 239      * A string of the form !key1=value1&key2=value2, where each pair represents
 240      * an attribute with a non-default value. If all attributes have default
 241      * values, this is the empty string.
 242      *
 243      * The value of .originSuffix is automatically serialized into .origin, so any
 244      * consumers using that are automatically origin-attribute-aware. Consumers with
 245      * special requirements must inspect and compare .originSuffix manually.
 246      */
 247     readonly attribute AUTF8String originSuffix;
 248
 249     /**
 250      * A canonical representation of the site-origin for this principal.
 251      * This string has the same format as |origin| (see above). Two principals
 252      * with differing |siteOrigin| values will never compare equal, even when
 253      * considering domain mutations.
 254      *
 255      * For most principals, |siteOrigin| matches |origin| precisely. Only
 256      * principals which allow mutating |domain|, such as ContentPrincipal,
 257      * override the default implementation in BasePrincipal.
 258      *
 259      * TODO(nika): Use this in DocGroup.
 260      */
 261     readonly attribute ACString siteOrigin;
 262
 263     /**
 264      * The base domain of the codebase URI to which this principal pertains
 265      * (generally the document URI), handling null principals and
 266      * non-hierarchical schemes correctly.
 267      */
 268     readonly attribute ACString baseDomain;
 269
 270     /**
 271      * Gets the id of the app this principal is inside.  If this principal is
 272      * not inside an app, returns nsIScriptSecurityManager::NO_APP_ID.
 273      *
 274      * Note that this principal does not necessarily have the permissions of
 275      * the app identified by appId.  For example, this principal might
 276      * correspond to an iframe whose origin differs from that of the app frame
 277      * containing it.  In this case, the iframe will have the appId of its
 278      * containing app frame, but the iframe must not run with the app's
 279      * permissions.
 280      *
 281      * Similarly, this principal might correspond to an <iframe mozbrowser>
 282      * inside an app frame; in this case, the content inside the iframe should
 283      * not have any of the app's permissions, even if the iframe is at the same
 284      * origin as the app.
 285      */
 286     [infallible] readonly attribute unsigned long appId;
 287
 288     /**
 289      * Gets the ID of the add-on this principal belongs to.
 290      */
 291     readonly attribute AString addonId;
 292
 293     readonly attribute nsISupports addonPolicy;
 294
 295     /**
 296      * Gets the id of the user context this principal is inside.  If this
 297      * principal is inside the default userContext, this returns
 298      * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID.
 299      */
 300     [infallible] readonly attribute unsigned long userContextId;
 301
 302     /**
 303      * Gets the id of the private browsing state of the context containing
 304      * this principal. If the principal has a private browsing value of 0, it
 305      * is not in private browsing.
 306      */
 307     [infallible] readonly attribute unsigned long privateBrowsingId;
 308
 309     /**
 310      * Returns true iff the principal is inside an isolated mozbrowser element.
 311      * <xul:browser> is not considered to be a mozbrowser element.
 312      * <iframe mozbrowser noisolation> does not count as isolated since
 313      * isolation is disabled.  Isolation can only be disabled if the
 314      * containing document is chrome.
 315      */
 316     [infallible] readonly attribute boolean isInIsolatedMozBrowserElement;
 317
 318     /**
 319      * Returns true iff this is a null principal (corresponding to an
 320      * unknown, hence assumed minimally privileged, security context).
 321      */
 322     [infallible] readonly attribute boolean isNullPrincipal;
 323
 324     /**
 325      * Returns true iff this principal corresponds to a codebase origin.
 326      */
 327     [infallible] readonly attribute boolean isCodebasePrincipal;
 328
 329     /**
 330      * Returns true iff this is an expanded principal.
 331      */
 332     [infallible] readonly attribute boolean isExpandedPrincipal;
 333
 334     /**
 335      * Returns true iff this is the system principal.  C++ callers should use
 336      * IsSystemPrincipal() instead of this scriptable accessor.
 337      */
 338     readonly attribute boolean isSystemPrincipal;
 339
 340     /**
 341      * Faster and nicer version callable from C++.  Callers must include
 342      * BasePrincipal.h, where it's implemented.
 343      */
 344     %{C++
 345       inline bool IsSystemPrincipal() const;
 346     %}
 347
 348     /**
 349      * Returns true iff the principal is either an addon principal or
 350      * an expanded principal, which contains at least one addon principal.
 351      */
 352     [infallible] readonly attribute boolean isAddonOrExpandedAddonPrincipal;
 353 };
 354
 355 /**
 356  * If SystemPrincipal is too risky to use, but we want a principal to access
 357  * more than one origin, ExpandedPrincipals letting us define an array of
 358  * principals it subsumes. So script with an ExpandedPrincipals will gain
 359  * same origin access when at least one of its principals it contains gained
 360  * sameorigin acccess. An ExpandedPrincipal will be subsumed by the system
 361  * principal, and by another ExpandedPrincipal that has all its principals.
 362  * It is added for jetpack content-scripts to let them interact with the
 363  * content and a well defined set of other domains, without the risk of
 364  * leaking out a system principal to the content. See: Bug 734891
 365  */
 366 [uuid(f3e177Df-6a5e-489f-80a7-2dd1481471d8)]
 367 interface nsIExpandedPrincipal : nsISupports
 368 {
 369   /**
 370    * An array of principals that the expanded principal subsumes.
 371    *
 372    * When an expanded principal is used as a triggering principal for a
 373    * request that inherits a security context, one of its constitutent
 374    * principals is inherited rather than the expanded principal itself. The
 375    * last principal in the allowlist is the default principal to inherit.
 376    *
 377    * Note: this list is not reference counted, it is shared, so
 378    * should not be changed and should only be used ephemerally.
 379    */
 380   [noscript, notxpcom, nostdcall]
 381   PrincipalArray AllowList();
 382 };