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++ 11struct JSPrincipals; 12#include "nsCOMPtr.h" 13#include "nsTArray.h" 14%} 15 16interface nsIURI; 17interface nsIContentSecurityPolicy; 18interface nsIDOMDocument; 19 20[ptr] native JSContext(JSContext); 21[ptr] native JSPrincipals(JSPrincipals); 22[ptr] native PrincipalArray(nsTArray<nsCOMPtr<nsIPrincipal> >); 23 24[scriptable, builtinclass, uuid(3da7b133-f1a0-4de9-a2bc-5c49014c1077)] 25interface nsIPrincipal : nsISerializable 26{ 27 /** 28 * Returns whether the other principal is equivalent to this principal. 29 * Principals are considered equal if they are the same principal, or 30 * they have the same origin. 31 */ 32 boolean equals(in nsIPrincipal other); 33 34 /** 35 * Like equals, but takes document.domain changes into account. 36 */ 37 boolean equalsConsideringDomain(in nsIPrincipal other); 38 39 %{C++ 40 inline bool Equals(nsIPrincipal* aOther) { 41 bool equal = false; 42 return NS_SUCCEEDED(Equals(aOther, &equal)) && equal; 43 } 44 45 inline bool EqualsConsideringDomain(nsIPrincipal* aOther) { 46 bool equal = false; 47 return NS_SUCCEEDED(EqualsConsideringDomain(aOther, &equal)) && equal; 48 } 49 %} 50 51 /** 52 * Returns a hash value for the principal. 53 */ 54 [noscript] readonly attribute unsigned long hashValue; 55 56 /** 57 * The codebase URI to which this principal pertains. This is 58 * generally the document URI. 59 */ 60 readonly attribute nsIURI URI; 61 62 /** 63 * The domain URI to which this principal pertains. 64 * This is null unless script successfully sets document.domain to our URI 65 * or a superdomain of our URI. 66 * Setting this has no effect on the URI. 67 * See https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#Changing_origin 68 */ 69 [noscript] attribute nsIURI domain; 70 71 /** 72 * Returns whether the other principal is equal to or weaker than this 73 * principal. Principals are equal if they are the same object or they 74 * have the same origin. 75 * 76 * Thus a principal always subsumes itself. 77 * 78 * The system principal subsumes itself and all other principals. 79 * 80 * A null principal (corresponding to an unknown, hence assumed minimally 81 * privileged, security context) is not equal to any other principal 82 * (including other null principals), and therefore does not subsume 83 * anything but itself. 84 */ 85 boolean subsumes(in nsIPrincipal other); 86 87 /** 88 * Same as the previous method, subsumes(), but takes document.domain into 89 * account. 90 */ 91 boolean subsumesConsideringDomain(in nsIPrincipal other); 92 93 %{C++ 94 inline bool Subsumes(nsIPrincipal* aOther) { 95 bool subsumes = false; 96 return NS_SUCCEEDED(Subsumes(aOther, &subsumes)) && subsumes; 97 } 98 99 inline bool SubsumesConsideringDomain(nsIPrincipal* aOther) { 100 bool subsumes = false; 101 return NS_SUCCEEDED(SubsumesConsideringDomain(aOther, &subsumes)) && subsumes; 102 } 103 %} 104 105 /** 106 * Checks whether this principal is allowed to load the network resource 107 * located at the given URI under the same-origin policy. This means that 108 * codebase principals are only allowed to load resources from the same 109 * domain, the system principal is allowed to load anything, and null 110 * principals can only load URIs where they are the principal. This is 111 * changed by the optional flag allowIfInheritsPrincipal (which defaults to 112 * false) which allows URIs that inherit their loader's principal. 113 * 114 * If the load is allowed this function does nothing. If the load is not 115 * allowed the function throws NS_ERROR_DOM_BAD_URI. 116 * 117 * NOTE: Other policies might override this, such as the Access-Control 118 * specification. 119 * NOTE: The 'domain' attribute has no effect on the behaviour of this 120 * function. 121 * 122 * 123 * @param uri The URI about to be loaded. 124 * @param report If true, will report a warning to the console service 125 * if the load is not allowed. 126 * @param allowIfInheritsPrincipal If true, the load is allowed if the 127 * loadee inherits the principal of the 128 * loader. 129 * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed. 130 */ 131 void checkMayLoad(in nsIURI uri, in boolean report, 132 in boolean allowIfInheritsPrincipal); 133 134 /** 135 * A Content Security Policy associated with this principal. 136 * Use this function to query the associated CSP with this principal. 137 * Please *only* use this function to *set* a CSP when you know exactly what you are doing. 138 * Most likely you want to call ensureCSP instead of setCSP. 139 */ 140 [noscript] attribute nsIContentSecurityPolicy csp; 141 142 /* 143 * Use this function to query a CSP associated with this principal. 144 * If no CSP is associated with this principal then one is created 145 * internally and setRequestContext is called on the CSP using aDocument. 146 * 147 * Please note if aDocument is null, then setRequestContext on the 148 * CSP object is called using the current principal. 149 */ 150 [noscript] nsIContentSecurityPolicy ensureCSP(in nsIDOMDocument aDocument); 151 152 /** 153 * A speculative Content Security Policy associated with this 154 * principal. Set during speculative loading (preloading) and 155 * used *only* for preloads. 156 * 157 * If you want to query the CSP associated with that principal, 158 * then this is *not* what you want. Instead query 'csp'. 159 */ 160 [noscript] readonly attribute nsIContentSecurityPolicy preloadCsp; 161 162 /* 163 * Use this function to query a speculative CSP associated with this 164 * principal. If no speculative CSP is associated with this principal 165 * then one is created internally and setRequestContext is called on 166 * the CSP using aDocument. 167 * 168 * Please note if aDocument is null, then setRequestContext on the 169 * speculative CSP object is called using the current principal. 170 */ 171 [noscript] nsIContentSecurityPolicy ensurePreloadCSP(in nsIDOMDocument aDocument); 172 173 /** 174 * The CSP of the principal in JSON notation. 175 * Note, that the CSP itself is not exposed to JS, but script 176 * should be able to obtain a JSON representation of the CSP. 177 */ 178 readonly attribute AString cspJSON; 179 180 /** 181 * A dictionary of the non-default origin attributes associated with this 182 * nsIPrincipal. 183 * 184 * Attributes are tokens that are taken into account when determining whether 185 * two principals are same-origin - if any attributes differ, the principals 186 * are cross-origin, even if the scheme, host, and port are the same. 187 * Attributes should also be considered for all security and bucketing decisions, 188 * even those which make non-standard comparisons (like cookies, which ignore 189 * scheme, or quotas, which ignore subdomains). 190 * 191 * If you're looking for an easy-to-use canonical stringification of the origin 192 * attributes, see |originSuffix| below. 193 */ 194 [implicit_jscontext] 195 readonly attribute jsval originAttributes; 196 197 /** 198 * A canonical representation of the origin for this principal. This 199 * consists of a base string (which, for codebase principals, is of the 200 * format scheme://host:port), concatenated with |originAttributes| (see 201 * below). 202 * 203 * We maintain the invariant that principalA.equals(principalB) if and only 204 * if principalA.origin == principalB.origin. 205 */ 206 readonly attribute ACString origin; 207 208 /** 209 * The base part of |origin| without the concatenation with |originSuffix|. 210 * This doesn't have the important invariants described above with |origin|, 211 * and as such should only be used for legacy situations. 212 */ 213 readonly attribute ACString originNoSuffix; 214 215 /** 216 * A string of the form !key1=value1&key2=value2, where each pair represents 217 * an attribute with a non-default value. If all attributes have default 218 * values, this is the empty string. 219 * 220 * The value of .originSuffix is automatically serialized into .origin, so any 221 * consumers using that are automatically origin-attribute-aware. Consumers with 222 * special requirements must inspect and compare .originSuffix manually. 223 */ 224 readonly attribute AUTF8String originSuffix; 225 226 /** 227 * The base domain of the codebase URI to which this principal pertains 228 * (generally the document URI), handling null principals and 229 * non-hierarchical schemes correctly. 230 */ 231 readonly attribute ACString baseDomain; 232 233 const short APP_STATUS_NOT_INSTALLED = 0; 234 const short APP_STATUS_INSTALLED = 1; 235 const short APP_STATUS_PRIVILEGED = 2; 236 const short APP_STATUS_CERTIFIED = 3; 237 238 /** 239 * Gets the principal's app status, which indicates whether the principal 240 * corresponds to "app code", and if it does, how privileged that code is. 241 * This method returns one of the APP_STATUS constants above. 242 * 243 * Note that a principal may have 244 * 245 * appId != nsIScriptSecurityManager::NO_APP_ID && 246 * appId != nsIScriptSecurityManager::UNKNOWN_APP_ID 247 * 248 * and still have appStatus == APP_STATUS_NOT_INSTALLED. That's because 249 * appId identifies the app that contains this principal, but a window 250 * might be contained in an app and not be running code that the app has 251 * vouched for. For example, the window might be inside an <iframe 252 * mozbrowser>, or the window's origin might not match the app's origin. 253 * 254 * If you're doing a check to determine "does this principal correspond to 255 * app code?", you must check appStatus; checking appId != NO_APP_ID is not 256 * sufficient. 257 */ 258 [infallible] readonly attribute unsigned short appStatus; 259 260 /** 261 * Gets the id of the app this principal is inside. If this principal is 262 * not inside an app, returns nsIScriptSecurityManager::NO_APP_ID. 263 * 264 * Note that this principal does not necessarily have the permissions of 265 * the app identified by appId. For example, this principal might 266 * correspond to an iframe whose origin differs from that of the app frame 267 * containing it. In this case, the iframe will have the appId of its 268 * containing app frame, but the iframe must not run with the app's 269 * permissions. 270 * 271 * Similarly, this principal might correspond to an <iframe mozbrowser> 272 * inside an app frame; in this case, the content inside the iframe should 273 * not have any of the app's permissions, even if the iframe is at the same 274 * origin as the app. 275 * 276 * If you're doing a security check based on appId, you must check 277 * appStatus as well. 278 */ 279 [infallible] readonly attribute unsigned long appId; 280 281 /** 282 * Gets the ID of the add-on this principal belongs to. 283 */ 284 readonly attribute AString addonId; 285 286 /** 287 * Gets the id of the user context this principal is inside. If this 288 * principal is inside the default userContext, this returns 289 * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID. 290 */ 291 [infallible] readonly attribute unsigned long userContextId; 292 293 /** 294 * Gets the id of the private browsing state of the context containing 295 * this principal. If the principal has a private browsing value of 0, it 296 * is not in private browsing. 297 */ 298 [infallible] readonly attribute unsigned long privateBrowsingId; 299 300 /** 301 * Returns true iff the principal is inside an isolated mozbrowser element. 302 * <iframe mozbrowser mozapp> and <xul:browser> are not considered to be 303 * mozbrowser elements. <iframe mozbrowser noisolation> does not count as 304 * isolated since isolation is disabled. Isolation can only be disabled if 305 * the containing document is chrome. 306 */ 307 [infallible] readonly attribute boolean isInIsolatedMozBrowserElement; 308 309 /** 310 * Returns true if this principal has an unknown appId. This shouldn't 311 * generally be used. We only expose it due to not providing the correct 312 * appId everywhere where we construct principals. 313 */ 314 [infallible] readonly attribute boolean unknownAppId; 315 316 /** 317 * Returns true iff this is a null principal (corresponding to an 318 * unknown, hence assumed minimally privileged, security context). 319 */ 320 [infallible] readonly attribute boolean isNullPrincipal; 321 322 /** 323 * Returns true iff this principal corresponds to a codebase origin. 324 */ 325 [infallible] readonly attribute boolean isCodebasePrincipal; 326 327 /** 328 * Returns true iff this is an expanded principal. 329 */ 330 [infallible] readonly attribute boolean isExpandedPrincipal; 331 332 /** 333 * Returns true iff this is the system principal. 334 */ 335 [infallible] readonly attribute boolean isSystemPrincipal; 336 337 /** 338 * Returns true if this principal's origin is recognized as being on the 339 * whitelist of sites that can use the CSS Unprefixing Service. 340 * 341 * (This interface provides a trivial implementation, just returning false; 342 * subclasses can implement something more complex as-needed.) 343 */ 344 [noscript,notxpcom,nostdcall] bool IsOnCSSUnprefixingWhitelist(); 345}; 346 347/** 348 * If nsSystemPrincipal is too risky to use, but we want a principal to access 349 * more than one origin, nsExpandedPrincipals letting us define an array of 350 * principals it subsumes. So script with an nsExpandedPrincipals will gain 351 * same origin access when at least one of its principals it contains gained 352 * sameorigin acccess. An nsExpandedPrincipal will be subsumed by the system 353 * principal, and by another nsExpandedPrincipal that has all its principals. 354 * It is added for jetpack content-scripts to let them interact with the 355 * content and a well defined set of other domains, without the risk of 356 * leaking out a system principal to the content. See: Bug 734891 357 */ 358[uuid(f3e177Df-6a5e-489f-80a7-2dd1481471d8)] 359interface nsIExpandedPrincipal : nsISupports 360{ 361 /** 362 * An array of principals that the expanded principal subsumes. 363 * Note: this list is not reference counted, it is shared, so 364 * should not be changed and should only be used ephemerally. 365 */ 366 [noscript] readonly attribute PrincipalArray whiteList; 367}; 368