Bug 1134096 - Revise docs for ::NewChannel2, ::GetChannelPrincipal and add deprecation warnings (r=tanvi,sicking)
authorChristoph Kerschbaumer <mozilla@christophkerschbaumer.com>
Mon, 13 Apr 2015 13:37:14 -0700
changeset 268772 4d0b61eb4ae900b5c0d60d6721ae2e424a02cdeb
parent 268771 a7597040042d77a4af4b3ea4f9a47de9b0a4864b
child 268773 12deb121d126d59bec12953eecdf5bfe0d1af7bf
push id4830
push userjlund@mozilla.com
push dateMon, 29 Jun 2015 20:18:48 +0000
treeherdermozilla-beta@4c2175bb0420 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerstanvi, sicking
bugs1134096
milestone40.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1134096 - Revise docs for ::NewChannel2, ::GetChannelPrincipal and add deprecation warnings (r=tanvi,sicking)
caps/nsScriptSecurityManager.cpp
netwerk/base/NetUtil.jsm
netwerk/base/nsIIOService.idl
netwerk/base/nsIIOService2.idl
netwerk/base/nsIOService.cpp
netwerk/base/nsNetUtil.h
--- a/caps/nsScriptSecurityManager.cpp
+++ b/caps/nsScriptSecurityManager.cpp
@@ -300,16 +300,25 @@ nsScriptSecurityManager::AppStatusForPri
     if (!appOriginPunned.Equals(origin)) {
         return nsIPrincipal::APP_STATUS_NOT_INSTALLED;
     }
 
     return status;
 
 }
 
+/*
+ * GetChannelResultPrincipal will return the principal that the resource
+ * returned by this channel will use.  For example, if the resource is in
+ * a sandbox, it will return the nullprincipal.  If the resource is forced
+ * to inherit principal, it will return the principal of its parent.  If
+ * the load doesn't require sandboxing or inheriting, it will return the same
+ * principal as GetChannelURIPrincipal. Namely the principal of the URI
+ * that is being loaded.
+ */
 NS_IMETHODIMP
 nsScriptSecurityManager::GetChannelResultPrincipal(nsIChannel* aChannel,
                                                    nsIPrincipal** aPrincipal)
 {
     NS_PRECONDITION(aChannel, "Must have channel!");
     nsCOMPtr<nsISupports> owner;
     aChannel->GetOwner(getter_AddRefs(owner));
     if (owner) {
@@ -334,16 +343,27 @@ nsScriptSecurityManager::GetChannelResul
         if (loadInfo->GetForceInheritPrincipal()) {
             NS_ADDREF(*aPrincipal = loadInfo->TriggeringPrincipal());
             return NS_OK;
         }
     }
     return GetChannelURIPrincipal(aChannel, aPrincipal);
 }
 
