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