From 634c1bf6e2555fd02b5b169534e678fec2767537 Mon Sep 17 00:00:00 2001 From: Nikita Dubrovsky Date: Sun, 31 Jan 2021 20:33:38 -0800 Subject: [PATCH] Add javadocs to internal APIs for content URI permissions Added javadocs to internal APIs commonly used for granting/revoking URI permissions. Bug: 178987263 Test: Presubmit Change-Id: Ibe1cd6949c235ef2f7091e0e6a7aa03eb35bff8b --- .../server/uri/UriGrantsManagerInternal.java | 53 +++++++++++++------ .../server/uri/UriGrantsManagerService.java | 34 +++++++----- 2 files changed, 57 insertions(+), 30 deletions(-) diff --git a/services/core/java/com/android/server/uri/UriGrantsManagerInternal.java b/services/core/java/com/android/server/uri/UriGrantsManagerInternal.java index 5772dea287fcc..e54b40eb334c8 100644 --- a/services/core/java/com/android/server/uri/UriGrantsManagerInternal.java +++ b/services/core/java/com/android/server/uri/UriGrantsManagerInternal.java @@ -16,6 +16,8 @@ package com.android.server.uri; +import android.annotation.NonNull; +import android.annotation.Nullable; import android.content.Intent; import android.content.pm.ProviderInfo; import android.net.Uri; @@ -58,6 +60,19 @@ public interface UriGrantsManagerInternal { void grantUriPermissionUncheckedFromIntent( NeededUriGrants needed, UriPermissionOwner owner); + /** + * Creates a new stateful object to track uri permission grants. This is needed to maintain + * state when managing grants via {@link UriGrantsManagerService#grantUriPermissionFromOwner}, + * {@link #revokeUriPermissionFromOwner}, etc. + * + * @param name A name for the object. This is only used for logcat/dumpsys logging, so there + * are no uniqueness or other requirements, but it is recommended to make the + * name sufficiently readable so that the relevant code area can be determined + * easily when this name shows up in a bug report. + * @return An opaque owner token for tracking uri permission grants. + * @see UriPermissionOwner + * @see UriGrantsManagerService + */ IBinder newUriPermissionOwner(String name); /** @@ -74,33 +89,39 @@ public interface UriGrantsManagerInternal { */ void removeUriPermissionsForPackage( String packageName, int userHandle, boolean persistable, boolean targetOnly); + /** - * Remove any {@link UriPermission} associated with the owner whose values match the given - * filtering parameters. - * - * @param token An opaque owner token as returned by {@link #newUriPermissionOwner(String)}. - * @param uri This uri must NOT contain an embedded userId. {@code null} to apply to all Uris. - * @param mode The modes (as a bitmask) to revoke. - * @param userId The userId in which the uri is to be resolved. + * Like {@link #revokeUriPermissionFromOwner(IBinder, Uri, int, int, String, int)} but applies + * to all target packages and all target users. */ - void revokeUriPermissionFromOwner(IBinder token, Uri uri, int mode, int userId); + void revokeUriPermissionFromOwner(@NonNull IBinder token, @Nullable Uri uri, int mode, + int userId); /** * Remove any {@link UriPermission} associated with the owner whose values match the given * filtering parameters. * * @param token An opaque owner token as returned by {@link #newUriPermissionOwner(String)}. - * @param uri This uri must NOT contain an embedded userId. {@code null} to apply to all Uris. - * @param mode The modes (as a bitmask) to revoke. - * @param userId The userId in which the uri is to be resolved. - * @param targetPkg Calling package name to match, or {@code null} to apply to all packages. - * @param targetUserId Calling user to match, or {@link UserHandle#USER_ALL} to apply to all - * users. + * @param uri The content uri for which the permission grant should be revoked. This uri + * must NOT contain an embedded userId; use + * {@link android.content.ContentProvider#getUriWithoutUserId(Uri)} if needed. + * This param may be {@code null} to revoke grants for all uris tracked by the + * provided owner token. + * @param mode The modes (as a bitmask) to revoke. See + * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION}, etc. + * @param userId The userId in which the given uri is to be resolved. If the {@code uri} + * param is {@code null}, this param is ignored since permissions for all + * uris will be revoked. + * @param targetPkg Target package name to match (app that received the grant), or + * {@code null} to apply to all packages. + * @param targetUserId Target user to match (userId of the app that received the grant), or + * {@link UserHandle#USER_ALL} to apply to all users. */ - void revokeUriPermissionFromOwner(IBinder token, Uri uri, int mode, int userId, - String targetPkg, int targetUserId); + void revokeUriPermissionFromOwner(@NonNull IBinder token, @Nullable Uri uri, int mode, + int userId, @Nullable String targetPkg, int targetUserId); boolean checkAuthorityGrants( int callingUid, ProviderInfo cpi, int userId, boolean checkUser); + void dump(PrintWriter pw, boolean dumpAll, String dumpPackage); } diff --git a/services/core/java/com/android/server/uri/UriGrantsManagerService.java b/services/core/java/com/android/server/uri/UriGrantsManagerService.java index dcc15999d8822..44545ed4898af 100644 --- a/services/core/java/com/android/server/uri/UriGrantsManagerService.java +++ b/services/core/java/com/android/server/uri/UriGrantsManagerService.java @@ -33,17 +33,13 @@ import static android.os.Process.ROOT_UID; import static android.os.Process.SYSTEM_UID; import static android.os.Process.myUid; -import static com.android.internal.util.XmlUtils.readBooleanAttribute; -import static com.android.internal.util.XmlUtils.readIntAttribute; -import static com.android.internal.util.XmlUtils.readLongAttribute; import static com.android.internal.util.XmlUtils.writeBooleanAttribute; -import static com.android.internal.util.XmlUtils.writeIntAttribute; -import static com.android.internal.util.XmlUtils.writeLongAttribute; import static com.android.server.uri.UriGrantsManagerService.H.PERSIST_URI_GRANTS_MSG; import static org.xmlpull.v1.XmlPullParser.END_DOCUMENT; import static org.xmlpull.v1.XmlPullParser.START_TAG; +import android.annotation.NonNull; import android.annotation.Nullable; import android.app.ActivityManager; import android.app.ActivityManagerInternal; @@ -82,7 +78,6 @@ import android.util.Xml; import com.android.internal.annotations.GuardedBy; import com.android.internal.annotations.VisibleForTesting; import com.android.internal.util.ArrayUtils; -import com.android.internal.util.FastXmlSerializer; import com.android.internal.util.Preconditions; import com.android.server.IoThread; import com.android.server.LocalServices; @@ -94,9 +89,7 @@ import com.google.android.collect.Maps; import libcore.io.IoUtils; -import org.xmlpull.v1.XmlPullParser; import org.xmlpull.v1.XmlPullParserException; -import org.xmlpull.v1.XmlSerializer; import java.io.File; import java.io.FileInputStream; @@ -104,7 +97,6 @@ import java.io.FileNotFoundException; import java.io.FileOutputStream; import java.io.IOException; import java.io.PrintWriter; -import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.Collections; import java.util.Iterator; @@ -211,6 +203,21 @@ public class UriGrantsManagerService extends IUriGrantsManager.Stub { } } + /** + * Grant uri permissions to the specified app. + * + * @param token An opaque owner token for tracking the permissions. See + * {@link UriGrantsManagerInternal#newUriPermissionOwner}. + * @param fromUid The uid of the grantor app that has permissions to the uri. Permissions + * will be granted on behalf of this app. + * @param targetPkg The package name of the grantor app that has permissions to the uri. + * Permissions will be granted on behalf of this app. + * @param uri The uri for which permissions should be granted. This uri must NOT contain an + * embedded userId; use {@link ContentProvider#getUriWithoutUserId(Uri)} if needed. + * @param modeFlags The modes to grant. See {@link Intent#FLAG_GRANT_READ_URI_PERMISSION}, etc. + * @param sourceUserId The userId in which the uri is to be resolved. + * @param targetUserId The userId of the target app to receive the grant. + */ @Override public void grantUriPermissionFromOwner(IBinder token, int fromUid, String targetPkg, Uri uri, final int modeFlags, int sourceUserId, int targetUserId) { @@ -219,12 +226,11 @@ public class UriGrantsManagerService extends IUriGrantsManager.Stub { } /** - * @param uri This uri must NOT contain an embedded userId. - * @param sourceUserId The userId in which the uri is to be resolved. - * @param targetUserId The userId of the app that receives the grant. + * See {@link #grantUriPermissionFromOwner(IBinder, int, String, Uri, int, int, int)}. */ - private void grantUriPermissionFromOwnerUnlocked(IBinder token, int fromUid, String targetPkg, - Uri uri, final int modeFlags, int sourceUserId, int targetUserId) { + private void grantUriPermissionFromOwnerUnlocked(@NonNull IBinder token, int fromUid, + @NonNull String targetPkg, @NonNull Uri uri, final int modeFlags, + int sourceUserId, int targetUserId) { targetUserId = mAmInternal.handleIncomingUser(Binder.getCallingPid(), Binder.getCallingUid(), targetUserId, false, ALLOW_FULL_ONLY, "grantUriPermissionFromOwner", null);