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 the Permissions 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 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.
For more information about Android's security model, see Android Security Overview
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 should 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>
Create a permission group
As shown in the previous section, you can use the
android:permissionGroup
attribute to help the system describe
permissions to the user. In most cases you will want to set this to a standard
system group (listed in android.Manifest.permission_group
), but you can also define your own group
with
<permission-group>
.
The
<permission-group>
element defines a label for a set of permissions—both those declared in the manifest with
<permission>
elements and those declared elsewhere. This affects only how the permissions are
grouped when presented to the user. The
<permission-group>
element does not specify the permissions that belong to the group, but
it gives the group a name.
You can place a permission in the group by assigning the group name to the
<permission>
element's
permissionGroup
attribute.
The
<permission-tree>
element declares a namespace for a group of permissions that are defined in
code.
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 apps that 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.
Continue reading about:
<uses-permission>
- API reference for the manifest tag that declares your app's required system permissions.
You might also be interested in:
- Android Security Overview
- A detailed discussion about the Android platform's security model.