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