android-permissions-security

Guidelines for auditing permission vulnerabilities, enforcing least privilege, securing IPC boundaries, and handling runtime permissions across the Android ecosystem.

Glossary

• Runtime Permission: Dangerous permission (e.g., Camera, Location) that must be granted by the user at runtime on Android 6.0+ (API 23+).
• Custom Permission: A permission defined by an app (<permission>) to restrict access to its exported components.
• Protection Level: Attribute defining how the OS grants the permission (normal, dangerous, signature, knownSigner).
• knownSigner: Protection flag (API 31+) granting signature-level access to partner apps matching trusted certificate digests.
• SigningInfo: Object (API 28+) providing signing history and multiple signer certificates for an application.
• Binder Calling Identity: Reliable UID representing the calling process obtained using Binder.getCallingUid().
• URI Permission: Temporary, granular access granted to a content URI using grantUriPermissions and intent flags.

Prerequisites

• Add androidx.core:core-ktx and androidx.activity:activity-ktx (or androidx.fragment:fragment-ktx) dependencies to the app-level build.gradle file for ContextCompat and ActivityResultContracts.
• For knownSigner partner permissions (android:knownCerts), ensure the project compileSdk and targetSdk are at least 31 (Android 12).
• For broadcast identity sharing (BroadcastOptions.setShareIdentityEnabled), ensure compileSdk and targetSdk are at least 34 (Android 14).

1. Security audit and permission gap detection playbook

When auditing an Android project for permission and IPC security vulnerabilities, systematically inspect each area:

2. Custom permissions and protection levels

When declaring custom permissions or partner certificates in the manifest, you must follow the instructions in the <permission> element guide.

• signature: Restricts access to apps signed with the same developer key.
• signature|knownSigner (API 31+): Restricts access to partner apps whose signing certificate digests match declared hashes in android:knownCerts.
• normal or dangerous : Do not use for private inter-app IPC.
• signatureOrSystem : Deprecated (API 23). Upgrade deprecated signatureOrSystem permissions to signature. Avoid in non-system apps.

Manifest snippets

Signature-level custom permission

Use signature permissions when restricting component access exclusively to apps signed with the same developer certificate by declaring the <permission> in the manifest and applying android:permission to the target component.

<permission
    android:name="com.example.snippets.permission.ACCESS_SECURE_API"
    android:protectionLevel="signature" />

KnownSigner partner permission (API 31+)

Use signature|knownSigner permissions when granting access to specific external partner apps by declaring the <permission> in the manifest with android:knownCerts referencing a resource array of trusted SHA-256 certificate digests.

<resources xmlns:tools="http://schemas.android.com/tools">
    <!-- SHA-256 fingerprints of trusted partner certificates (lowercase, no colons) -->
    <string-array name="trusted_partner_certs" tools:ignore="Typos">
        <item>103938ee4537e59e8ee792f654504fb8346fc6b346d0bbc4415fc339fcfc8ec1</item>
    </string-array>
</resources>

<permission
    android:name="com.example.snippets.permission.PARTNER_API"
    android:protectionLevel="signature|knownSigner"
    android:knownCerts="@array/trusted_partner_certs" />

3. Exported component protection and URI permissions

