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