| page.title=System Permissions |
| page.tags=permissions |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#arch">Security Architecture</a></li> |
| <li><a href="#signing">Application Signing</a></li> |
| <li><a href="#userid">User IDs and File Access</a></li> |
| <li><a href="#permissions">Using Permissions</a></li> |
| <li><a href="#normal-dangerous">Normal and Dangerous Permissions</a> |
| <ol> |
| <li><a href="#perm-groups">Permission Groups</a></li> |
| </ol> |
| </li> |
| <li><a href="#defining">Defining and Enforcing Permissions</a> |
| <ol> |
| <li><a href="#custom-recommendations">Custom permission recommendations</a></li> |
| <li><a href="#manifest">...in AndroidManifest.xml</a></li> |
| <li><a href="#broadcasts">...when Sending Broadcasts</a></li> |
| <li><a href="#enforcement">Other Permission Enforcement</a></li> |
| </ol></li> |
| <li><a href="#uri">URI Permissions</a></li> |
| </ol> |
| |
| <h2>Key classes</h2> |
| <ol> |
| <li>{@link android.Manifest.permission}</li> |
| <li>{@link android.Manifest.permission_group}</li> |
| </ol> |
| |
| <h2>See Also</h2> |
| <ol> |
| <li><a href="{@docRoot}training/permissions/index.html">Working with System |
| Permissions</a></li> |
| </ol> |
| |
| <!-- |
| <h2>See also</h2> |
| <ol> |
| <li></li> |
| </ol> |
| --> |
| </div> |
| </div> |
| |
| <a class="notice-designers" |
| href="https://www.google.com/design/spec/patterns/permissions.html"> |
| <div> |
| <h3>Design Patterns</h3> |
| <p>Permissions</p> |
| </div> |
| </a> |
| |
| <!-- video box --> |
| <a class="notice-developers-video" |
| href="https://www.youtube.com/watch?v=f17qe9vZ8RM"> |
| <div> |
| <h3>Video</h3> |
| <p>Google I/O 2015—Android M Permissions: Best Practices for |
| Developers</p> |
| </div> |
| </a> |
| |
| <p>Android is a privilege-separated operating system, in which each |
| application 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 applications from each other and from the system.</p> |
| |
| <p>Additional finer-grained security features are provided through a |
| "permission" mechanism that enforces restrictions on the specific operations |
| that a particular process can perform, and per-URI permissions for granting |
| ad hoc access to specific pieces of data.</p> |
| |
| <p>This document describes how application developers can use the |
| security features provided by Android. A more general <a |
| href="http://source.android.com/tech/security/index.html" |
| class="external-link">Android Security |
| Overview</a> is provided in the Android Open Source Project.</p> |
| |
| |
| <a name="arch"></a> |
| <h2>Security Architecture</h2> |
| |
| <p>A central design point of the Android security architecture is that no |
| application, by default, has permission to perform any operations that would |
| adversely impact other applications, the operating system, or the user. This |
| includes reading or writing the user's private data (such as contacts or |
| emails), reading or writing another application's files, performing |
| network access, keeping the device awake, and so on.</p> |
| |
| <p>Because each Android application operates in a process sandbox, applications |
| must explicitly share resources and data. They do this by declaring the |
| <em>permissions</em> they need for additional capabilities not provided by |
| the basic sandbox. Applications statically declare the permissions they |
| require, and the Android system prompts the user for consent.</p> |
| |
| <p>The application sandbox does not depend on the technology used to build |
| an application. In particular the Dalvik VM is not a security boundary, and |
| any app can run native code (see <a href="{@docRoot}tools/sdk/ndk/index.html">the Android |
| NDK</a>). All types of applications — Java, native, and hybrid — |
| are sandboxed in the same way and have the same degree of security from each |
| other.</p> |
| |
| |
| <a name="signing"></a> |
| <h2>Application Signing</h2> |
| |
| <p>All APKs ({@code .apk} files) must be signed with a certificate |
| whose private key is held by their developer. This certificate identifies |
| the author of the application. The certificate does <em>not</em> need to be |
| signed by a certificate authority; it is perfectly allowable, and typical, |
| for Android applications to use self-signed certificates. The purpose of |
| certificates in Android is to distinguish application authors. This allows |
| the system to grant or deny applications access to <a |
| href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature-level |
| permissions</a> and to grant or deny an application's <a |
| href="{@docRoot}guide/topics/manifest/manifest-element.html#uid">request to be given |
| the same Linux identity</a> as another application.</p> |
| |
| <a name="userid"></a> |
| <h2>User IDs and File Access</h2> |
| |
| <p>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.</p> |
| |
| <p>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 {@link android.R.attr#sharedUserId} attribute in the |
| <code>AndroidManifest.xml</code>'s |
| {@link android.R.styleable#AndroidManifest 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 application, with the same |
| user ID and file permissions. Note that in order to retain security, only two applications |
| signed with the same signature (and requesting the same sharedUserId) will |
| be given the same user ID.</p> |
| |
| <p>Any data stored by an application will be assigned that application's user |
| ID, and not normally accessible to other packages. When creating a new file |
| with {@link android.content.Context#getSharedPreferences}, |
| {@link android.content.Context#openFileOutput}, or |
| {@link android.content.Context#openOrCreateDatabase}, |
| you can use the |
| {@link android.content.Context#MODE_WORLD_READABLE} and/or |
| {@link android.content.Context#MODE_WORLD_WRITEABLE} flags to allow any other |
| package to read/write the file. When setting these flags, the file is still |
| owned by your application, but its global read and/or write permissions have |
| been set appropriately so any other application can see it.</p> |
| |
| |
| <h2 id="permissions">Using Permissions</h2> |
| |
| <p>A basic Android application has no permissions associated with it by default, |
| meaning it cannot do anything that would adversely impact the user experience |
| or any data on the device. To make use of protected features of the device, |
| you must include one or more |
| <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html" |
| ><code><uses-permission></code></a> |
| tags in your <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">app |
| manifest</a>.</p> |
| |
| <p>For example, an application that needs to monitor incoming SMS messages would |
| specify:</p> |
| |
| <pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" |
| package="com.android.app.myapp" > |
| <uses-permission android:name="android.permission.RECEIVE_SMS" /> |
| ... |
| </manifest></pre> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h3>Permission Levels</h3> |
| <p>For more information about the different protection levels for |
| permissions, see <a href="#normal-dangerous">Normal and Dangerous |
| Permissions</a>.</p> |
| </div> |
| </div> |
| |
| <p> |
| If your app lists <em>normal</em> permissions in its manifest (that is, |
| permissions that don't pose much risk to the user's privacy or the device's |
| operation), the system automatically grants those permissions. |
| If your app lists <em>dangerous</em> permissions in its manifest (that is, |
| permissions that could potentially affect the user's privacy or the device's |
| normal operation), the system asks the user to explicitly grant those |
| permissions. The way Android makes the requests depends on the system |
| version, and the system version targeted by your app: |
| </p> |
| |
| <ul> |
| <li>If the device is running Android 6.0 (API level 23) or higher, |
| <em>and</em> the app's <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target" |
| ><code>targetSdkVersion</code></a> |
| is 23 or higher, the app requests permissions from the user at run-time. |
| The user can revoke the permissions at any time, so the app needs to |
| check whether it has the permissions every time it runs. |
| For more information about requesting permissions in your app, see the |
| <a href="{@docRoot}training/permissions/index.html">Working with System |
| Permissions</a> training guide. |
| </li> |
| |
| <li>If the device is running Android 5.1 (API level 22) or lower, <em>or</em> |
| the app's <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target" |
| ><code>targetSdkVersion</code></a> |
| is 22 or lower, the system asks the user to grant the permissions when the |
| user installs the app. If you add a new permission to an updated version of |
| the app, the system asks the user to grant that permission when the user |
| updates the app. Once the user installs the app, the only way they can |
| revoke the permission is by uninstalling the app. |
| </li> |
| </ul> |
| |
| <p>Often times a permission failure will result in a {@link |
| java.lang.SecurityException} being thrown back to the application. However, |
| this is not guaranteed to occur everywhere. For example, the {@link |
| android.content.Context#sendBroadcast} method checks permissions as data is |
| being delivered to each receiver, after the method call has returned, so you |
| will not receive an exception if there are permission failures. In almost all |
| cases, however, a permission failure will be printed to the system log.</p> |
| |
| <p>The permissions provided by the Android system can be found at {@link |
| android.Manifest.permission}. Any application may also define and enforce its |
| own permissions, so this is not a comprehensive list of all possible |
| permissions.</p> |
| |
| <p>A particular permission may be enforced at a number of places during your |
| program's operation:</p> |
| |
| <ul> |
| <li>At the time of a call into the system, to prevent an application from |
| executing certain functions.</li> |
| <li>When starting an activity, to prevent applications from launching |
| activities of other applications.</li> |
| <li>Both sending and receiving broadcasts, to control who can receive |
| your broadcast or who can send a broadcast to you.</li> |
| <li>When accessing and operating on a content provider.</li> |
| <li>Binding to or starting a service.</li> |
| </ul> |
| |
| <h3 id="auto-adjustments">Automatic permission adjustments</h3> |
| |
| <p> Over time, |
| new restrictions may be added to the platform such that, in order |
| to use certain APIs, your app must request a permission that it previously did not need. |
| Because existing apps assume access to those APIs is freely available, |
| Android may apply the new permission request to the app's manifest to avoid |
| breaking the app on the new platform version. |
| Android makes the decision as to whether an app might need the permission based on |
| the value provided for the <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> |
| attribute. If the value is lower than the version in which the permission was added, then |
| Android adds the permission.</p> |
| <p>For example, the {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission was |
| added in API level 4 to restrict access to the shared storage space. If your <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> |
| is 3 or lower, this permission is added to your app on newer versions of Android.</p> |
| |
| <p class="caution"> |
| <strong>Caution:</strong> If a permission is automatically added to your app, |
| your app listing on Google Play lists these additional permissions even |
| though your app might not actually require them. |
| </p> |
| |
| <p>To avoid this and remove the default permissions you don't need, always update your <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> |
| to be as high as possible. You can see which permissions were added with each release in the |
| {@link android.os.Build.VERSION_CODES} documentation.</p> |
| </div> |
| |
| <h2 id="normal-dangerous">Normal and Dangerous Permissions</h2> |
| |
| <p> |
| System permissions are divided into several protection levels. The two most |
| important protection levels to know about are <em>normal</em> and |
| <em>dangerous</em> permissions: |
| </p> |
| |
| <ul> |
| <li> |
| <em>Normal</em> permissions cover areas where your app needs to access data |
| or resources outside the app's sandbox, but where there's very little risk |
| to the user's privacy or the operation of other apps. For example, |
| permission to set the time zone is a normal permission. If an app |
| declares that it needs a normal permission, the system automatically grants |
| the permission to the app. For a full listing of the current normal |
| permissions, see <a href="normal-permissions.html">Normal permissions</a>. |
| </li> |
| |
| <li> |
| <em>Dangerous</em> permissions cover areas where the app wants data or |
| resources that involve the user's private information, or could potentially |
| affect the user's stored data or the operation of other apps. For example, |
| the ability to read the user's contacts is a dangerous permission. If an |
| app declares that it needs a dangerous permission, the user has to |
| explicitly grant the permission to the app. |
| </li> |
| </ul> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h3 id="special_permissions">Special Permissions</h3> |
| <p> |
| There are a couple of permissions that don't behave like normal and |
| dangerous permissions. {@link android.Manifest.permission#SYSTEM_ALERT_WINDOW |
| SYSTEM_ALERT_WINDOW} and {@link android.Manifest.permission#WRITE_SETTINGS |
| WRITE_SETTINGS} are particularly sensitive, so most apps should not use |
| them. If an app needs one of these permissions, it must declare the |
| permission in the manifest, <em>and</em> send an intent requesting the |
| user's authorization. The system responds to the intent by showing a |
| detailed management screen to the user. |
| </p> |
| |
| <p> |
| For details on how to request these permissions, see the {@link |
| android.Manifest.permission#SYSTEM_ALERT_WINDOW SYSTEM_ALERT_WINDOW} and |
| {@link android.Manifest.permission#WRITE_SETTINGS WRITE_SETTINGS} reference |
| entries. |
| </p> |
| </div> |
| </div> |
| |
| <h3 id="perm-groups">Permission groups</h3> |
| |
| <p> |
| All dangerous Android system permissions belong to permission groups. |
| If the device is running Android 6.0 (API level 23) and the app's <a href= |
| "{@docRoot}guide/topics/manifest/uses-sdk-element.html#target" |
| ><code>targetSdkVersion</code></a> is 23 or higher, the following system |
| behavior applies when your app requests a dangerous permission: |
| </p> |
| |
| <ul> |
| <li>If an app requests a dangerous permission listed in its manifest, and the app |
| does not currently have any permissions in the permission group, the system |
| shows a dialog box to the user describing the permission group that the app |
| wants access to. The dialog box does not describe the specific permission |
| within that group. For example, if an app requests the {@link |
| android.Manifest.permission#READ_CONTACTS READ_CONTACTS} permission, the |
| system dialog box just says the app needs access to the device's contacts. If |
| the user grants approval, the system gives the app just the permission it |
| requested. |
| </li> |
| |
| <li>If an app requests a dangerous permission listed in its manifest, and the app |
| already has another dangerous permission in the same permission group, the |
| system immediately grants the permission without any interaction with the |
| user. For example, if an app had previously requested and been granted the |
| {@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS} permission, |
| and it then requests {@link android.Manifest.permission#WRITE_CONTACTS |
| WRITE_CONTACTS}, the system immediately grants that permission. |
| </li> |
| </ul> |
| |
| <p class="aside"> |
| Any permission can belong to a permission group, including normal permissions |
| and permissions defined by your app. |
| However, a permission's group only affects the user experience if the |
| permission is dangerous. You can ignore the permission group for normal |
| permissions. |
| </p> |
| |
| <p> |
| If the device is running Android 5.1 (API level 22) or lower, or the app's |
| <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target" |
| ><code>targetSdkVersion</code></a> is 22 or lower, the system asks the user |
| to grant the permissions at install time. Once again, the system just tells |
| the user what permission <em>groups</em> the app needs, not the individual |
| permissions. |
| </p> |
| |
| <p class="table-caption" id="permission-groups"> |
| <strong>Table 1.</strong> Dangerous permissions and permission groups.</p> |
| <table> |
| <tr> |
| <th scope="col">Permission Group</th> |
| <th scope="col">Permissions</th> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#CALENDAR CALENDAR}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#READ_CALENDAR READ_CALENDAR} |
| </li> |
| </ul> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#WRITE_CALENDAR WRITE_CALENDAR} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#CAMERA CAMERA}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#CAMERA CAMERA} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#CONTACTS CONTACTS}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS} |
| </li> |
| <li> |
| {@link android.Manifest.permission#WRITE_CONTACTS WRITE_CONTACTS} |
| </li> |
| <li> |
| {@link android.Manifest.permission#GET_ACCOUNTS GET_ACCOUNTS} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#LOCATION LOCATION}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION} |
| </li> |
| <li> |
| {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#MICROPHONE MICROPHONE}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#RECORD_AUDIO RECORD_AUDIO} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#PHONE PHONE}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} |
| </li> |
| <li> |
| {@link android.Manifest.permission#CALL_PHONE CALL_PHONE} |
| </li> |
| <li> |
| {@link android.Manifest.permission#READ_CALL_LOG READ_CALL_LOG} |
| </li> |
| <li> |
| {@link android.Manifest.permission#WRITE_CALL_LOG WRITE_CALL_LOG} |
| </li> |
| <li> |
| {@link android.Manifest.permission#ADD_VOICEMAIL ADD_VOICEMAIL} |
| </li> |
| <li> |
| {@link android.Manifest.permission#USE_SIP USE_SIP} |
| </li> |
| <li> |
| {@link android.Manifest.permission#PROCESS_OUTGOING_CALLS PROCESS_OUTGOING_CALLS} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#SENSORS SENSORS}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#BODY_SENSORS BODY_SENSORS} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td>{@link android.Manifest.permission_group#SMS SMS}</td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#SEND_SMS SEND_SMS} |
| </li> |
| <li> |
| {@link android.Manifest.permission#RECEIVE_SMS RECEIVE_SMS} |
| </li> |
| <li> |
| {@link android.Manifest.permission#READ_SMS READ_SMS} |
| </li> |
| <li> |
| {@link android.Manifest.permission#RECEIVE_WAP_PUSH RECEIVE_WAP_PUSH} |
| </li> |
| <li> |
| {@link android.Manifest.permission#RECEIVE_MMS RECEIVE_MMS} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| {@link android.Manifest.permission_group#STORAGE STORAGE} |
| </td> |
| <td> |
| <ul> |
| <li> |
| {@link android.Manifest.permission#READ_EXTERNAL_STORAGE |
| READ_EXTERNAL_STORAGE} |
| </li> |
| <li> |
| {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE |
| WRITE_EXTERNAL_STORAGE} |
| </li> |
| </ul> |
| </td> |
| </tr> |
| |
| </table> |
| |
| |
| <a name="declaring"></a> |
| <h2 id="defining">Defining and Enforcing Permissions</h2> |
| |
| <p> |
| To enforce your own permissions, you must first declare them in your |
| <code>AndroidManifest.xml</code> using one or more <a href= |
| "{@docRoot}guide/topics/manifest/permission-element.html"><code><permission></code></a> |
| elements. |
| </p> |
| |
| <p>For example, an application that wants to control who can start one |
| of its activities could declare a permission for this operation as follows:</p> |
| |
| <pre><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></pre> |
| |
| <p class="note"> |
| <strong>Note:</strong> 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 <code>com.example.myapp.ENGAGE_HYPERSPACE</code>. |
| </p> |
| |
| <p>The {@link android.R.styleable#AndroidManifestPermission_protectionLevel |
| protectionLevel} attribute is required, telling the system how the |
| user is to be informed of applications requiring the permission, or who is |
| allowed to hold that permission, as described in the linked documentation.</p> |
| |
| <p> |
| The <a href= |
| "{@docRoot}guide/topics/manifest/permission-group-element.html" |
| ><code>android:permissionGroup</code></a> |
| 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 {@link android.Manifest.permission_group |
| 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. |
| </p> |
| |
| <p>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 |
| (<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>) |
| or details on a single permission ( |
| <code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>). |
| 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 application is granted the |
| permission.</p> |
| |
| <p>Here is an example of a label and description for the CALL_PHONE |
| permission:</p> |
| |
| <pre> |
| <string name="permlab_callPhone">directly call phone numbers</string> |
| <string name="permdesc_callPhone">Allows the application to call |
| phone numbers without your intervention. Malicious applications may |
| cause unexpected calls on your phone bill. Note that this does not |
| allow the application to call emergency numbers.</string> |
| </pre> |
| |
| <p>You can view at the permissions currently defined in the system using the |
| Settings app and the shell command <code>adb shell pm list permissions</code>. |
| To use the Settings app, go to <b>Settings</b> > <b>Applications</b>. Pick an app and |
| scroll down to see the permissions that the app uses. For developers, the adb '-s' |
| option displays the permissions in a form similar to how the user will see them:</p> |
| |
| <pre class="no-pretty-print"> |
| $ adb shell pm list permissions -s |
| All Permissions: |
| |
| Network communication: view Wi-Fi state, create Bluetooth connections, full |
| Internet access, view network state |
| |
| Your location: access extra location provider commands, fine (GPS) location, |
| mock location sources for testing, coarse (network-based) location |
| |
| Services that cost you money: send SMS messages, directly call phone numbers |
| |
| ...</pre> |
| |
| <h3 id="custom-recommendations"> |
| Custom permission recommendations |
| </h3> |
| |
| <p> |
| Apps can define their own custom permissions and request custom permissions |
| from other apps by defining <a href= |
| "{@docRoot}guide/topics/manifest/uses-permission-element.html"><code |
| ><uses-permission></code></a> elements. |
| However, you should carefully assess whether it is necessary for your app to |
| do so. |
| </p> |
| |
| <ul> |
| <li>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. |
| </li> |
| |
| <li>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. |
| </li> |
| |
| <li>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 <a href= |
| "{@docRoot}guide/topics/manifest/uses-permission-element.html"><code |
| ><uses-permission></code></a> |
| element. |
| </li> |
| </ul> |
| |
| <a name="manifest"></a> |
| <h3>Enforcing Permissions in AndroidManifest.xml</h3> |
| |
| <p>You can apply high-level permissions restricting access to entire components |
| of the system or application through your |
| <code>AndroidManifest.xml</code>. To do this, include an {@link |
| android.R.attr#permission android:permission} attribute on the desired |
| component, naming the permission that controls access to |
| it.</p> |
| |
| <p><strong>{@link android.app.Activity}</strong> permissions |
| (applied to the |
| {@link android.R.styleable#AndroidManifestActivity <activity>} tag) |
| restrict who can start the associated |
| activity. The permission is checked during |
| {@link android.content.Context#startActivity Context.startActivity()} and |
| {@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}; |
| if the caller does not have |
| the required permission then {@link java.lang.SecurityException} is thrown |
| from the call.</p> |
| |
| <p><strong>{@link android.app.Service}</strong> permissions |
| (applied to the |
| {@link android.R.styleable#AndroidManifestService <service>} tag) |
| restrict who can start or bind to the |
| associated service. The permission is checked during |
| {@link android.content.Context#startService Context.startService()}, |
| {@link android.content.Context#stopService Context.stopService()} and |
| {@link android.content.Context#bindService Context.bindService()}; |
| if the caller does not have |
| the required permission then {@link java.lang.SecurityException} is thrown |
| from the call.</p> |
| |
| <p><strong>{@link android.content.BroadcastReceiver}</strong> permissions |
| (applied to the |
| {@link android.R.styleable#AndroidManifestReceiver <receiver>} tag) |
| restrict who can send broadcasts to the associated receiver. |
| The permission is checked <em>after</em> |
| {@link android.content.Context#sendBroadcast 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 |
| {@link android.content.Context#registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter, String, android.os.Handler) |
| Context.registerReceiver()} |
| to control who can broadcast to a programmatically registered receiver. |
| Going the other way, a permission can be supplied when calling |
| {@link android.content.Context#sendBroadcast(Intent, String) Context.sendBroadcast()} |
| to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see |
| below).</p> |
| |
| <p><strong>{@link android.content.ContentProvider}</strong> permissions |
| (applied to the |
| {@link android.R.styleable#AndroidManifestProvider <provider>} tag) |
| restrict who can access the data in |
| a {@link android.content.ContentProvider}. (Content providers have an important |
| additional security facility available to them called |
| <a href="#uri">URI permissions</a> which is described later.) |
| Unlike the other components, |
| there are two separate permission attributes you can set: |
| {@link android.R.attr#readPermission android:readPermission} restricts who |
| can read from the provider, and |
| {@link android.R.attr#writePermission 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 |
| {@link android.content.ContentResolver#query ContentResolver.query()} requires |
| holding the read permission; using |
| {@link android.content.ContentResolver#insert ContentResolver.insert()}, |
| {@link android.content.ContentResolver#update ContentResolver.update()}, |
| {@link android.content.ContentResolver#delete ContentResolver.delete()} |
| requires the write permission. |
| In all of these cases, not holding the required permission results in a |
| {@link java.lang.SecurityException} being thrown from the call.</p> |
| |
| |
| <a name="broadcasts"></a> |
| <h3>Enforcing Permissions when Sending Broadcasts</h3> |
| |
| <p>In addition to the permission enforcing who can send Intents to a |
| registered {@link android.content.BroadcastReceiver} (as described above), you |
| can also specify a required permission when sending a broadcast. By calling {@link |
| android.content.Context#sendBroadcast(android.content.Intent,String) |
| Context.sendBroadcast()} with a |
| permission string, you require that a receiver's application must hold that |
| permission in order to receive your broadcast.</p> |
| |
| <p>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.</p> |
| |
| |
| <a name="enforcement"></a> |
| <h3>Other Permission Enforcement</h3> |
| |
| <p>Arbitrarily fine-grained permissions can be enforced at any call into a |
| service. This is accomplished with the {@link |
| android.content.Context#checkCallingPermission 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.</p> |
| |
| <p>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 {@link |
| android.content.Context#checkPermission(String, int, int) Context.checkPermission(String, int, int)} |
| to check a permission against that pid. If you have the package name of another |
| application, you can use the direct PackageManager method {@link |
| android.content.pm.PackageManager#checkPermission(String, String) |
| PackageManager.checkPermission(String, String)} |
| to find out whether that particular package has been granted a specific permission.</p> |
| |
| |
| <a name="uri"></a> |
| <h2>URI Permissions</h2> |
| |
| <p>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 applications for them to operate on. |
| A typical example is attachments in a mail application. 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.</p> |
| |
| <p>The solution to this problem is per-URI permissions: when starting an |
| activity or returning a result to an activity, the caller can set |
| {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION |
| Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or |
| {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION |
| 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.</p> |
| |
| <p>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 applications to only those directly related to their |
| behavior.</p> |
| |
| <p>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 |
| {@link android.R.styleable#AndroidManifestProvider_grantUriPermissions |
| android:grantUriPermissions} attribute or |
| {@link android.R.styleable#AndroidManifestGrantUriPermission |
| <grant-uri-permissions>} tag.</p> |
| |
| <p>More information can be found in the |
| {@link android.content.Context#grantUriPermission Context.grantUriPermission()}, |
| {@link android.content.Context#revokeUriPermission Context.revokeUriPermission()}, and |
| {@link android.content.Context#checkUriPermission Context.checkUriPermission()} |
| methods.</p> |
| |
| <div class="next-docs"> |
| <div class="col-6"> |
| <h2 class="norule">Continue reading about:</h2> |
| <dl> |
| <dt><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions" |
| >Permissions that Imply Feature Requirements</a></dt> |
| <dd>Information about how requesting some permissions will implicitly restrict your app |
| to devices that include the corresponding hardware or software feature.</dd> |
| <dt><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">{@code |
| <uses-permission>}</a></dt> |
| <dd>API reference for the manifest tag that declare's your app's required system permissions. |
| </dd> |
| <dt>{@link android.Manifest.permission}</dt> |
| <dd>API reference for all system permissions.</dd> |
| </dl> |
| </div> |
| <div class="col-6"> |
| <h2 class="norule">You might also be interested in:</h2> |
| <dl> |
| <dt><a href="{@docRoot}guide/practices/compatibility.html" |
| >Device Compatibility</a></dt> |
| <dd>Information about Android works on different types of devices and an introduction |
| to how you can optimize your app for each device or restrict your app's availability |
| to different devices.</dd> |
| <dt><a href="http://source.android.com/devices/tech/security/index.html" |
| class="external-link">Android Security Overview</a></dt> |
| <dd>A detailed discussion about the Android platform's security model.</dd> |
| </dl> |
| </div> |
| </div> |