• Private components : Always set android:exported="false".
• Exported components : Require permissions (android:permission, android:readPermission, android:writePermission).
• Granular URI Grants : Retain android:grantUriPermissions="true" for secure sharing, but scope grants to specific sub-paths. Never use wildcard pathPrefix="/".
• Custom Permission Declarations : When splitting read and write permissions on a provider, you MUST declare the <permission> tags with android:protectionLevel="signature" (or signature|knownSigner) at the <manifest> root level.
• Remediating Existing Wildcard Grants : You MUST find and remove any existing <grant-uri-permission android:pathPrefix="/" /> or pathPrefix="" and replace it with an explicit scoped subpath (e.g. android:pathPrefix="/shared/").
• Granular UriPermission Management : Instead of broad manifest grants, use runtime android.content.UriPermission tokens for least-privilege per-URI sharing:
  • Grant temporary access : context.grantUriPermission(targetPackage, uri, Intent.FLAG_GRANT_READ_URI_PERMISSION) or attach Intent.FLAG_GRANT_READ_URI_PERMISSION to outgoing intents.
  • Persist access : The receiving app calls contentResolver.takePersistableUriPermission(uri, modeFlags) for durable access across reboots.
  • Audit active grants : Inspect contentResolver.persistedUriPermissions (List<UriPermission>) to verify granted URIs (uriPermission.uri, uriPermission.isReadPermission(), uriPermission.isWritePermission()).
  • Revoke access : Call context.revokeUriPermission(uri, modeFlags) or contentResolver.releasePersistableUriPermission(uri, modeFlags) as soon as operations conclude.

Manifest snippet: Complete secure ContentProvider declaration

Declare the split read and write permissions at the <manifest> root:

<permission
    android:name="com.example.snippets.permission.READ_DATA"
    android:protectionLevel="signature" />
<permission
    android:name="com.example.snippets.permission.WRITE_DATA"
    android:protectionLevel="signature" />

Then configure the provider with those permissions and a scoped URI grant:

<provider
    android:name=".permissions.SecureDataProvider"
    android:authorities="com.example.snippets.partnerprovider"
    android:exported="true"
    android:readPermission="com.example.snippets.permission.READ_DATA"
    android:writePermission="com.example.snippets.permission.WRITE_DATA"
    android:grantUriPermissions="true">
    <grant-uri-permission android:pathPrefix="/shared/" />
</provider>

Runtime granular UriPermission management snippet

object UriPermissionManager {

    /** Grants temporary read access to a specific URI for a partner package. */
    fun grantScopedUriAccess(context: Context, targetPackage: String, uri: Uri) {
        context.grantUriPermission(
            targetPackage,
            uri,
            Intent.FLAG_GRANT_READ_URI_PERMISSION
        )
    }

    /** Audits active persisted URI permissions held by the application. */
    fun getActivePersistedPermissions(context: Context): List<UriPermission> {
        return context.contentResolver.persistedUriPermissions
    }

    /** Revokes temporary URI access when data transfer completes. */
    fun revokeScopedUriAccess(context: Context, uri: Uri) {
        context.revokeUriPermission(
            uri,
            Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION
        )
    }
}

4. Cryptographic caller identity verification

Never trust caller package names provided in Intents or string arguments (getCallingPackage(), intent.getStringExtra("calling_package"), intent.getStringExtra("sender"), intent.getStringExtra("package")). Intent extras and string package names are forged by malicious applications.

Critical vulnerability: Package name spoofing using intent extras

// VULNERABLE PATTERN: DO NOT DO THIS
val callingPackage = intent?.getStringExtra("calling_package")
if (callingPackage != null && SignatureUtils.verifyPartnerPackage(this, callingPackage)) {
    // A malicious app passes "com.example.partner" in the extra.
    // The signature check verifies the installed partner on disk, but the CALLER was malicious!
}

Secure pattern: Authenticate calling UID cryptographically

1. Completely remove all intent.getStringExtra("calling_package"), intent.getStringExtra("sender"), and callingPackage == "..." checks.
2. Obtain caller identity using Binder.getCallingUid().
3. Verify caller certificate using PackageManager.hasSigningCertificate() (API 28+) or PackageManager.getPackagesForUid().

Complete CallerVerifier implementation

Apply this to the service that currently performs the spoofable check.

• Placement : declare CallerVerifier in the same file as the service you are fixing (for example inside SecureDataService.kt). Do not move the verification into a new file and leave the original service untouched.
• Nullability : packageInfo.signatures is Array<Signature>?. Copy the ?: return false guard exactly as written below. Iterating packageInfo.signatures directly fails to compile with "Non-nullable value required to call an 'iterator()' method in a for-loop."

