Bug 802366 - Prelude, part 3: Make some methods on nsIPrincipal infallible, and improve documentation on other methods. r=bz
☠☠ backed out by b103561f6a8b ☠ ☠
authorJustin Lebar <justin.lebar@gmail.com>
Tue, 30 Oct 2012 15:55:05 -0400
changeset 111931 212e1383eb6ed9d9f6c13530e320bc65815501aa
parent 111930 e710acd6ef1170767ca6fd639f8d4f77fc57a976
child 111932 37357ffceb05b6bfad93f1c150feceb4b02977c8
push id93
push usernmatsakis@mozilla.com
push dateWed, 31 Oct 2012 21:26:57 +0000
reviewersbz
bugs802366
milestone19.0a1
Bug 802366 - Prelude, part 3: Make some methods on nsIPrincipal infallible, and improve documentation on other methods. r=bz
caps/idl/nsIPrincipal.idl
--- a/caps/idl/nsIPrincipal.idl
+++ b/caps/idl/nsIPrincipal.idl
@@ -16,17 +16,17 @@ struct JSPrincipals;
 
 interface nsIURI;
 interface nsIContentSecurityPolicy;
 
 [ptr] native JSContext(JSContext);
 [ptr] native JSPrincipals(JSPrincipals);
 [ptr] native PrincipalArray(nsTArray<nsCOMPtr<nsIPrincipal> >);
 
-[scriptable, uuid(3a283dc9-f733-4618-a36f-e2b68c280ab7)]
+[scriptable, builtinclass, uuid(011966C0-8564-438D-B37A-08D7E1195E5A)]
 interface nsIPrincipal : nsISerializable
 {
     /**
      * Returns whether the other principal is equivalent to this principal.
      * Principals are considered equal if they are the same principal, or
      * they have the same origin.
      */
     boolean equals(in nsIPrincipal other);
@@ -154,88 +154,76 @@ interface nsIPrincipal : nsISerializable
     readonly attribute AUTF8String extendedOrigin;
 
     const short APP_STATUS_NOT_INSTALLED = 0;
     const short APP_STATUS_INSTALLED     = 1;
     const short APP_STATUS_PRIVILEGED    = 2;
     const short APP_STATUS_CERTIFIED     = 3;
 
     /**
-     * Shows the status of the app.
-     * Can be: APP_STATUS_NOT_INSTALLED, APP_STATUS_INSTALLED,
-     *         APP_STATUS_PRIVILEGED or APP_STATUS_CERTIFIED.
+     * Gets the principal's app status, which indicates whether the principal
+     * corresponds to "app code", and if it does, how privileged that code is.
+     * This method returns one of the APP_STATUS constants above.
+     *
+     * Note that a principal may have
+     *
+     *   appId != nsIScriptSecurityManager::NO_APP_ID &&
+     *   appId != nsIScriptSecurityManager::UNKNOWN_APP_ID
+     *
+     * and still have appStatus == APP_STATUS_NOT_INSTALLED.  That's because
+     * appId identifies the app that contains this principal, but a window
+     * might be contained in an app and not be running code that the app has
+     * vouched for.  For example, the window might be inside an <iframe
+     * mozbrowser>, or the window's origin might not match the app's origin.
+     *
+     * If you're doing a check to determine "does this principal correspond to
+     * app code?", you must check appStatus; checking appId != NO_APP_ID is not
+     * sufficient.
      */
-    readonly attribute unsigned short appStatus;
-
-    %{C++
-    uint16_t GetAppStatus()
-    {
-      uint16_t appStatus;
-      nsresult rv = GetAppStatus(&appStatus);
-      if (NS_FAILED(rv)) {
-        return APP_STATUS_NOT_INSTALLED;
-      }
-      return appStatus;
-    }
-    %}
+    [infallible] readonly attribute unsigned short appStatus;
 
     /**
-     * Returns the app id the principal is in, or returns
-     * nsIScriptSecurityManager::NO_APP_ID if this principal isn't part of an
-     * app.
+     * Gets the id of the app this principal is inside.  If this principal is
+     * not inside an app, returns nsIScriptSecurityManager::NO_APP_ID.
+     *
+     * Note that this principal does not necessarily have the permissions of
+     * the app identified by appId.  For example, this principal might
+     * correspond to an iframe whose origin differs from that of the app frame
+     * containing it.  In this case, the iframe will have the appId of its
+     * containing app frame, but the iframe must not run with the app's
+     * permissions.
+     *
+     * Similarly, this principal might correspond to an <iframe mozbrowser>
+     * inside an app frame; in this case, the content inside the iframe should
+     * not have any of the app's permissions, even if the iframe is at the same
+     * origin as the app.
+     *
+     * If you're doing a security check based on appId, you must check
+     * appStatus as well.
      */
-    readonly attribute unsigned long appId;
-
-    %{C++
-    uint32_t GetAppId()
-    {
-      uint32_t appId;
-      mozilla::DebugOnly<nsresult> rv = GetAppId(&appId);
-      MOZ_ASSERT(NS_SUCCEEDED(rv));
-      return appId;
-    }
-    %}
+    [infallible] readonly attribute unsigned long appId;
 
     /**
-     * Returns true iif the principal is inside a browser element.
+     * Returns true iff the principal is inside a browser element.  (<iframe
+     * mozbrowser mozapp> does not count as a browser element.)
      */
-    readonly attribute boolean isInBrowserElement;
-
-    %{C++
-    bool GetIsInBrowserElement()
-    {
-      bool isInBrowserElement;
-      mozilla::DebugOnly<nsresult> rv = GetIsInBrowserElement(&isInBrowserElement);
-      MOZ_ASSERT(NS_SUCCEEDED(rv));
-      return isInBrowserElement;
-    }
-    %}
+    [infallible] readonly attribute boolean isInBrowserElement;
 
     /**
      * Returns true if this principal has an unknown appId. This shouldn't
      * generally be used. We only expose it due to not providing the correct
      * appId everywhere where we construct principals.
      */
-    readonly attribute boolean unknownAppId;
-
-    %{C++
-    bool GetUnknownAppId()
-    {
-      bool unkwnownAppId;
-      mozilla::DebugOnly<nsresult> rv = GetUnknownAppId(&unkwnownAppId);
-      MOZ_ASSERT(NS_SUCCEEDED(rv));
-      return unkwnownAppId;
-    }
-    %}
+    [infallible] readonly attribute boolean unknownAppId;
 
     /**
      * Returns true iff this principal is a null principal (corresponding to an
      * unknown, hence assumed minimally privileged, security context).
      */
-    readonly attribute boolean isNullPrincipal;
+    [infallible] readonly attribute boolean isNullPrincipal;
 };
 
 /**
  * If nsSystemPrincipal is too risky to use, but we want a principal to access 
  * more than one origin, nsExpandedPrincipals letting us define an array of 
  * principals it subsumes. So script with an nsExpandedPrincipals will gain
  * same origin access when at least one of its principals it contains gained 
  * sameorigin acccess. An nsExpandedPrincipal will be subsumed by the system