Defining Permissions

This document describes how app developers can use the security features provided by Android to define their own permissions. By defining custom permissions, an app can share its resources and capabilities with other apps. For more information about permissions, see Android Security Overview.

Background

Android is a privilege-separated operating system, in which each app runs with a distinct system identity (Linux user ID and group ID). Parts of the system are also separated into distinct identities. Linux thereby isolates apps from each other and from the system.

Apps can expose their functionality to other apps by defining permissions which those other apps can request. They can also define permissions which are automatically made available to any other apps which are signed with the same certificate.

App signing

All APKs (.apk files) must be signed with a certificate whose private key is held by their developer. This certificate identifies the author of the app. The certificate does not need to be signed by a certificate authority; it is perfectly allowable, and typical, for Android apps to use self-signed certificates. The purpose of certificates in Android is to distinguish app authors. This allows the system to grant or deny apps access to signature-level permissions and to grant or deny an app's request to be given the same Linux identity as another app.

User IDs and file access

At install time, Android gives each package a distinct Linux user ID. The identity remains constant for the duration of the package's life on that device. On a different device, the same package may have a different UID; what matters is that each package has a distinct UID on a given device.

Because security enforcement happens at the process level, the code of any two packages cannot normally run in the same process, since they need to run as different Linux users. You can use the sharedUserId attribute in the AndroidManifest.xml's manifest tag of each package to have them assigned the same user ID. By doing this, for purposes of security the two packages are then treated as being the same app, with the same user ID and file permissions. Note that in order to retain security, only two apps signed with the same signature (and requesting the same sharedUserId) will be given the same user ID.

Any data stored by an app will be assigned that app's user ID, and not normally accessible to other packages.

Defining and Enforcing Permissions

To enforce your own permissions, you must first declare them in your AndroidManifest.xml using one or more <permission> elements.

For example, an app that wants to control who can start one of its activities could declare a permission for this operation as follows:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp" >
    <permission android:name="com.example.myapp.permission.DEADLY_ACTIVITY"
        android:label="@string/permlab_deadlyActivity"
        android:description="@string/permdesc_deadlyActivity"
        android:permissionGroup="android.permission-group.COST_MONEY"
        android:protectionLevel="dangerous" />
    ...
</manifest>

Note: The system does not allow multiple packages to declare a permission with the same name, unless all the packages are signed with the same certificate. If a package declares a permission, the system does not permit the user to install other packages with the same permission name, unless those packages are signed with the same certificate as the first package. To avoid naming collisions, we recommend using reverse-domain-style naming for custom permissions, for example com.example.myapp.ENGAGE_HYPERSPACE.

The protectionLevel attribute is required, telling the system how the user is to be informed of apps requiring the permission, or who is allowed to hold that permission, as described in the linked documentation.

The android:permissionGroup attribute is optional, and only used to help the system display permissions to the user. In most cases you will want to set this to a standard system group (listed in android.Manifest.permission_group), although you can define a group yourself. It is preferable to use an existing group, as this simplifies the permission UI shown to the user.

You need to supply both a label and description for the permission. These are string resources that the user can see when they are viewing a list of permissions (android:label) or details on a single permission ( android:description). The label should be short; a few words describing the key piece of functionality the permission is protecting. The description should be a couple of sentences describing what the permission allows a holder to do. Our convention is a two-sentence description: the first sentence describes the permission, and the second sentence warns the user of the type of things that can go wrong if an app is granted the permission.

Here is an example of a label and description for the CALL_PHONE permission:

<string name="permlab_callPhone">directly call phone numbers</string>
<string name="permdesc_callPhone">Allows the app to call
    phone numbers without your intervention. Malicious apps may
    cause unexpected calls on your phone bill. Note that this does not
    allow the app to call emergency numbers.</string>

Custom permission recommendations

Apps can define their own custom permissions and request custom permissions from other apps by defining <uses-permission> elements. However, you should carefully assess whether it is necessary for your app to do so.

• If you are designing a suite of apps that expose functionality to one another, try to design the apps so that each permission is defined only once. You must do this if the apps are not all signed with the same certificate. Even if the apps are all signed with the same certificate, it's a best practice to define each permission once only.
• If the functionality is only available to apps signed with the same signature as the providing app, you may be able to avoid defining custom permissions by using signature checks. When one of your apps makes a request of another of your apps, the second app can verify that both apps are signed with the same certificate before complying with the request.
• If you are developing a suite of apps runs only on your own devices, you should develop and install a package that manages permissions for all the apps in the suite. This package does not need to provide any services itself. It just declares all the permissions, and the other apps in the suite request those permissions with the <uses-permission> element.