object CallerVerifier {
    private const val TRUSTED_PARTNER_SHA256 =
        "A1B2C3D4E5F60708090A0B0C0D0E0F1011121314151617181920212223242526"

    fun isCallerAuthorized(context: Context): Boolean {
        val callingUid = Binder.getCallingUid()
        if (callingUid == android.os.Process.myUid()) return true

        val pm = context.packageManager
        // Modern API 28+ check by UID:
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
            val certBytes = hexStringToByteArray(TRUSTED_PARTNER_SHA256)
            if (pm.hasSigningCertificate(callingUid, certBytes, PackageManager.CERT_INPUT_SHA256)) {
                return true
            }
        }

        // Fallback for legacy APIs:
        val callingPackages = pm.getPackagesForUid(callingUid) ?: return false
        for (pkg in callingPackages) {
            if (verifyPackageSignature(pm, pkg)) {
                return true
            }
        }
        return false
    }

    @Suppress("DEPRECATION")
    private fun verifyPackageSignature(pm: PackageManager, packageName: String): Boolean {
        return try {
            val packageInfo = pm.getPackageInfo(packageName, PackageManager.GET_SIGNATURES)
            val signatures = packageInfo.signatures ?: return false
            for (sig in signatures) {
                val digest = java.security.MessageDigest.getInstance("SHA-256").digest(sig.toByteArray())
                val hex = digest.joinToString("") { "%02X".format(it) }
                if (hex.equals(TRUSTED_PARTNER_SHA256, ignoreCase = true)) return true
            }
            false
        } catch (e: PackageManager.NameNotFoundException) {
            false
        }
    }

    private fun hexStringToByteArray(s: String): ByteArray {
        val len = s.length
        val data = ByteArray(len / 2)
        for (i in 0 until len step 2) {
            data[i / 2] = ((Character.digit(s[i], 16) shl 4) + Character.digit(s[i + 1], 16)).toByte()
        }
        return data
    }
}

5. Method-level Binder enforcement in bound services (SecureBoundService.kt)

In bound services exposing AIDL Binder stubs, protect state-modifying methods using enforceCallingPermission().

Critical security rule: Never use CallingOrSelfPermission in services

• NEVER use checkCallingOrSelfPermission() or enforceCallingOrSelfPermission().
• Why: During an active Binder transaction, this method checks the caller's permission. However, if the method is invoked locally (outside of an active IPC) or if the IPC calling identity is dropped, it falls back to checking the host app's permissions. Because the host app holds the permission, this fallback grants access and bypasses the security boundary, causing a Confused Deputy vulnerability.
• MUST USE: enforceCallingPermission("com.example.snippets.permission.WRITE_DATA", "Caller lacks WRITE_DATA permission") or checkCallingPermission("com.example.snippets.permission.WRITE_DATA").

Complete SecureBoundService implementation

class SecureBoundService : Service() {

    private val binder = object : IMyService.Stub() {
        override fun getData(): String {
            // Read-only operation guarded by manifest-level permission
            return "Confidential Data"
        }

        override fun modifyData(newData: String) {
            // MUST use enforceCallingPermission or checkCallingPermission.
            // NEVER use checkCallingOrSelfPermission or enforceCallingOrSelfPermission.
            this@SecureBoundService.enforceCallingPermission(
                "com.example.snippets.permission.WRITE_DATA",
                "Caller lacks WRITE_DATA permission"
            )
            updateInternalState(newData)
            Log.d("SecureBoundService", "Data modified to: $newData with proper WRITE_DATA permission check")
        }
    }

    override fun onBind(intent: Intent?): IBinder = binder

    private fun updateInternalState(data: String) {
        // Internal state update logic
    }
}

6. Safe runtime permission workflow (RuntimePermissionsActivity.kt)

When implementing runtime permission requests or handling permission denial states, you must follow the instructions in the Request runtime permissions guide and Permissions overview. Implement a 3-state flow without caching states or creating infinite retry loops:

