1 page.title=Security and 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 24 security features provided by Android. A more general <a 25 href="http://source.android.com/tech/security/index.html"> Android Security 26 Overview</a> is provided in the Android Open Source Project.</p> 27 28 <p>Android is a privilege-separated operating system, in which each 29 application runs with a distinct system identity (Linux user ID and group 30 ID). Parts of the system are also separated into distinct identities. 31 Linux 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 35 that a particular process can perform, and per-URI permissions for granting 36 ad-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 42 application, by default, has permission to perform any operations that would 43 adversely impact other applications, the operating system, or the user. This 44 includes reading or writing the user's private data (such as contacts or 45 e-mails), reading or writing another application's files, performing 46 network access, keeping the device awake, etc.</p> 47 48 <p>Because Android sandboxes applications from each other, applications 49 must explicitly share resources and data. They do this by declaring the 50 <em>permissions</em> they need for additional capabilities not provided by 51 the basic sandbox. Applications statically declare the permissions they 52 require, and the Android system prompts the user for consent at the time the 53 application is installed. Android has no mechanism for granting permissions 54 dynamically (at run-time) because it complicates the user experience to the 55 detriment of security.</p> 56 57 <p>The application sandbox does not depend on the technology used to build 58 an application. In particular the Dalvik VM is not a security boundary, and 59 any app can run native code (see <a href="/sdk/ndk/index.html">the Android 60 NDK</a>). All types of applications — Java, native, and hybrid — 61 are sandboxed in the same way and have the same degree of security from each 62 other.</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 68 whose private key is held by their developer. This certificate identifies 69 the author of the application. The certificate does <em>not</em> need to be 70 signed by a certificate authority: it is perfectly allowable, and typical, 71 for Android applications to use self-signed certificates. The purpose of 72 certificates in Android is to distinguish application authors. This allows 73 the system to grant or deny applications access to <a 74 href="/guide/topics/manifest/permission-element.html#plevel">signature-level 75 permissions</a> and to grant or deny an application's <a 76 href="/guide/topics/manifest/manifest-element.html#uid">request to be given 77 the 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 83 identity remains constant for the duration of the package's life on that 84 device. On a different device, the same package may have a different UID; 85 what matters is that each package has a distinct UID on a given device.</p> 86 87 <p>Because security enforcement happens at the 88 process level, the code of any two packages can not normally 89 run in the same process, since they need to run as different Linux users. 90 You 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 93 have them assigned the same user ID. By doing this, for purposes of security 94 the two packages are then treated as being the same application, with the same 95 user ID and file permissions. Note that in order to retain security, only two applications 96 signed with the same signature (and requesting the same sharedUserId) will 97 be given the same user ID.</p> 98 99 <p>Any data stored by an application will be assigned that application's user 100 ID, and not normally accessible to other packages. When creating a new file 101 with {@link android.content.Context#getSharedPreferences}, 102 {@link android.content.Context#openFileOutput}, or 103 {@link android.content.Context#openOrCreateDatabase}, 104 you 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 107 package to read/write the file. When setting these flags, the file is still 108 owned by your application, but its global read and/or write permissions have 109 been 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, 116 meaning it can not do anything that would adversely impact the user experience 117 or any data on the device. To make use of protected features of the device, 118 you must include in your <code>AndroidManifest.xml</code> one or more 119 <code>{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}</code> 120 tags declaring the permissions that your application needs.</p> 121 122 <p>For example, an application that needs to monitor incoming SMS messages would 123 specify:</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 132 granted to it by the package installer, based on checks against the 133 signatures of the applications declaring those permissions and/or interaction 134 with the user. <em>No</em> checks with the user 135 are done while an application is running: it either was granted a particular 136 permission when installed, and can use that feature as desired, or the 137 permission was not granted and any attempt to use the feature will fail 138 without prompting the user.</p> 139 140 <p>Often times a permission failure will result in a {@link 141 java.lang.SecurityException} being thrown back to the application. However, 142 this is not guaranteed to occur everywhere. For example, the {@link 143 android.content.Context#sendBroadcast} method checks permissions as data is 144 being delivered to each receiver, after the method call has returned, so you 145 will not receive an exception if there are permission failures. In almost all 146 cases, 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 149 android.Manifest.permission}. Any application may also define and enforce its 150 own permissions, so this is not a comprehensive list of all possible 151 permissions.</p> 152 153 <p>A particular permission may be enforced at a number of places during your 154 program's operation:</p> 155 156 <ul> 157 <li>At the time of a call into the system, to prevent an application from 158 executing certain functions.</li> 159 <li>When starting an activity, to prevent applications from launching 160 activities of other applications.</li> 161 <li>Both sending and receiving broadcasts, to control who can receive 162 your 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> 174 tags.</p> 175 176 <p>For example, an application that wants to control who can start one 177 of 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 191 user is to be informed of applications requiring the permission, or who is 192 allowed 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 196 permissions to the user. You will usually want to set this to either a standard 197 system group (listed in {@link android.Manifest.permission_group 198 android.Manifest.permission_group}) or in more rare cases to one defined by 199 yourself. It is preferred to use an existing group, as this simplifies the 200 permission UI shown to the user.</p> 201 202 <p>Note that both a label and description should be supplied for the 203 permission. These are string resources that can be displayed to the user when 204 they are viewing a list of permissions 205 (<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>) 206 or details on a single permission ( 207 <code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>). 208 The label should be short, a few words 209 describing the key piece of functionality the permission is protecting. The 210 description should be a couple sentences describing what the permission allows 211 a holder to do. Our convention for the description is two sentences, the first 212 describing the permission, the second warning the user of what bad things 213 can 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 216 permission:</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 227 Settings app and the shell command <code>adb shell pm list permissions</code>. 228 To use the Settings app, go to Settings > Applications. Pick an app and 229 scroll down to see the permissions that the app uses. For developers, the adb '-s' 230 option 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 234 All Permissions: 235 236 Network communication: view Wi-Fi state, create Bluetooth connections, full 237 Internet access, view network state 238 239 Your location: access extra location provider commands, fine (GPS) location, 240 mock location sources for testing, coarse (network-based) location 241 242 Services 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 250 system or application can be applied through your 251 <code>AndroidManifest.xml</code>. All that this requires is including an {@link 252 android.R.attr#permission android:permission} attribute on the desired 253 component, naming the permission that will be used to control access to 254 it.</p> 255 256 <p><strong>{@link android.app.Activity}</strong> permissions 257 (applied to the 258 {@link android.R.styleable#AndroidManifestActivity <activity>} tag) 259 restrict who can start the associated 260 activity. The permission is checked during 261 {@link android.content.Context#startActivity Context.startActivity()} and 262 {@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}; 263 if the caller does not have 264 the required permission then {@link java.lang.SecurityException} is thrown 265 from 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) 270 restrict who can start or bind to the 271 associated 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()}; 275 if the caller does not have 276 the required permission then {@link java.lang.SecurityException} is thrown 277 from 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) 282 restrict who can send broadcasts to the associated receiver. 283 The permission is checked <em>after</em> 284 {@link android.content.Context#sendBroadcast Context.sendBroadcast()} returns, 285 as the system tries 286 to deliver the submitted broadcast to the given receiver. As a result, a 287 permission failure will not result in an exception being thrown back to the 288 caller; it will just not deliver the intent. In the same way, a permission 289 can be supplied to 290 {@link android.content.Context#registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter, String, android.os.Handler) 291 Context.registerReceiver()} 292 to control who can broadcast to a programmatically registered receiver. 293 Going the other way, a permission can be supplied when calling 294 {@link android.content.Context#sendBroadcast(Intent, String) Context.sendBroadcast()} 295 to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see 296 below).</p> 297 298 <p><strong>{@link android.content.ContentProvider}</strong> permissions 299 (applied to the 300 {@link android.R.styleable#AndroidManifestProvider <provider>} tag) 301 restrict who can access the data in 302 a {@link android.content.ContentProvider}. (Content providers have an important 303 additional security facility available to them called 304 <a href="#uri">URI permissions</a> which is described later.) 305 Unlike the other components, 306 there are two separate permission attributes you can set: 307 {@link android.R.attr#readPermission android:readPermission} restricts who 308 can read from the provider, and 309 {@link android.R.attr#writePermission android:writePermission} restricts 310 who can write to it. Note that if a provider is protected with both a read 311 and write permission, holding only the write permission does not mean 312 you can read from a provider. The permissions are checked when you first 313 retrieve a provider (if you don't have either permission, a SecurityException 314 will be thrown), and as you perform operations on the provider. Using 315 {@link android.content.ContentResolver#query ContentResolver.query()} requires 316 holding 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()} 320 requires the write permission. 321 In 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 329 registered {@link android.content.BroadcastReceiver} (as described above), you 330 can also specify a required permission when sending a broadcast. By calling {@link 331 android.content.Context#sendBroadcast(android.content.Intent,String) 332 Context.sendBroadcast()} with a 333 permission string, you require that a receiver's application must hold that 334 permission in order to receive your broadcast.</p> 335 336 <p>Note that both a receiver and a broadcaster can require a permission. When 337 this happens, both permission checks must pass for the Intent to be delivered 338 to 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 345 service. This is accomplished with the {@link 346 android.content.Context#checkCallingPermission Context.checkCallingPermission()} 347 method. Call with a desired 348 permission string and it will return an integer indicating whether that 349 permission has been granted to the current calling process. Note that this can 350 only be used when you are executing a call coming in from another process, 351 usually through an IDL interface published from a service or in some other way 352 given to another process.</p> 353 354 <p>There are a number of other useful ways to check permissions. If you have 355 the pid of another process, you can use the Context method {@link 356 android.content.Context#checkPermission(String, int, int) Context.checkPermission(String, int, int)} 357 to check a permission against that pid. If you have the package name of another 358 application, you can use the direct PackageManager method {@link 359 android.content.pm.PackageManager#checkPermission(String, String) 360 PackageManager.checkPermission(String, String)} 361 to 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 368 when used with content providers. A content provider may want to 369 protect itself with read and write permissions, while its direct clients 370 also need to hand specific URIs to other applications for them to operate on. 371 A typical example is attachments in a mail application. Access to the mail 372 should be protected by permissions, since this is sensitive user data. However, 373 if a URI to an image attachment is given to an image viewer, that image viewer 374 will not have permission to open the attachment since it has no reason to hold 375 a permission to access all e-mail.</p> 376 377 <p>The solution to this problem is per-URI permissions: when starting an 378 activity or returning a result to an activity, the caller can set 379 {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION 380 Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or 381 {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION 382 Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. This grants the receiving activity 383 permission access the specific data URI in the Intent, regardless of whether 384 it has any permission to access data in the content provider corresponding 385 to 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 389 granting of fine-grained permission. This can be a key facility for reducing 390 the permissions needed by applications to only those directly related to their 391 behavior.</p> 392 393 <p>The granting of fine-grained URI permissions does, however, require some 394 cooperation with the content provider holding those URIs. It is strongly 395 recommended that content providers implement this facility, and declare that 396 they support it through the 397 {@link android.R.styleable#AndroidManifestProvider_grantUriPermissions 398 android: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()} 406 methods.</p> 407 408
