1page.title=Permissions 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7<h2>In this document</h2> 8<ol> 9<li><a href="#arch">Security Architecture</a></li> 10<li><a href="#signing">Application Signing</a></li> 11<li><a href="#userid">User IDs and File Access</a></li> 12<li><a href="#permissions">Using Permissions</a></li> 13<li><a href="#declaring">Declaring and Enforcing Permissions</a> 14 <ol> 15 <li><a href="#manifest">...in AndroidManifest.xml</a></li> 16 <li><a href="#broadcasts">...when Sending Broadcasts</a></li> 17 <li><a href="#enforcement">Other Permission Enforcement</a></li> 18 </ol></li> 19<li><a href="#uri">URI Permissions</a></li> 20</ol> 21</div> 22</div> 23<p>This document describes how application developers can use the 24security features provided by Android. A more general <a 25href="http://source.android.com/tech/security/index.html"> Android Security 26Overview</a> is provided in the Android Open Source Project.</p> 27 28<p>Android is a privilege-separated operating system, in which each 29application runs with a distinct system identity (Linux user ID and group 30ID). Parts of the system are also separated into distinct identities. 31Linux thereby isolates applications from each other and from the system.</p> 32 33<p>Additional finer-grained security features are provided through a 34"permission" mechanism that enforces restrictions on the specific operations 35that a particular process can perform, and per-URI permissions for granting 36ad-hoc access to specific pieces of data.</p> 37 38<a name="arch"></a> 39<h2>Security Architecture</h2> 40 41<p>A central design point of the Android security architecture is that no 42application, by default, has permission to perform any operations that would 43adversely impact other applications, the operating system, or the user. This 44includes reading or writing the user's private data (such as contacts or 45e-mails), reading or writing another application's files, performing 46network access, keeping the device awake, etc.</p> 47 48<p>Because Android sandboxes applications from each other, applications 49must explicitly share resources and data. They do this by declaring the 50<em>permissions</em> they need for additional capabilities not provided by 51the basic sandbox. Applications statically declare the permissions they 52require, and the Android system prompts the user for consent at the time the 53application is installed. Android has no mechanism for granting permissions 54dynamically (at run-time) because it complicates the user experience to the 55detriment of security.</p> 56 57<p>The application sandbox does not depend on the technology used to build 58an application. In particular the Dalvik VM is not a security boundary, and 59any app can run native code (see <a href="/sdk/ndk/index.html">the Android 60NDK</a>). All types of applications — Java, native, and hybrid — 61are sandboxed in the same way and have the same degree of security from each 62other.</p> 63 64<a name="signing"></a> 65<h2>Application Signing</h2> 66 67<p>All Android applications (.apk files) must be signed with a certificate 68whose private key is held by their developer. This certificate identifies 69the author of the application. The certificate does <em>not</em> need to be 70signed by a certificate authority: it is perfectly allowable, and typical, 71for Android applications to use self-signed certificates. The purpose of 72certificates in Android is to distinguish application authors. This allows 73the system to grant or deny applications access to <a 74href="/guide/topics/manifest/permission-element.html#plevel">signature-level 75permissions</a> and to grant or deny an application's <a 76href="/guide/topics/manifest/manifest-element.html#uid">request to be given 77the same Linux identity</a> as another application.</p> 78 79<a name="userid"></a> 80<h2>User IDs and File Access</h2> 81 82<p>At install time, Android gives each package a distinct Linux user ID. The 83identity remains constant for the duration of the package's life on that 84device. On a different device, the same package may have a different UID; 85what matters is that each package has a distinct UID on a given device.</p> 86 87<p>Because security enforcement happens at the 88process level, the code of any two packages can not normally 89run in the same process, since they need to run as different Linux users. 90You can use the {@link android.R.attr#sharedUserId} attribute in the 91<code>AndroidManifest.xml</code>'s 92{@link android.R.styleable#AndroidManifest manifest} tag of each package to 93have them assigned the same user ID. By doing this, for purposes of security 94the two packages are then treated as being the same application, with the same 95user ID and file permissions. Note that in order to retain security, only two applications 96signed with the same signature (and requesting the same sharedUserId) will 97be given the same user ID.</p> 98 99<p>Any data stored by an application will be assigned that application's user 100ID, and not normally accessible to other packages. When creating a new file 101with {@link android.content.Context#getSharedPreferences}, 102{@link android.content.Context#openFileOutput}, or 103{@link android.content.Context#openOrCreateDatabase}, 104you can use the 105{@link android.content.Context#MODE_WORLD_READABLE} and/or 106{@link android.content.Context#MODE_WORLD_WRITEABLE} flags to allow any other 107package to read/write the file. When setting these flags, the file is still 108owned by your application, but its global read and/or write permissions have 109been set appropriately so any other application can see it.</p> 110 111 112<a name="permissions"></a> 113<h2>Using Permissions</h2> 114 115<p>A basic Android application has no permissions associated with it, 116meaning it can not do anything that would adversely impact the user experience 117or any data on the device. To make use of protected features of the device, 118you must include in your <code>AndroidManifest.xml</code> one or more 119<code>{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}</code> 120tags declaring the permissions that your application needs.</p> 121 122<p>For example, an application that needs to monitor incoming SMS messages would 123specify:</p> 124 125<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android"; 126 package="com.android.app.myapp" > 127 <uses-permission android:name="android.permission.RECEIVE_SMS" /> 128 ... 129</manifest></pre> 130 131<p>At application install time, permissions requested by the application are 132granted to it by the package installer, based on checks against the 133signatures of the applications declaring those permissions and/or interaction 134with the user. <em>No</em> checks with the user 135are done while an application is running: it either was granted a particular 136permission when installed, and can use that feature as desired, or the 137permission was not granted and any attempt to use the feature will fail 138without prompting the user.</p> 139 140<p>Often times a permission failure will result in a {@link 141java.lang.SecurityException} being thrown back to the application. However, 142this is not guaranteed to occur everywhere. For example, the {@link 143android.content.Context#sendBroadcast} method checks permissions as data is 144being delivered to each receiver, after the method call has returned, so you 145will not receive an exception if there are permission failures. In almost all 146cases, however, a permission failure will be printed to the system log.</p> 147 148<p>The permissions provided by the Android system can be found at {@link 149android.Manifest.permission}. Any application may also define and enforce its 150own permissions, so this is not a comprehensive list of all possible 151permissions.</p> 152 153<p>A particular permission may be enforced at a number of places during your 154program's operation:</p> 155 156<ul> 157<li>At the time of a call into the system, to prevent an application from 158executing certain functions.</li> 159<li>When starting an activity, to prevent applications from launching 160activities of other applications.</li> 161<li>Both sending and receiving broadcasts, to control who can receive 162your broadcast or who can send a broadcast to you.</li> 163<li>When accessing and operating on a content provider.</li> 164<li>Binding to or starting a service.</li> 165</ul> 166 167 168<a name="declaring"></a> 169<h2>Declaring and Enforcing Permissions</h2> 170 171<p>To enforce your own permissions, you must first declare them in your 172<code>AndroidManifest.xml</code> using one or more 173<code>{@link android.R.styleable#AndroidManifestPermission <permission>}</code> 174tags.</p> 175 176<p>For example, an application that wants to control who can start one 177of its activities could declare a permission for this operation as follows:</p> 178 179<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android"; 180 package="com.me.app.myapp" > 181 <permission android:name="com.me.app.myapp.permission.DEADLY_ACTIVITY" 182 android:label="@string/permlab_deadlyActivity" 183 android:description="@string/permdesc_deadlyActivity" 184 android:permissionGroup="android.permission-group.COST_MONEY" 185 android:protectionLevel="dangerous" /> 186 ... 187</manifest></pre> 188 189<p>The {@link android.R.styleable#AndroidManifestPermission_protectionLevel 190<protectionLevel>} attribute is required, telling the system how the 191user is to be informed of applications requiring the permission, or who is 192allowed to hold that permission, as described in the linked documentation.</p> 193 194<p>The {@link android.R.styleable#AndroidManifestPermission_permissionGroup 195<permissionGroup>} attribute is optional, and only used to help the system display 196permissions to the user. You will usually want to set this to either a standard 197system group (listed in {@link android.Manifest.permission_group 198android.Manifest.permission_group}) or in more rare cases to one defined by 199yourself. It is preferred to use an existing group, as this simplifies the 200permission UI shown to the user.</p> 201 202<p>Note that both a label and description should be supplied for the 203permission. These are string resources that can be displayed to the user when 204they are viewing a list of permissions 205(<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>) 206or details on a single permission ( 207<code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>). 208The label should be short, a few words 209describing the key piece of functionality the permission is protecting. The 210description should be a couple sentences describing what the permission allows 211a holder to do. Our convention for the description is two sentences, the first 212describing the permission, the second warning the user of what bad things 213can happen if an application is granted the permission.</p> 214 215<p>Here is an example of a label and description for the CALL_PHONE 216permission:</p> 217 218<pre> 219 <string name="permlab_callPhone">directly call phone numbers</string> 220 <string name="permdesc_callPhone">Allows the application to call 221 phone numbers without your intervention. Malicious applications may 222 cause unexpected calls on your phone bill. Note that this does not 223 allow the application to call emergency numbers.</string> 224</pre> 225 226<p>You can look at the permissions currently defined in the system with the 227Settings app and the shell command <code>adb shell pm list permissions</code>. 228To use the Settings app, go to Settings > Applications. Pick an app and 229scroll down to see the permissions that the app uses. For developers, the adb '-s' 230option displays the permissions in a form similar to how the user will see them:</p> 231 232<pre> 233$ adb shell pm list permissions -s 234All Permissions: 235 236Network communication: view Wi-Fi state, create Bluetooth connections, full 237Internet access, view network state 238 239Your location: access extra location provider commands, fine (GPS) location, 240mock location sources for testing, coarse (network-based) location 241 242Services that cost you money: send SMS messages, directly call phone numbers 243 244...</pre> 245 246<a name="manifest"></a> 247<h3>Enforcing Permissions in AndroidManifest.xml</h3> 248 249<p>High-level permissions restricting access to entire components of the 250system or application can be applied through your 251<code>AndroidManifest.xml</code>. All that this requires is including an {@link 252android.R.attr#permission android:permission} attribute on the desired 253component, naming the permission that will be used to control access to 254it.</p> 255 256<p><strong>{@link android.app.Activity}</strong> permissions 257(applied to the 258{@link android.R.styleable#AndroidManifestActivity <activity>} tag) 259restrict who can start the associated 260activity. The permission is checked during 261{@link android.content.Context#startActivity Context.startActivity()} and 262{@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}; 263if the caller does not have 264the required permission then {@link java.lang.SecurityException} is thrown 265from the call.</p> 266 267<p><strong>{@link android.app.Service}</strong> permissions 268(applied to the 269{@link android.R.styleable#AndroidManifestService <service>} tag) 270restrict who can start or bind to the 271associated service. The permission is checked during 272{@link android.content.Context#startService Context.startService()}, 273{@link android.content.Context#stopService Context.stopService()} and 274{@link android.content.Context#bindService Context.bindService()}; 275if the caller does not have 276the required permission then {@link java.lang.SecurityException} is thrown 277from the call.</p> 278 279<p><strong>{@link android.content.BroadcastReceiver}</strong> permissions 280(applied to the 281{@link android.R.styleable#AndroidManifestReceiver <receiver>} tag) 282restrict who can send broadcasts to the associated receiver. 283The permission is checked <em>after</em> 284{@link android.content.Context#sendBroadcast Context.sendBroadcast()} returns, 285as the system tries 286to deliver the submitted broadcast to the given receiver. As a result, a 287permission failure will not result in an exception being thrown back to the 288caller; it will just not deliver the intent. In the same way, a permission 289can be supplied to 290{@link android.content.Context#registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter, String, android.os.Handler) 291Context.registerReceiver()} 292to control who can broadcast to a programmatically registered receiver. 293Going the other way, a permission can be supplied when calling 294{@link android.content.Context#sendBroadcast(Intent, String) Context.sendBroadcast()} 295to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see 296below).</p> 297 298<p><strong>{@link android.content.ContentProvider}</strong> permissions 299(applied to the 300{@link android.R.styleable#AndroidManifestProvider <provider>} tag) 301restrict who can access the data in 302a {@link android.content.ContentProvider}. (Content providers have an important 303additional security facility available to them called 304<a href="#uri">URI permissions</a> which is described later.) 305Unlike the other components, 306there are two separate permission attributes you can set: 307{@link android.R.attr#readPermission android:readPermission} restricts who 308can read from the provider, and 309{@link android.R.attr#writePermission android:writePermission} restricts 310who can write to it. Note that if a provider is protected with both a read 311and write permission, holding only the write permission does not mean 312you can read from a provider. The permissions are checked when you first 313retrieve a provider (if you don't have either permission, a SecurityException 314will be thrown), and as you perform operations on the provider. Using 315{@link android.content.ContentResolver#query ContentResolver.query()} requires 316holding the read permission; using 317{@link android.content.ContentResolver#insert ContentResolver.insert()}, 318{@link android.content.ContentResolver#update ContentResolver.update()}, 319{@link android.content.ContentResolver#delete ContentResolver.delete()} 320requires the write permission. 321In all of these cases, not holding the required permission results in a 322{@link java.lang.SecurityException} being thrown from the call.</p> 323 324 325<a name="broadcasts"></a> 326<h3>Enforcing Permissions when Sending Broadcasts</h3> 327 328<p>In addition to the permission enforcing who can send Intents to a 329registered {@link android.content.BroadcastReceiver} (as described above), you 330can also specify a required permission when sending a broadcast. By calling {@link 331android.content.Context#sendBroadcast(android.content.Intent,String) 332Context.sendBroadcast()} with a 333permission string, you require that a receiver's application must hold that 334permission in order to receive your broadcast.</p> 335 336<p>Note that both a receiver and a broadcaster can require a permission. When 337this happens, both permission checks must pass for the Intent to be delivered 338to the associated target.</p> 339 340 341<a name="enforcement"></a> 342<h3>Other Permission Enforcement</h3> 343 344<p>Arbitrarily fine-grained permissions can be enforced at any call into a 345service. This is accomplished with the {@link 346android.content.Context#checkCallingPermission Context.checkCallingPermission()} 347method. Call with a desired 348permission string and it will return an integer indicating whether that 349permission has been granted to the current calling process. Note that this can 350only be used when you are executing a call coming in from another process, 351usually through an IDL interface published from a service or in some other way 352given to another process.</p> 353 354<p>There are a number of other useful ways to check permissions. If you have 355the pid of another process, you can use the Context method {@link 356android.content.Context#checkPermission(String, int, int) Context.checkPermission(String, int, int)} 357to check a permission against that pid. If you have the package name of another 358application, you can use the direct PackageManager method {@link 359android.content.pm.PackageManager#checkPermission(String, String) 360PackageManager.checkPermission(String, String)} 361to find out whether that particular package has been granted a specific permission.</p> 362 363 364<a name="uri"></a> 365<h2>URI Permissions</h2> 366 367<p>The standard permission system described so far is often not sufficient 368when used with content providers. A content provider may want to 369protect itself with read and write permissions, while its direct clients 370also need to hand specific URIs to other applications for them to operate on. 371A typical example is attachments in a mail application. Access to the mail 372should be protected by permissions, since this is sensitive user data. However, 373if a URI to an image attachment is given to an image viewer, that image viewer 374will not have permission to open the attachment since it has no reason to hold 375a permission to access all e-mail.</p> 376 377<p>The solution to this problem is per-URI permissions: when starting an 378activity or returning a result to an activity, the caller can set 379{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION 380Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or 381{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION 382Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. This grants the receiving activity 383permission access the specific data URI in the Intent, regardless of whether 384it has any permission to access data in the content provider corresponding 385to the Intent.</p> 386 387<p>This mechanism allows a common capability-style model where user interaction 388(opening an attachment, selecting a contact from a list, etc) drives ad-hoc 389granting of fine-grained permission. This can be a key facility for reducing 390the permissions needed by applications to only those directly related to their 391behavior.</p> 392 393<p>The granting of fine-grained URI permissions does, however, require some 394cooperation with the content provider holding those URIs. It is strongly 395recommended that content providers implement this facility, and declare that 396they support it through the 397{@link android.R.styleable#AndroidManifestProvider_grantUriPermissions 398android:grantUriPermissions} attribute or 399{@link android.R.styleable#AndroidManifestGrantUriPermission 400<grant-uri-permissions>} tag.</p> 401 402<p>More information can be found in the 403{@link android.content.Context#grantUriPermission Context.grantUriPermission()}, 404{@link android.content.Context#revokeUriPermission Context.revokeUriPermission()}, and 405{@link android.content.Context#checkUriPermission Context.checkUriPermission()} 406methods.</p> 407 408