1. Check Granted State : ContextCompat.checkSelfPermission(this, permission) == PackageManager.PERMISSION_GRANTED.
2. Check Rationale : shouldShowRequestPermissionRationale(permission) to present educational context before requesting.
3. Launch Contract : ActivityResultContracts.RequestPermission().
4. Handle Permanent Denial : In the callback, if permission was denied and !shouldShowRequestPermissionRationale(permission), guide the user to Settings.ACTION_APPLICATION_DETAILS_SETTINGS.

Complete RuntimePermissionsActivity.kt implementation

class RuntimePermissionsActivity : ComponentActivity() {

    private val cameraLauncher =
        registerForActivityResult(ActivityResultContracts.RequestPermission()) { isGranted ->
            if (isGranted) {
                startCameraPreview()
            } else {
                if (!shouldShowRequestPermissionRationale(Manifest.permission.CAMERA)) {
                    // User selected 'Don't ask again' or permanently denied.
                    // Direct user to Application Details Settings.
                    val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
                        data = Uri.fromParts("package", packageName, null)
                    }
                    startActivity(intent)
                } else {
                    showSnackbar("Camera permission is required to preview camera feed.")
                }
            }
        }

    fun requestCameraPermissionSafely() {
        val permission = Manifest.permission.CAMERA
        when {
            ContextCompat.checkSelfPermission(this, permission) == PackageManager.PERMISSION_GRANTED -> {
                startCameraPreview()
            }
            shouldShowRequestPermissionRationale(permission) -> {
                showSnackbar("Camera permission is needed to preview camera feed.")
                cameraLauncher.launch(permission)
            }
            else -> {
                cameraLauncher.launch(permission)
            }
        }
    }

    private fun startCameraPreview() {
        Log.d("RuntimePermissionsActivity", "Camera preview started")
    }

    private fun showSnackbar(msg: String) {
        Log.i("RuntimePermissionsActivity", msg)
    }
}

7. Zero-permission alternatives and sequential flows

When implementing photo or media selection, you must follow the instructions in the Photo Picker API guide to avoid requesting broad storage permissions.

• Photo Picker : Prefer ActivityResultContracts.PickVisualMedia() over requesting wide storage permissions (READ_MEDIA_IMAGES, READ_EXTERNAL_STORAGE).
• Sequential Location Flow : Request ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION first. Never request ACCESS_BACKGROUND_LOCATION simultaneously. Only request background location in a separate step after foreground is granted.

Photo picker implementation

private val photoPickerLauncher =
    registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { uri ->
        if (uri != null) {
            handleImageUri(uri)
        }
    }

fun selectPhoto() {
    photoPickerLauncher.launch(
        PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly)
    )
}

Sequential location request implementation

private val foregroundLocationLauncher =
    registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { permissions ->
        val fineGranted = permissions[Manifest.permission.ACCESS_FINE_LOCATION] ?: false
        val coarseGranted = permissions[Manifest.permission.ACCESS_COARSE_LOCATION] ?: false
        if (fineGranted || coarseGranted) {
            startForegroundLocationUpdates()
        }
    }

fun requestForegroundLocation() {
    foregroundLocationLauncher.launch(
        arrayOf(
            Manifest.permission.ACCESS_FINE_LOCATION,
            Manifest.permission.ACCESS_COARSE_LOCATION
        )
    )
}

// Background location requested only AFTER foreground is granted and user explicitly opts in:
private val backgroundLocationLauncher =
    registerForActivityResult(ActivityResultContracts.RequestPermission()) { isGranted ->
        if (isGranted) {
            startBackgroundTracking()
        }
    }

8. Stateless checks and error boundaries

• Never cache permission states in in-memory variables (e.g. cachedLocationPermissionGranted). Check ContextCompat.checkSelfPermission() dynamically before each operation.
• Wrap API calls in try-catch : Catch SecurityException around permission-protected framework calls (e.g., location queries) to handle one-time permission revocation gracefully.

