From 08f8c49f33e9c07e445f65f707804faf270602f5 Mon Sep 17 00:00:00 2001
From: Winson <chiuwinson@google.com>
Date: Thu, 21 Nov 2019 15:44:02 -0800
Subject: [PATCH] Clarify actor requirements in OverlayManager API

Bug: 135052950
Bug: 138458046

Test: none; docs only change

Change-Id: Ibe0d139cd0e7f819b8e85d109ea38fe853a0b080
---
 .../android/content/om/OverlayManager.java    | 40 +++++++++++++++++++
 .../server/om/OverlayActorEnforcer.java       | 11 ++---
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/core/java/android/content/om/OverlayManager.java b/core/java/android/content/om/OverlayManager.java
index dbe39547b0cac..2bdca7d87a78f 100644
--- a/core/java/android/content/om/OverlayManager.java
+++ b/core/java/android/content/om/OverlayManager.java
@@ -27,14 +27,50 @@ import android.compat.annotation.ChangeId;
 import android.compat.annotation.EnabledAfter;
 import android.content.Context;
 import android.os.Build;
+import android.os.Process;
 import android.os.RemoteException;
 import android.os.ServiceManager;
 import android.os.UserHandle;
 
+import com.android.server.SystemConfig;
+
 import java.util.List;
 
 /**
  * Updates OverlayManager state; gets information about installed overlay packages.
+ *
+ * <p>Users of this API must be actors of any overlays they desire to change the state of.</p>
+ *
+ * <p>An actor is a package responsible for managing the state of overlays targeting overlayables
+ * that specify the actor. For example, an actor may enable or disable an overlay or otherwise
+ * change its state.</p>
+ *
+ * <p>Actors are specified as part of the overlayable definition.
+ *
+ * <pre>{@code
+ * <overlayable name="OverlayableResourcesName" actor="overlay://namespace/actorName">
+ * }</pre></p>
+ *
+ * <p>Actors are defined through {@link SystemConfig}. Only system packages can be used.
+ * The namespace "android" is reserved for use by AOSP and any "android" definitions must
+ * have an implementation on device that fulfill their intended functionality.</p>
+ *
+ * <pre>{@code
+ * <named-actor
+ *     namespace="namespace"
+ *     name="actorName"
+ *     package="com.example.pkg"
+ *     />
+ * }</pre></p>
+ *
+ * <p>An actor can manipulate a particular overlay if any of the following is true:
+ * <ul>
+ * <li>its UID is {@link Process#ROOT_UID}, {@link Process#SYSTEM_UID}</li>
+ * <li>it is the target of the overlay package</li>
+ * <li>it has the CHANGE_OVERLAY_PACKAGES permission and the target does not specify an actor</li>
+ * <li>it is the actor specified by the overlayable</li>
+ * </ul></p>
+ *
  * @hide
  */
 @SystemApi
@@ -84,6 +120,8 @@ public class OverlayManager {
      * If a set of overlay packages share the same category, single call to this method is
      * equivalent to multiple calls to {@link #setEnabled(String, boolean, UserHandle)}.
      *
+     * The caller must pass the actor requirements specified in the class comment.
+     *
      * @param packageName the name of the overlay package to enable.
      * @param user The user for which to change the overlay.
      *
@@ -116,6 +154,8 @@ public class OverlayManager {
      * While {@link #setEnabledExclusiveInCategory(String, UserHandle)} doesn't support disabling
      * every overlay in a category, this method allows you to disable everything.
      *
+     * The caller must pass the actor requirements specified in the class comment.
+     *
      * @param packageName the name of the overlay package to enable.
      * @param enable {@code false} if the overlay should be turned off.
      * @param user The user for which to change the overlay.
diff --git a/services/core/java/com/android/server/om/OverlayActorEnforcer.java b/services/core/java/com/android/server/om/OverlayActorEnforcer.java
index 40efb7cd96d70..91979564fe960 100644
--- a/services/core/java/com/android/server/om/OverlayActorEnforcer.java
+++ b/services/core/java/com/android/server/om/OverlayActorEnforcer.java
@@ -29,7 +29,6 @@ import android.util.Pair;
 
 import com.android.internal.util.ArrayUtils;
 import com.android.internal.util.CollectionUtils;
-import com.android.server.SystemConfig;
 
 import java.io.IOException;
 import java.util.List;
@@ -38,6 +37,8 @@ import java.util.Map;
 /**
  * Performs verification that a calling UID can act on a target package's overlayable.
  *
+ * Actors requirements are specified in {@link android.content.om.OverlayManager}.
+ *
  * @hide
  */
 public class OverlayActorEnforcer {
@@ -99,13 +100,7 @@ public class OverlayActorEnforcer {
     }
 
     /**
-     * An actor is valid if any of the following is true:
-     * - is {@link Process#ROOT_UID}, {@link Process#SYSTEM_UID}
-     * - is the target overlay package
-     * - has the CHANGE_OVERLAY_PACKAGES permission and an actor is not defined
-     * - is the same the as the package defined in {@link SystemConfig#getNamedActors()} for a given
-     *     namespace and actor name
-     *
+     * See {@link OverlayActorEnforcer} class comment for actor requirements.
      * @return true if the actor is allowed to act on the target overlayInfo
      */
     private ActorState isAllowedActor(String methodName, OverlayInfo overlayInfo,