+/* The principal of the URI that this channel is loading. This is never
+ * affected by things like sandboxed loads, or loads where we forcefully
+ * inherit the principal.  Think of this as the principal of the server
+ * which this channel is loading from.  Most callers should use
+ * GetChannelResultPrincipal instead of GetChannelURIPrincipal.  Only
+ * call GetChannelURIPrincipal if you are sure that you want the
+ * principal that matches the uri, even in cases when the load is
+ * sandboxed or when the load could be a blob or data uri (i.e even when
+ * you encounter loads that may or may not be sandboxed and loads
+ * that may or may not inherit)."
+ */
 NS_IMETHODIMP
 nsScriptSecurityManager::GetChannelURIPrincipal(nsIChannel* aChannel,
                                                 nsIPrincipal** aPrincipal)
 {
     NS_PRECONDITION(aChannel, "Must have channel!");
 
     // Get the principal from the URI.  Make sure this does the same thing
     // as nsDocument::Reset and XULDocument::StartDocumentLoad.
--- a/netwerk/base/NetUtil.jsm
+++ b/netwerk/base/NetUtil.jsm
@@ -315,21 +315,22 @@ this.NetUtil = {
      *            For loads that are not related to any document, such as loads
      *            coming from addons or internal browser features, omit this
      *            property and specify a loadingPrincipal or
      *            loadUsingSystemPrincipal instead.
      *          loadingPrincipal:
      *            The loadingPrincipal of the channel.
      *            The principal of the document where the result of this request
      *            will be used.
-     *            This is generally the principal of the loadingNode.  However
-     *            for loads where loadingNode is omitted this argument still
-     *            needs to be passed.  For example for loads from a WebWorker,
-     *            pass the principal of that worker.  For loads from an addon or
-     *            from internal browser features, pass the system principal.
+     *            This defaults to the principal of aLoadingNode, so when
+     *            aLoadingNode is passed this can be left as null. However for
+     *            loads where aLoadingNode is null this argument must be passed.
+     *            For example for loads from a WebWorker, pass the principal of
+     *            that worker.  For loads from an addon or from internal browser
+     *            features, pass the system principal.
      *            This principal should almost always be the system principal if
      *            loadingNode is omitted, in which case you can use the
      *            useSystemPrincipal property.  The only exception to this is
      *            for loads from WebWorkers since they don't have any nodes to
      *            be passed as loadingNode.
      *            Please note, loadingPrincipal is *not* the principal of the
      *            resource being loaded, but rather the principal of the context
      *            where the resource will be used.
--- a/netwerk/base/nsIIOService.idl
+++ b/netwerk/base/nsIIOService.idl
@@ -83,19 +83,20 @@ interface nsIIOService : nsISupports
      *        the load might be coalesced across multiple elements (such as
      *        for <img>) then pass in the Document node instead.
      *        For loads that are not related to any document, such as loads coming
      *        from addons or internal browser features, use null here.
      * @param aLoadingPrincipal
      *        The loadingPrincipal of the channel.
      *        The principal of the document where the result of this request will
      *        be used.
-     *        This is generally the principal of the aLoadingNode. However for
-     *        loads where aLoadingNode is null this argument still needs to be
-     *        passed. For example for loads from a WebWorker, pass the principal
+     *        This defaults to the principal of aLoadingNode, so when aLoadingNode
+     *        is passed this can be left as null. However for loads where
+     *        aLoadingNode is null this argument must be passed.
+     *        For example for loads from a WebWorker, pass the principal
      *        of that worker. For loads from an addon or from internal browser
      *        features, pass the system principal.
      *        This principal should almost always be the system principal if
      *        aLoadingNode is null. The only exception to this is for loads
      *        from WebWorkers since they don't have any nodes to be passed as
      *        aLoadingNode.
      *        Please note, aLoadingPrincipal is *not* the principal of the
      *        resource being loaded. But rather the principal of the context
--- a/netwerk/base/nsIIOService2.idl
+++ b/netwerk/base/nsIIOService2.idl
@@ -53,19 +53,20 @@ interface nsIIOService2 : nsIIOService
    *        the load might be coalesced across multiple elements (such as
    *        for <img>) then pass in the Document node instead.
    *        For loads that are not related to any document, such as loads coming
    *        from addons or internal browser features, use null here.
    * @param aLoadingPrincipal
    *        The loadingPrincipal of the channel.
    *        The principal of the document where the result of this request will
    *        be used.
-   *        This is generally the principal of the aLoadingNode. However for
-   *        loads where aLoadingNode is null this argument still needs to be
-   *        passed. For example for loads from a WebWorker, pass the principal
+   *        This defaults to the principal of aLoadingNode, so when aLoadingNode
+   *        is passed this can be left as null. However for loads where
+   *        aLoadingNode is null this argument must be passed.
+   *        For example for loads from a WebWorker, pass the principal
    *        of that worker. For loads from an addon or from internal browser
    *        features, pass the system principal.
    *        This principal should almost always be the system principal if
    *        aLoadingNode is null. The only exception to this is for loads
    *        from WebWorkers since they don't have any nodes to be passed as
    *        aLoadingNode.
    *        Please note, aLoadingPrincipal is *not* the principal of the
    *        resource being loaded. But rather the principal of the context
--- a/netwerk/base/nsIOService.cpp
+++ b/netwerk/base/nsIOService.cpp
@@ -583,19 +583,30 @@ nsIOService::NewChannelFromURIWithLoadIn
   NS_ENSURE_ARG_POINTER(aLoadInfo);
   return NewChannelFromURIWithProxyFlagsInternal(aURI,
                                                  nullptr, // aProxyURI
                                                  0,       // aProxyFlags
                                                  aLoadInfo,
                                                  result);
 }
 
+/*  ***** DEPRECATED *****
+ * please use NewChannelFromURI2 providing the right arguments for:
+ *        * aLoadingNode
+ *        * aLoadingPrincipal
+ *        * aTriggeringPrincipal
+ *        * aSecurityFlags
+ *        * aContentPolicyType
+ *
+ * See nsIIoService.idl for a detailed description of those arguments
+ */
 NS_IMETHODIMP
 nsIOService::NewChannelFromURI(nsIURI *aURI, nsIChannel **result)
 {
+  NS_WARNING("Deprecated, use NewChannelFromURI2 providing loadInfo arguments!");
   return NewChannelFromURI2(aURI,
                             nullptr, // aLoadingNode
                             nullptr, // aLoadingPrincipal
                             nullptr, // aTriggeringPrincipal
                             nsILoadInfo::SEC_NORMAL,
                             nsIContentPolicy::TYPE_OTHER,
                             result);
 }
@@ -760,22 +771,33 @@ nsIOService::NewChannelFromURIWithProxyF
     }
     return NewChannelFromURIWithProxyFlagsInternal(aURI,
                                                    aProxyURI,
                                                    aProxyFlags,
                                                    loadInfo,
                                                    result);
 }
 