fun performLocationAccess() {
    val fine = ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION)
    val coarse = ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION)
    if (fine != PackageManager.PERMISSION_GRANTED && coarse != PackageManager.PERMISSION_GRANTED) {
        requestForegroundLocation()
        return
    }

    val provider = if (fine == PackageManager.PERMISSION_GRANTED) {
        LocationManager.GPS_PROVIDER
    } else {
        LocationManager.NETWORK_PROVIDER
    }

    try {
        val location = locationManager.getLastKnownLocation(provider)
        processLocation(location)
    } catch (e: SecurityException) {
        Log.e("LocationAccess", "Permission revoked at runtime", e)
    }
}

9. Secure broadcasts (API 34+ share identity)

Use explicit intents, required receiver permissions, or Android 14+ broadcast options:

// Sender: Enforce permission and share identity
val intent = Intent("com.example.snippets.permission.ACTION_SECRET_UPDATE").apply {
    setPackage("com.example.partner") // Explicit target
}
val isUdc = Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE
val options = if (isUdc) {
    BroadcastOptions.makeBasic().apply {
        setShareIdentityEnabled(true)
    }.toBundle()
} else null

sendBroadcast(intent, "com.example.snippets.permission.RECEIVE_SECRET_UPDATE", options)

// Receiver: Validate sender on Android 14+
class ProtectedReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == "com.example.snippets.permission.ACTION_SECRET_UPDATE") {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
                val sender = sentFromPackage
                if (sender != "com.example.trusted_sender") {
                    return // Reject unauthorized sender
                }
            }
            processUpdate(intent)
        }
    }

    private fun processUpdate(intent: Intent) {}
}

Legacy compatibility (Pre-API 34) : For apps targeting API 33 or lower, attach an immutable PendingIntent extra (FLAG_IMMUTABLE) to the broadcast and authenticate the sender using pendingIntent.creatorPackage.

Quality checklist

DO

• MUST declare <permission android:name="..." android:protectionLevel="signature" /> (or signature|knownSigner) at the <manifest> root for custom permissions and ContentProvider split permissions.
• MUST explicitly set android:exported="false" for all private components to remove the need for custom permission management.
• MUST authenticate callers cryptographically using Binder.getCallingUid() and certificate hashes (PackageManager.hasSigningCertificate or getPackagesForUid) rather than checking spoofable intent extras.
• MUST check shouldShowRequestPermissionRationale() before runtime prompts and during denial handling.
• MUST direct user to Settings.ACTION_APPLICATION_DETAILS_SETTINGS when permission is permanently denied.
• MUST enforce method-level checks with enforceCallingPermission() or checkCallingPermission() on modifying AIDL methods.
• MUST scope ContentProvider URI permissions to explicit sub-paths (e.g. android:pathPrefix="/shared/") while retaining android:grantUriPermissions="true".
• MUST catch SecurityException around protected API calls.
• MUST request foreground and background location permissions sequentially, never simultaneously.

NEVER

• NEVER extract or verify package names from Intent extras (intent.getStringExtra("calling_package"), intent.getStringExtra("sender"), intent.getStringExtra("package")). Always authenticate using Binder.getCallingUid() and certificates.
• NEVER remediate caller spoofing by merely adding manifest permissions while keeping spoofable intent extra checks.
• NEVER use checkCallingOrSelfPermission() or enforceCallingOrSelfPermission() to guard external caller methods. Always use enforceCallingPermission() or checkCallingPermission().
• NEVER use deprecated signatureOrSystem.
• NEVER declare or retain <grant-uri-permission android:pathPrefix="/" /> or pathPrefix="". Always replace with a scoped sub-path.
• NEVER create infinite permission request loops on denial.
• NEVER request foreground and background location permissions in the same request.
• NEVER cache permission grant states in in-memory fields.