Enforcing permissions in AndroidManifest.xml

You can apply high-level permissions restricting access to entire components of the system or app through your AndroidManifest.xml. To do this, include an android:permission attribute on the desired component, naming the permission that controls access to it.

Activity permissions (applied to the <activity> tag) restrict who can start the associated activity. The permission is checked during Context.startActivity() and Activity.startActivityForResult(); if the caller does not have the required permission then SecurityException is thrown from the call.

Service permissions (applied to the <service> tag) restrict who can start or bind to the associated service. The permission is checked during Context.startService(), Context.stopService() and Context.bindService(); if the caller does not have the required permission then SecurityException is thrown from the call.

BroadcastReceiver permissions (applied to the <receiver> tag) restrict who can send broadcasts to the associated receiver. The permission is checked after Context.sendBroadcast() returns, as the system tries to deliver the submitted broadcast to the given receiver. As a result, a permission failure will not result in an exception being thrown back to the caller; it will just not deliver the intent. In the same way, a permission can be supplied to Context.registerReceiver() to control who can broadcast to a programmatically registered receiver. Going the other way, a permission can be supplied when calling Context.sendBroadcast() to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see below).

ContentProvider permissions (applied to the <provider> tag) restrict who can access the data in a ContentProvider. (Content providers have an important additional security facility available to them called URI permissions which is described later.) Unlike the other components, there are two separate permission attributes you can set: android:readPermission restricts who can read from the provider, and android:writePermission restricts who can write to it. Note that if a provider is protected with both a read and write permission, holding only the write permission does not mean you can read from a provider. The permissions are checked when you first retrieve a provider (if you don't have either permission, a SecurityException will be thrown), and as you perform operations on the provider. Using ContentResolver.query() requires holding the read permission; using ContentResolver.insert(), ContentResolver.update(), ContentResolver.delete() requires the write permission. In all of these cases, not holding the required permission results in a SecurityException being thrown from the call.

Enforcing permissions when sending broadcasts

In addition to the permission enforcing who can send Intents to a registered BroadcastReceiver (as described above), you can also specify a required permission when sending a broadcast. By calling Context.sendBroadcast() with a permission string, you require that a receiver's app must hold that permission in order to receive your broadcast.

Note that both a receiver and a broadcaster can require a permission. When this happens, both permission checks must pass for the Intent to be delivered to the associated target.

For more information, see Restricting broadcasts with permissions.

Other permission enforcement

Arbitrarily fine-grained permissions can be enforced at any call into a service. This is accomplished with the Context.checkCallingPermission() method. Call with a desired permission string and it will return an integer indicating whether that permission has been granted to the current calling process. Note that this can only be used when you are executing a call coming in from another process, usually through an IDL interface published from a service or in some other way given to another process.

There are a number of other useful ways to check permissions. If you have the pid of another process, you can use the Context method Context.checkPermission(String, int, int) to check a permission against that pid. If you have the package name of another app, you can use the direct PackageManager method PackageManager.checkPermission(String, String) to find out whether that particular package has been granted a specific permission.

URI Permissions

The standard permission system described so far is often not sufficient when used with content providers. A content provider may want to protect itself with read and write permissions, while its direct clients also need to hand specific URIs to other apps for them to operate on. A typical example is attachments in a mail app. Access to the mail should be protected by permissions, since this is sensitive user data. However, if a URI to an image attachment is given to an image viewer, that image viewer will not have permission to open the attachment since it has no reason to hold a permission to access all e-mail.

The solution to this problem is per-URI permissions: when starting an activity or returning a result to an activity, the caller can set Intent.FLAG_GRANT_READ_URI_PERMISSION and/or Intent.FLAG_GRANT_WRITE_URI_PERMISSION. This grants the receiving activity permission access the specific data URI in the Intent, regardless of whether it has any permission to access data in the content provider corresponding to the Intent.

This mechanism allows a common capability-style model where user interaction (opening an attachment, selecting a contact from a list, etc) drives ad-hoc granting of fine-grained permission. This can be a key facility for reducing the permissions needed by apps to only those directly related to their behavior.

The granting of fine-grained URI permissions does, however, require some cooperation with the content provider holding those URIs. It is strongly recommended that content providers implement this facility, and declare that they support it through the android:grantUriPermissions attribute or <grant-uri-permissions> tag.

More information can be found in the Context.grantUriPermission(), Context.revokeUriPermission(), and Context.checkUriPermission() methods.