Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Improve the documentation of the paramters passed to noteOp"

Browse Source
This commit is contained in:
TreeHugger Robot
2020-10-09 03:12:56 +00:00
committed by Android (Google) Code Review
parent 22d412a5bf 8c22ae2a0c
commit 23606d44e8
3 changed files with 76 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
core/java/android/app/AppOpsManager.java
View File

@@ -7337,21 +7337,48 @@ public class AppOpsManager {
}
/**
* Make note of an application performing an operation. Note that you must pass
* in both the uid and name of the application to be checked; this function will verify
* that these two match, and if not, return {@link #MODE_IGNORED}. If this call
* succeeds, the last execution time of the operation for this app will be updated to
* the current time.
* Make note of an application performing an operation and check if the application is allowed
* to perform it.
*
* <p>If this is a check that is not preceding the protected operation, use
* {@link #unsafeCheckOp} instead.
*
* <p>The identity of the package the app-op is noted for is specified by the
* {@code uid} and {@code packageName} parameters. If this is noted for a regular app both
* should be set and the package needs to be part of the uid. In the very rare case that an
* app-op is noted for an entity that does not have a package name, the package can be
* {@code null}. As it is possible that a single process contains more than one package the
* {@code packageName} should be {@link Context#getPackageName() read} from the context of the
* caller of the API (in the app process) that eventually triggers this check. If this op is
* not noted for a running process the {@code packageName} cannot be read from the context, but
* it should be clear which package the note is for.
*
* <p>If the {@code uid} and {@code packageName} do not match this return
* {@link #MODE_IGNORED}.
*
* <p>Beside the access check this method also records the access. While the access check is
* based on {@code uid} and/or {@code packageName} the access recording is done based on the
* {@code packageName} and {@code attributionTag}. The {@code attributionTag} should be
* {@link Context#getAttributionTag() read} from the same context the package name is read from.
* In the case the check is not related to an API call, the {@code attributionTag} should be
* {@code null}. Please note that e.g. registering a callback for later is still an API call and
* the code should store the attribution tag along the package name for being used in this
* method later.
*
* <p>The {@code message} parameter only needs to be set when this method is <ul>not</ul>
* called in a two-way binder call from the client. In this case the message is a free form text
* that is meant help the app developer determine what part of the app's code triggered the
* note. This message is passed back to the app in the
* {@link OnOpNotedCallback#onAsyncNoted(AsyncNotedAppOp)} callback. A good example of a useful
* message is including the {@link System#identityHashCode(Object)} of the listener that will
* receive data or the name of the manifest-receiver.
*
* @param op The operation to note. One of the OPSTR_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param uid The uid of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
* @param attributionTag The {@link Context#createAttributionContext attribution tag} or {@code
* null} for default attribution
* @param message A message describing the reason the op was noted
* @param attributionTag The {@link Context#createAttributionContext attribution tag} of the
* calling context or {@code null} for default attribution
* @param message A message describing why the op was noted
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or
* {@link #MODE_IGNORED} if it is not allowed and should be silently ignored (without
@@ -7359,33 +7386,16 @@ public class AppOpsManager {
*
* @throws SecurityException If the app has been configured to crash on this op.
*/
// For platform callers of this method, please read the package name parameter from
// Context#getOpPackageName.
// When noting a callback, the message can be computed using the #toReceiverId method.
public int noteOp(@NonNull String op, int uid, @Nullable String packageName,
@Nullable String attributionTag, @Nullable String message) {
return noteOp(strOpToOp(op), uid, packageName, attributionTag, message);
}
/**
* Make note of an application performing an operation. Note that you must pass
* in both the uid and name of the application to be checked; this function will verify
* that these two match, and if not, return {@link #MODE_IGNORED}. If this call
* succeeds, the last execution time of the operation for this app will be updated to
* the current time.
*
* <p>If this is a check that is not preceding the protected operation, use
* {@link #unsafeCheckOp} instead.
*
* @param op The operation to note. One of the OP_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
* @param attributionTag The {@link Context#createAttributionContext attribution tag} or {@code
* null} for default attribution
* @param message A message describing the reason the op was noted
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or
* {@link #MODE_IGNORED} if it is not allowed and should be silently ignored (without
* causing the app to crash).
*
* @throws SecurityException If the app has been configured to crash on this op.
* @see #noteOp(String, int, String, String, String
*
* @hide
*/
@@ -7423,16 +7433,7 @@ public class AppOpsManager {
* Like {@link #noteOp(String, int, String, String, String)} but instead of throwing a
* {@link SecurityException} it returns {@link #MODE_ERRORED}.
*
* @param op The operation to note. One of the OPSTR_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
* @param attributionTag The {@link Context#createAttributionContext attribution tag} or {@code
* null} for default attribution
* @param message A message describing the reason the op was noted
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or
* {@link #MODE_IGNORED} if it is not allowed and should be silently ignored (without
* causing the app to crash).
* @see #noteOp(String, int, String, String, String)
*/
public int noteOpNoThrow(@NonNull String op, int uid, @NonNull String packageName,
@Nullable String attributionTag, @Nullable String message) {
@@ -7440,19 +7441,7 @@ public class AppOpsManager {
}
/**
* Like {@link #noteOp(String, int, String, String, String)} but instead of throwing a
* {@link SecurityException} it returns {@link #MODE_ERRORED}.
*
* @param op The operation to note. One of the OP_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
* @param attributionTag The {@link Context#createAttributionContext attribution tag} or {@code
* null} for default attribution
* @param message A message describing the reason the op was noted
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or
* {@link #MODE_IGNORED} if it is not allowed and should be silently ignored (without
* causing the app to crash).
* @see #noteOpNoThrow(String, int, String, String, String)
*
* @hide
*/
@@ -7509,23 +7498,7 @@ public class AppOpsManager {
}
/**
* Make note of an application performing an operation on behalf of another application when
* handling an IPC. This function will verify that the calling uid and proxied package name
* match, and if not, return {@link #MODE_IGNORED}. If this call succeeds, the last execution
* time of the operation for the proxied app and your app will be updated to the current time.
*
* @param op The operation to note. One of the OP_* constants.
* @param proxiedPackageName The name of the application calling into the proxy application.
* @param proxiedUid The uid of the proxied application
* @param proxiedAttributionTag The proxied {@link Context#createAttributionContext
* attribution tag} or {@code null} for default attribution
* @param message A message describing the reason the op was noted
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or {@link #MODE_IGNORED}
* if it is not allowed and should be silently ignored (without causing the app to crash).
*
* @throws SecurityException If the proxy or proxied app has been configured to crash on this
* op.
* @see #noteProxyOp(String, String, int, String, String)
*
* @hide
*/
@@ -7587,15 +7560,7 @@ public class AppOpsManager {
* Like {@link #noteProxyOp(String, String, int, String, String)} but instead
* of throwing a {@link SecurityException} it returns {@link #MODE_ERRORED}.
*
* <p>This API requires package with the {@code proxiedPackageName} to belong to
* {@code proxiedUid}.
*
* @param op The op to note
* @param proxiedPackageName The package to note the op for
* @param proxiedUid The uid the package belongs to
* @param proxiedAttributionTag The proxied {@link Context#createAttributionContext
* attribution tag} or {@code null} for default attribution
* @param message A message describing the reason the op was noted
* @see #noteOpNoThrow(String, int, String, String, String)
*/
public int noteProxyOpNoThrow(@NonNull String op, @Nullable String proxiedPackageName,
int proxiedUid, @Nullable String proxiedAttributionTag, @Nullable String message) {
@@ -7604,16 +7569,7 @@ public class AppOpsManager {
}
/**
* Like {@link #noteProxyOp(int, String, int, String, String)} but instead
* of throwing a {@link SecurityException} it returns {@link #MODE_ERRORED}.
*
* @param op The op to note
* @param proxiedPackageName The package to note the op for or {@code null} if the op should be
* noted for the "android" package
* @param proxiedUid The uid the package belongs to
* @param proxiedAttributionTag The proxied {@link Context#createAttributionContext
* attribution tag} or {@code null} for default attribution
* @param message A message describing the reason the op was noted
* @see #noteProxyOpNoThrow(String, String, int, String, String)
*
* @hide
*/
@@ -7701,6 +7657,9 @@ public class AppOpsManager {
/**
* Like {@link #checkOp} but instead of throwing a {@link SecurityException} it
* returns {@link #MODE_ERRORED}.
*
* @see #checkOp(int, int, String)
*
* @hide
*/
@UnsupportedAppUsage
@@ -7832,6 +7791,10 @@ public class AppOpsManager {
/**
* Report that an application has started executing a long-running operation.
*
* <p>For more details how to determine the {@code callingPackageName},
* {@code callingAttributionTag}, and {@code message}, please check the description in
* {@link #noteOp(String, int, String, String, String)}
*
* @param op The operation to start. One of the OPSTR_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
@@ -7852,22 +7815,7 @@ public class AppOpsManager {
}
/**
* Report that an application has started executing a long-running operation.
*
* @param op The operation to start. One of the OP_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
* @param attributionTag The {@link Context#createAttributionContext attribution tag} or
* {@code null} for default attribution
* @param startIfModeDefault Whether to start if mode is {@link #MODE_DEFAULT}.
* @param message Description why op was started
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or
* {@link #MODE_IGNORED} if it is not allowed and should be silently ignored (without
* causing the app to crash).
*
* @throws SecurityException If the app has been configured to crash on this op or
* the package is not in the passed in UID.
* @see #startOp(String, int, String, String, String)
*
* @hide
*/
@@ -7913,16 +7861,7 @@ public class AppOpsManager {
* Like {@link #startOp(String, int, String, String, String)} but instead of throwing a
* {@link SecurityException} it returns {@link #MODE_ERRORED}.
*
* @param op The operation to start. One of the OP_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
* @param attributionTag The {@link Context#createAttributionContext attribution tag} or
* {@code null} for default attribution
* @param message Description why op was started
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or
* {@link #MODE_IGNORED} if it is not allowed and should be silently ignored (without
* causing the app to crash).
* @see #startOp(String, int, String, String, String)
*/
public int startOpNoThrow(@NonNull String op, int uid, @NonNull String packageName,
@NonNull String attributionTag, @Nullable String message) {
@@ -7930,20 +7869,7 @@ public class AppOpsManager {
}
/**
* Like {@link #startOp(int, int, String, boolean, String, String)} but instead of throwing a
* {@link SecurityException} it returns {@link #MODE_ERRORED}.
*
* @param op The operation to start. One of the OP_* constants.
* @param uid The user id of the application attempting to perform the operation.
* @param packageName The name of the application attempting to perform the operation.
* @param attributionTag The {@link Context#createAttributionContext attribution tag} or
* {@code null} for default attribution
* @param startIfModeDefault Whether to start if mode is {@link #MODE_DEFAULT}.
* @param message Description why op was started
*
* @return Returns {@link #MODE_ALLOWED} if the operation is allowed, or
* {@link #MODE_IGNORED} if it is not allowed and should be silently ignored (without
* causing the app to crash).
* @see #startOpNoThrow(String, int, String, String, String)
*
* @hide
*/
@@ -8102,10 +8028,7 @@ public class AppOpsManager {
}
/**
* Report that an application is no longer performing an operation that had previously
* been started with {@link #startOp(int, int, String, boolean, String, String)}. There is no
* validation of input or result; the parameters supplied here must be the exact same ones
* previously passed in when starting the operation.
* @see #finishOp(String, int, String, String)
*
* @hide
*/

22
core/java/android/content/PermissionChecker.java
View File

@@ -116,6 +116,10 @@ public final class PermissionChecker {
* will evaluate the permission access based on the current fg/bg state of the app and
* leave a record that the data was accessed.
*
* <p>For more details how to determine the {@code packageName}, {@code attributionTag}, and
* {@code message}, please check the description in
* {@link AppOpsManager#noteOp(String, int, String, String, String)}
*
* @param context Context for accessing resources.
* @param permission The permission to check.
* @param pid The process id for which to check. Use {@link #PID_UNKNOWN} if the PID
@@ -262,11 +266,15 @@ public final class PermissionChecker {
* will evaluate the permission access based on the current fg/bg state of the app and
* leave a record that the data was accessed.
*
* <p>For more details how to determine the {@code callingPackageName},
* {@code callingAttributionTag}, and {@code message}, please check the description in
* {@link AppOpsManager#noteOp(String, int, String, String, String)}
*
* @param context Context for accessing resources.
* @param permission The permission to check.
* @param packageName The package name making the IPC. If null the
* @param callingPackageName The package name making the IPC. If null the
* the first package for the calling UID will be used.
* @param attributionTag attribution tag
* @param callingAttributionTag attribution tag
* @return The permission check result which is either {@link #PERMISSION_GRANTED}
* or {@link #PERMISSION_SOFT_DENIED} or {@link #PERMISSION_HARD_DENIED}.
* @param message A message describing the reason the permission was checked
@@ -275,13 +283,13 @@ public final class PermissionChecker {
*/
@PermissionResult
public static int checkCallingPermissionForDataDelivery(@NonNull Context context,
@NonNull String permission, @Nullable String packageName,
@Nullable String attributionTag, @Nullable String message) {
@NonNull String permission, @Nullable String callingPackageName,
@Nullable String callingAttributionTag, @Nullable String message) {
if (Binder.getCallingPid() == Process.myPid()) {
return PERMISSION_HARD_DENIED;
}
return checkPermissionForDataDelivery(context, permission, Binder.getCallingPid(),
Binder.getCallingUid(), packageName, attributionTag, message);
Binder.getCallingUid(), callingPackageName, callingAttributionTag, message);
}
/**
@@ -339,6 +347,10 @@ public final class PermissionChecker {
* will evaluate the permission access based on the current fg/bg state of the app and
* leave a record that the data was accessed.
*
* <p>For more details how to determine the {@code callingPackageName},
* {@code callingAttributionTag}, and {@code message}, please check the description in
* {@link AppOpsManager#noteOp(String, int, String, String, String)}
*
* @param context Context for accessing resources.
* @param permission The permission to check.
* @return The permission check result which is either {@link #PERMISSION_GRANTED}

6
core/java/android/permission/Permissions.md
View File

@@ -203,7 +203,7 @@ decision is made the activity is called by via `Activity.onPermissionGranted`.
During development and testing a runtime permission can be granted via the `pm` shell command or by
using the `UiAutomator.grantRuntimePermission` API call. Please note that this does _not_ grant the
[app-op](#runtime-permissions-and-app-ops) synchronously. Unless the app needs to test the actual
[app-op](#runtime-permissions-and-app_ops) synchronously. Unless the app needs to test the actual
permission grant flow it is recommended to grant the runtime permissions during install using
`adb install -g /my/package.apk`.
@@ -262,7 +262,7 @@ crashing the app the special `PERMISSION_DENIED_APP_OP` mandates that the API sh
silently fail.
A secondary use case of the `AppOpsManager.noteOp` calls is to
[track](../app/AppOps.md#Appops-for-tracking) which apps perform what runtime protected actions.
[track](../app/AppOps.md#app_ops-for-tracking) which apps perform what runtime protected actions.
#### Verifying an app has a runtime time permission
@@ -471,7 +471,7 @@ This is currently (Mar 2020) reworked and will behave like [location](#location)
##### Location
As described [above](#runtime-permissions-and-app-ops) the app-op mode for granted permissions is
As described [above](#runtime-permissions-and-app_ops) the app-op mode for granted permissions is
`MODE_ALLOWED` to allow access or `MODE_IGNORED` to suppress access.
The important case is the case where the permission is granted and the app-op is `MODE_IGNORED`. In