+/*  ***** DEPRECATED *****
+ * please use NewChannelFromURIWithProxyFlags2 providing the right arguments for:
+ *        * aLoadingNode
+ *        * aLoadingPrincipal
+ *        * aTriggeringPrincipal
+ *        * aSecurityFlags
+ *        * aContentPolicyType
+ *
+ * See nsIIoService.idl for a detailed description of those arguments
+ */
 NS_IMETHODIMP
 nsIOService::NewChannelFromURIWithProxyFlags(nsIURI *aURI,
                                              nsIURI *aProxyURI,
                                              uint32_t aProxyFlags,
                                              nsIChannel **result)
 {
+  NS_WARNING("Deprecated, use NewChannelFromURIWithProxyFlags2 providing loadInfo arguments!");
   return NewChannelFromURIWithProxyFlags2(aURI,
                                           aProxyURI,
                                           aProxyFlags,
                                           nullptr, // aLoadingNode
                                           nullptr, // aLoadingPrincipal
                                           nullptr, // aTriggeringPrincipal
                                           nsILoadInfo::SEC_NORMAL,
                                           nsIContentPolicy::TYPE_OTHER,
@@ -802,19 +824,30 @@ nsIOService::NewChannel2(const nsACStrin
                               aLoadingNode,
                               aLoadingPrincipal,
                               aTriggeringPrincipal,
                               aSecurityFlags,
                               aContentPolicyType,
                               result);
 }
 
+/*  ***** DEPRECATED *****
+ * please use NewChannel2 providing the right arguments for:
+ *        * aLoadingNode
+ *        * aLoadingPrincipal
+ *        * aTriggeringPrincipal
+ *        * aSecurityFlags
+ *        * aContentPolicyType
+ *
+ * See nsIIoService.idl for a detailed description of those arguments
+ */
 NS_IMETHODIMP
 nsIOService::NewChannel(const nsACString &aSpec, const char *aCharset, nsIURI *aBaseURI, nsIChannel **result)
 {
+  NS_WARNING("Deprecated, use NewChannel2 providing loadInfo arguments!");
   return NewChannel2(aSpec,
                      aCharset,
                      aBaseURI,
                      nullptr, // aLoadingNode
                      nullptr, // aLoadingPrincipal
                      nullptr, // aTriggeringPrincipal
                      nsILoadInfo::SEC_NORMAL,
                      nsIContentPolicy::TYPE_OTHER,
--- a/netwerk/base/nsNetUtil.h
+++ b/netwerk/base/nsNetUtil.h
@@ -219,19 +219,20 @@ NS_NewFileURI(nsIURI* *result,
 *        the load might be coalesced across multiple elements (such as
 *        for <img>) then pass in the Document node instead.
 *        For loads that are not related to any document, such as loads coming
 *        from addons or internal browser features, use null here.
 * @param aLoadingPrincipal
 *        The loadingPrincipal of the channel.
 *        The principal of the document where the result of this request will
 *        be used.
-*        This is generally the principal of the aLoadingNode. However for
-*        loads where aLoadingNode is null this argument still needs to be
-*        passed. For example for loads from a WebWorker, pass the principal
+*        This defaults to the principal of aLoadingNode, so when aLoadingNode
+*        is passed this can be left as null. However for loads where
+*        aLoadingNode is null this argument must be passed.
+*        For example for loads from a WebWorker, pass the principal
 *        of that worker. For loads from an addon or from internal browser
 *        features, pass the system principal.
 *        This principal should almost always be the system principal if
 *        aLoadingNode is null. The only exception to this is for loads
 *        from WebWorkers since they don't have any nodes to be passed as
 *        aLoadingNode.
 *        Please note, aLoadingPrincipal is *not* the principal of the
 *        resource being loaded. But rather the principal of the context