Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 1 | page.title=Device Administration |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 2 | page.tags=devicepolicymanager,policy,security |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 3 | @jd:body |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 4 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 5 | <div id="qv-wrapper"> |
| 6 | <div id="qv"> |
| 7 | <h2>In this document</h2> |
| 8 | <ol> |
| 9 | <li><a href="#overview">Device Administration API Overview</a> |
| 10 | <ol> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 11 | <li><a href="#how">How does it work?</a></li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 12 | <li><a href="#policies">Policies</a></li> |
| 13 | </ol> |
| 14 | </li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 15 | <li><a href="#sample">Sample Application</a></li> |
| 16 | <li><a href="#developing">Developing a Device Administration Application</a> |
| 17 | <ol> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 18 | <li><a href="#manifest">Creating the manifest</a></li> |
| 19 | <li><a href="#code">Implementing the code</a></li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 20 | </ol> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 21 | </li> |
| 22 | |
| 23 | </ol> |
| 24 | |
| 25 | <h2>Key classes</h2> |
| 26 | <ol> |
| 27 | <li>{@link android.app.admin.DeviceAdminReceiver}</li> |
| 28 | <li>{@link android.app.admin.DevicePolicyManager}</li> |
| 29 | <li>{@link android.app.admin.DeviceAdminInfo}</li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 30 | </ol> |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 31 | <h2>Related samples</h2> |
| 32 | <ol> |
| 33 | <li><a |
| 34 | href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> |
| 35 | DeviceAdminSample</a></li> |
| 36 | </ol> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 37 | </div> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 38 | </div> |
| 39 | |
| 40 | <p>Android 2.2 introduces support for enterprise applications by offering the |
| 41 | Android Device Administration API. The Device Administration API provides device |
| 42 | administration features at the system level. These APIs allow you to create |
| 43 | security-aware applications that are useful in enterprise settings, in which IT |
| 44 | professionals require rich control over employee devices. For example, the |
| 45 | built-in Android Email application has leveraged the new APIs to improve |
| 46 | Exchange support. Through the Email application, Exchange administrators can |
| 47 | enforce password policies — including alphanumeric passwords or numeric |
| 48 | PINs — across devices. Administrators can also remotely wipe (that is, |
| 49 | restore factory defaults on) lost or stolen handsets. Exchange users can sync |
| 50 | their email and calendar data.</p> |
| 51 | |
| 52 | <p>This document is intended for developers who want to develop enterprise |
| 53 | solutions for Android-powered devices. It discusses the various features |
| 54 | provided by the Device Administration API to provide stronger security for |
| 55 | employee devices that are powered by Android.</p> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 56 | |
| 57 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 58 | <h2 id="overview">Device Administration API Overview</h2> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 59 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 60 | <p>Here are examples of the types of applications that might use the Device Administration API:</p> |
| 61 | <ul> |
| 62 | <li>Email clients.</li> |
| 63 | <li>Security applications that do remote wipe.</li> |
| 64 | <li>Device management services and applications.</li> |
| 65 | </ul> |
| 66 | |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 67 | <h3 id="how">How does it work?</h3> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 68 | <p>You use the Device Administration API to write device admin applications that users |
| 69 | install on their devices. The device admin application enforces the desired |
| 70 | policies. Here's how it works:</p> <ul> |
| 71 | <li>A system administrator writes a device admin application that enforces |
| 72 | remote/local device security policies. These policies could be hard-coded into |
| 73 | the app, or the application could dynamically fetch policies from a third-party |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 74 | server. </li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 75 | <li>The application is installed on users' devices. Android does |
| 76 | not currently have an automated provisioning solution. Some of the ways a sysadmin might |
| 77 | distribute the application to users are as follows: |
| 78 | <ul> |
Dirk Dougherty | 4d7bc655 | 2012-01-27 17:56:49 -0800 | [diff] [blame] | 79 | <li>Google Play.</li> |
| 80 | <li>Enabling installation from another store.</li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 81 | <li>Distributing the application through other means, such as email or websites.</li> |
| 82 | |
| 83 | </ul> |
| 84 | |
| 85 | |
| 86 | </li> |
| 87 | <li>The system prompts the user to enable the device admin application. How |
| 88 | and when this happens depends on how the application is implemented.</li> |
| 89 | <li>Once users enable the device admin application, they are subject to |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 90 | its policies. Complying with those policies typically confers benefits, such as |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 91 | access to sensitive systems and data.</li> |
| 92 | </ul> |
| 93 | <p>If users do not enable the device admin app, it remains on the device, but in an inactive state. Users will not be subject to its policies, and they will conversely not get any of the application's benefits—for example, they may not be able to sync data.</p> |
| 94 | <p>If a user fails to comply with the policies (for example, if a user sets a |
| 95 | password that violates the guidelines), it is up to the application to decide |
| 96 | how to handle this. However, typically this will result in the user not being |
| 97 | able to sync data.</p> |
| 98 | <p>If a device attempts to connect to a server that requires policies not |
| 99 | supported in the Device Administration API, the connection will not |
| 100 | be allowed. The Device Administration API does not currently allow partial |
| 101 | provisioning. In other words, if a device (for example, a legacy device) does |
| 102 | not support all of the stated policies, there is no way to allow the |
| 103 | device to connect.</p> |
| 104 | <p>If a device contains multiple enabled admin applications, the strictest policy is |
| 105 | enforced. There is no way to target a particular admin |
| 106 | application.</p> |
| 107 | <p>To uninstall an existing device admin application, users need to |
| 108 | first unregister the application as an administrator. </p> |
| 109 | |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 110 | |
| 111 | <h3 id="policies">Policies</h3> |
| 112 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 113 | <p>In an enterprise setting, it's often the case that employee devices must |
| 114 | adhere to a strict set of policies that govern the use of the device. The |
| 115 | Device Administration API supports the policies listed in Table 1. |
| 116 | Note that the Device Administration API currently only supports passwords for screen |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 117 | lock:</p> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 118 | <p class="table-caption"><strong>Table 1.</strong> Policies supported by the Device Administration API.</p> |
| 119 | <table border="1"> |
| 120 | <tr> |
| 121 | <th>Policy</th> |
| 122 | <th>Description</th> |
| 123 | </tr> |
| 124 | <tr> |
| 125 | <td>Password enabled</td> |
| 126 | <td>Requires that devices ask for PIN or passwords.</td> |
| 127 | </tr> |
| 128 | <tr> |
| 129 | <td>Minimum password length</td> |
| 130 | <td>Set the required number of characters for the password. For example, you |
| 131 | can require PIN or passwords to have at least six characters. </td> </tr> |
| 132 | <tr> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 133 | <td>Alphanumeric password required</td> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 134 | <td>Requires that passwords have a |
| 135 | combination of letters and numbers. They may include symbolic characters. |
| 136 | </td> |
| 137 | </tr> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 138 | |
| 139 | <tr> |
| 140 | <td>Complex password required</td> |
| 141 | <td>Requires that passwords must contain at least a letter, a numerical digit, and a special symbol. Introduced in Android 3.0. |
| 142 | </td> |
| 143 | </tr> |
| 144 | |
| 145 | <tr> |
| 146 | <td>Minimum letters required in password</td> <td>The minimum number of |
| 147 | letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> |
| 148 | </tr> |
| 149 | |
| 150 | |
| 151 | <tr> |
| 152 | <td>Minimum lowercase letters required in password</td> |
| 153 | <td>The minimum number of lowercase |
| 154 | letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> |
| 155 | </tr> |
| 156 | |
| 157 | <tr> |
| 158 | <td>Minimum non-letter characters required in password</td> |
| 159 | <td>The minimum number of |
| 160 | non-letter characters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> |
| 161 | </tr> |
| 162 | |
| 163 | <tr> |
| 164 | <td>Minimum numerical digits required in password</td> |
| 165 | <td>The minimum number of numerical digits required in the password for all admins or a particular one. Introduced in Android 3.0.</td> |
| 166 | </tr> |
| 167 | |
| 168 | <tr> |
| 169 | <td>Minimum symbols required in password</td> |
| 170 | <td>The minimum number of symbols required in the password for all admins or a particular one. Introduced in Android 3.0.</td> |
| 171 | </tr> |
| 172 | |
| 173 | <tr> |
| 174 | <td>Minimum uppercase letters required in password</td> |
| 175 | <td>The minimum number of uppercase letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> |
| 176 | </tr> |
| 177 | |
| 178 | <tr> |
| 179 | <td>Password expiration timeout</td> |
| 180 | <td>When the password will expire, expressed as a delta in milliseconds from when a device admin sets the expiration timeout. Introduced in Android 3.0.</td> |
| 181 | </tr> |
| 182 | |
| 183 | <tr> |
| 184 | <td>Password history restriction</td> |
| 185 | <td>This policy prevents users from reusing the last <em>n</em> unique passwords. |
| 186 | This policy is typically used in conjunction with |
| 187 | {@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()}, which forces |
| 188 | users to update their passwords after a specified amount of time has elapsed. |
| 189 | Introduced in Android 3.0.</td> |
| 190 | </tr> |
| 191 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 192 | <tr> |
| 193 | <td>Maximum failed password attempts </td> |
| 194 | <td>Specifies how many times a user can enter the wrong password before the |
| 195 | device wipes its data. The Device Administration API also allows administrators to |
| 196 | remotely reset the device to factory defaults. This secures data in case the |
| 197 | device is lost or stolen.</td> |
| 198 | </tr> |
| 199 | <tr> |
| 200 | <td>Maximum inactivity time lock</td> |
| 201 | <td>Sets the length of time since the user last touched the screen or |
| 202 | pressed a button before the device locks the screen. When this happens, users |
| 203 | need to enter their PIN or passwords again before they can use their devices and |
| 204 | access data. The value can be between 1 and 60 minutes.</td> </tr> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 205 | |
| 206 | <tr> |
| 207 | <td>Require storage encryption</td> |
| 208 | <td>Specifies that the storage area should be encrypted, if the device supports it. |
| 209 | Introduced in Android 3.0.</td> </tr> |
| 210 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 211 | <tr> |
| 212 | <td>Disable camera</td> |
| 213 | |
| 214 | <td>Specifies that the camera should be disabled. Note that this doesn't have |
| 215 | to be a permanent disabling. The camera can be enabled/disabled dynamically |
| 216 | based on context, time, and so on. Introduced in Android 4.0.</td> |
| 217 | |
| 218 | </tr> |
| 219 | |
| 220 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 221 | </table> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 222 | |
| 223 | <h4>Other features</h4> |
| 224 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 225 | <p>In addition to supporting the policies listed in the above table, the Device |
| 226 | Administration API lets you do the following:</p> <ul> |
| 227 | <li>Prompt user to set a new password.</li> |
| 228 | <li>Lock device immediately.</li> |
| 229 | <li>Wipe the device's data (that is, restore the device to its factory defaults).</li> |
| 230 | </ul> |
| 231 | |
| 232 | |
| 233 | <h2 id="sample">Sample Application</h2> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 234 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 235 | <p>The examples used in this document are based on the <a |
Scott Main | 93d204e | 2010-12-06 15:19:37 -0800 | [diff] [blame] | 236 | href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> |
| 237 | Device Administration API |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 238 | sample</a>, which is included in the SDK samples. For information on downloading and |
| 239 | installing the SDK samples, see <a |
| 240 | href="{@docRoot}resources/samples/get.html"> |
| 241 | Getting the Samples</a>. Here is the <a |
Scott Main | 93d204e | 2010-12-06 15:19:37 -0800 | [diff] [blame] | 242 | href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> |
| 243 | complete code</a> for |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 244 | the sample. </p> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 245 | <p>The |
| 246 | sample application offers a demo of device admin features. It presents users |
| 247 | with a user interface that lets them enable the device admin application. Once |
| 248 | they've enabled the application, they can use the buttons in the user interface |
| 249 | to do the following:</p> |
| 250 | <ul> |
| 251 | <li>Set password quality.</li> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 252 | <li>Specify requirements for the user's password, such as minimum length, the minimum number of |
| 253 | numeric characters it must contain, and so on.</li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 254 | <li>Set the password. If the password does not conform to the specified |
| 255 | policies, the system returns an error.</li> |
| 256 | <li>Set how many failed password attempts can occur before the device is wiped |
| 257 | (that is, restored to factory settings).</li> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 258 | <li>Set how long from now the password will expire.</li> |
| 259 | <li>Set the password history length (<em>length</em> refers to number of old passwords stored in the history). |
| 260 | This prevents users from reusing |
| 261 | one of the last <em>n</em> passwords they previously used.</li> |
| 262 | <li>Specify that the storage area should be encrypted, if the device supports it.</li> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 263 | <li>Set the maximum amount of inactive time that can elapse before the device |
| 264 | locks.</li> |
| 265 | <li>Make the device lock immediately.</li> |
| 266 | <li>Wipe the device's data (that is, restore factory settings).</li> |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 267 | <li>Disable the camera.</li> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 268 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 269 | </ul> |
| 270 | |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 271 | |
| 272 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 273 | <img src="{@docRoot}images/admin/device-admin-app.png"/> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 274 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 275 | <p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Sample Application</p> |
| 276 | |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 277 | |
| 278 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 279 | <h2 id="developing">Developing a Device Administration Application</h2> |
| 280 | |
| 281 | <p>System administrators can use the Device Administration API to write an application |
| 282 | that enforces remote/local device security policy enforcement. This section |
| 283 | summarizes the steps involved in creating a device administration |
| 284 | application.</p> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 285 | |
| 286 | <h3 id="manifest">Creating the manifest</h3> |
| 287 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 288 | <p>To use the Device Administration API, the application's |
| 289 | manifest must include the following:</p> |
| 290 | <ul> |
| 291 | <li>A subclass of {@link android.app.admin.DeviceAdminReceiver} that includes the following: |
| 292 | <ul> |
| 293 | <li>The {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission.</li> |
| 294 | <li>The ability to respond to the {@link android.app.admin.DeviceAdminReceiver#ACTION_DEVICE_ADMIN_ENABLED} |
| 295 | intent, expressed in the manifest as an intent filter.</li> |
| 296 | </ul> |
| 297 | </li> |
| 298 | <li>A declaration of security policies used in metadata.</li> |
| 299 | </ul> |
| 300 | <p>Here is an excerpt from the Device Administration sample manifest:</p> |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 301 | <pre><activity android:name=".app.DeviceAdminSample" |
| 302 | android:label="@string/activity_sample_device_admin"> |
| 303 | <intent-filter> |
| 304 | <action android:name="android.intent.action.MAIN" /> |
| 305 | <category android:name="android.intent.category.SAMPLE_CODE" /> |
| 306 | </intent-filter> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 307 | </activity> |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 308 | <receiver android:name=".app.DeviceAdminSample$DeviceAdminSampleReceiver" |
| 309 | android:label="@string/sample_device_admin" |
| 310 | android:description="@string/sample_device_admin_description" |
| 311 | android:permission="android.permission.BIND_DEVICE_ADMIN"> |
| 312 | <meta-data android:name="android.app.device_admin" |
| 313 | android:resource="@xml/device_admin_sample" /> |
| 314 | <intent-filter> |
| 315 | <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" /> |
| 316 | </intent-filter> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 317 | </receiver></pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 318 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 319 | <p>Note that:</p> |
| 320 | <ul> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 321 | <li>The following attributes refer to string resources that for the sample application reside in |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 322 | <code>ApiDemos/res/values/strings.xml</code>. For more information about resources, see |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 323 | <a |
| 324 | href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>. |
| 325 | <ul> |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 326 | <li><code>android:label="@string/activity_sample_device_admin"</code> refers to the |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 327 | user-readable label for the activity.</li> |
| 328 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 329 | <li><code>android:label="@string/sample_device_admin"</code> refers to the |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 330 | user-readable label for the permission.</li> |
| 331 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 332 | <li><code>android:description="@string/sample_device_admin_description"</code> refers to |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 333 | the user-readable description of the permission. A descripton is typically longer and more |
| 334 | informative than |
| 335 | a label.</li> |
| 336 | </ul> |
| 337 | |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 338 | |
| 339 | <li><code>android:permission="android.permission.BIND_DEVICE_ADMIN" |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 340 | </code> is a permission that a {@link android.app.admin.DeviceAdminReceiver} subclass must |
| 341 | have, to ensure that only the system can interact with the receiver (no application can be granted this permission). This |
| 342 | prevents other applications from abusing your device admin app.</li> |
kmccormick | 76dfc02 | 2013-04-03 12:41:12 -0700 | [diff] [blame] | 343 | <li><code>android.app.action.DEVICE_ADMIN_ENABLED</code> is the primary |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 344 | action that a {@link android.app.admin.DeviceAdminReceiver} subclass must handle to be |
| 345 | allowed to manage a device. This is set to the receiver when the user enables |
| 346 | the device admin app. Your code typically handles this in |
| 347 | {@link android.app.admin.DeviceAdminReceiver#onEnabled onEnabled()}. To be supported, the receiver must also |
| 348 | require the {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission so that other applications |
| 349 | cannot abuse it. </li> |
| 350 | <li>When a user enables the device admin application, that gives the receiver |
| 351 | permission to perform actions in response to the broadcast of particular system |
| 352 | events. When suitable event arises, the application can impose a policy. For |
| 353 | example, if the user attempts to set a new password that doesn't meet the policy |
| 354 | requirements, the application can prompt the user to pick a different password |
| 355 | that does meet the requirements.</li> |
| 356 | |
| 357 | <li><code>android:resource="@xml/device_admin_sample"</code> |
| 358 | declares the security policies used in metadata. The metadata provides additional |
| 359 | information specific to the device administrator, as parsed by the {@link |
| 360 | android.app.admin.DeviceAdminInfo} class. Here are the contents of |
| 361 | <code>device_admin_sample.xml</code>:</li> |
| 362 | </ul> |
| 363 | <pre><device-admin xmlns:android="http://schemas.android.com/apk/res/android"> |
| 364 | <uses-policies> |
| 365 | <limit-password /> |
| 366 | <watch-login /> |
| 367 | <reset-password /> |
| 368 | <force-lock /> |
| 369 | <wipe-data /> |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 370 | <expire-password /> |
| 371 | <encrypted-storage /> |
| 372 | <disable-camera /> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 373 | </uses-policies> |
| 374 | </device-admin> |
| 375 | </pre> |
| 376 | <p> In designing your device administration application, you don't need to |
| 377 | include all of the policies, just the ones that are relevant for your app. |
| 378 | </p> |
| 379 | For more discussion of the manifest file, see the <a |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 380 | href="{@docRoot}guide/topics/manifest/manifest-intro.html">Android Developers Guide</a>. |
| 381 | |
| 382 | |
| 383 | |
| 384 | <h3 id="code">Implementing the code</h3> |
| 385 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 386 | <p>The Device Administration API includes the following classes:</p> |
| 387 | <dl> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 388 | <dt>{@link android.app.admin.DeviceAdminReceiver}</dt> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 389 | <dd>Base class for implementing a device administration component. This class provides |
| 390 | a convenience for interpreting the raw intent actions that are sent by the |
| 391 | system. Your Device Administration application must include a |
| 392 | {@link android.app.admin.DeviceAdminReceiver} subclass.</dd> |
| 393 | <dt>{@link android.app.admin.DevicePolicyManager}</dt> |
| 394 | <dd>A class for managing policies enforced on a device. Most clients of |
| 395 | this class must have published a {@link android.app.admin.DeviceAdminReceiver} that the user |
| 396 | has currently enabled. The {@link android.app.admin.DevicePolicyManager} manages policies for |
| 397 | one or more {@link android.app.admin.DeviceAdminReceiver} instances</dd> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 398 | <dt>{@link android.app.admin.DeviceAdminInfo}</dt> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 399 | <dd>This class is used to specify metadata |
| 400 | for a device administrator component.</dd> |
| 401 | </dl> |
| 402 | <p>These classes provide the foundation for a fully functional device administration application. |
| 403 | The rest of this section describes how you use the {@link |
| 404 | android.app.admin.DeviceAdminReceiver} and |
| 405 | {@link android.app.admin.DevicePolicyManager} APIs to write a device admin application.</p> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 406 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 407 | <h4 id="receiver">Subclassing DeviceAdminReceiver</h4> |
| 408 | <p>To create a device admin application, you must subclass |
| 409 | {@link android.app.admin.DeviceAdminReceiver}. The {@link android.app.admin.DeviceAdminReceiver} class |
| 410 | consists of a series of callbacks that are triggered when particular events |
| 411 | occur.</p> |
| 412 | <p>In its {@link android.app.admin.DeviceAdminReceiver} subclass, the sample application |
| 413 | simply displays a {@link android.widget.Toast} notification in response to particular |
| 414 | events. For example:</p> |
| 415 | <pre>public class DeviceAdminSample extends DeviceAdminReceiver { |
| 416 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 417 | void showToast(Context context, String msg) { |
| 418 | String status = context.getString(R.string.admin_receiver_status, msg); |
| 419 | Toast.makeText(context, status, Toast.LENGTH_SHORT).show(); |
| 420 | } |
| 421 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 422 | @Override |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 423 | public void onEnabled(Context context, Intent intent) { |
| 424 | showToast(context, context.getString(R.string.admin_receiver_status_enabled)); |
| 425 | } |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 426 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 427 | @Override |
| 428 | public CharSequence onDisableRequested(Context context, Intent intent) { |
| 429 | return context.getString(R.string.admin_receiver_status_disable_warning); |
| 430 | } |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 431 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 432 | @Override |
| 433 | public void onDisabled(Context context, Intent intent) { |
| 434 | showToast(context, context.getString(R.string.admin_receiver_status_disabled)); |
| 435 | } |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 436 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 437 | @Override |
| 438 | public void onPasswordChanged(Context context, Intent intent) { |
| 439 | showToast(context, context.getString(R.string.admin_receiver_status_pw_changed)); |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 440 | } |
| 441 | ... |
| 442 | }</pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 443 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 444 | |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 445 | <h4 id="enabling">Enabling the application</h4> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 446 | <p>One of the major events a device admin application has to handle is the user |
| 447 | enabling the application. The user must explicitly enable the application for |
| 448 | the policies to be enforced. If the user chooses not to enable the application |
| 449 | it will still be present on the device, but its policies will not be enforced, and the user will not |
| 450 | get any of the application's benefits.</p> |
| 451 | <p>The process of enabling the application begins when the user performs an |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 452 | action that triggers the {@link android.app.admin.DevicePolicyManager#ACTION_ADD_DEVICE_ADMIN} |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 453 | intent. In the |
| 454 | sample application, this happens when the user clicks the <strong>Enable |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 455 | Admin</strong> checkbox. </p> |
| 456 | <p>When the user clicks the <strong>Enable Admin</strong> checkbox, the display |
| 457 | changes to prompt the user to activate the device admin application, as shown in figure |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 458 | 2.</p> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 459 | |
| 460 | <img src="{@docRoot}images/admin/device-admin-activate-prompt.png"/> |
| 461 | <p class="img-caption"><strong>Figure 2.</strong> Sample Application: Activating the Application</p> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 462 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 463 | <p>Below is the code that gets executed when the user clicks the <strong>Enable Admin</strong> checkbox. This has the effect of triggering the |
| 464 | {@link android.preference.Preference.OnPreferenceChangeListener#onPreferenceChange(android.preference.Preference, java.lang.Object) onPreferenceChange()} |
| 465 | callback. This callback is invoked when the value of this {@link android.preference.Preference} has been changed by the user and is about to be set and/or persisted. If the user is enabling the application, the display |
| 466 | changes to prompt the user to activate the device admin application, as shown in figure |
| 467 | 2. Otherwise, the device admin application is disabled. </p> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 468 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 469 | <pre>@Override |
| 470 | public boolean onPreferenceChange(Preference preference, Object newValue) { |
| 471 | if (super.onPreferenceChange(preference, newValue)) { |
| 472 | return true; |
| 473 | } |
| 474 | boolean value = (Boolean) newValue; |
| 475 | if (preference == mEnableCheckbox) { |
| 476 | if (value != mAdminActive) { |
| 477 | if (value) { |
| 478 | // Launch the activity to have the user enable our admin. |
| 479 | Intent intent = new Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN); |
| 480 | intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, mDeviceAdminSample); |
| 481 | intent.putExtra(DevicePolicyManager.EXTRA_ADD_EXPLANATION, |
| 482 | mActivity.getString(R.string.add_admin_extra_app_text)); |
| 483 | startActivityForResult(intent, REQUEST_CODE_ENABLE_ADMIN); |
| 484 | // return false - don't update checkbox until we're really active |
| 485 | return false; |
| 486 | } else { |
| 487 | mDPM.removeActiveAdmin(mDeviceAdminSample); |
| 488 | enableDeviceCapabilitiesArea(false); |
| 489 | mAdminActive = false; |
| 490 | } |
| 491 | } |
| 492 | } else if (preference == mDisableCameraCheckbox) { |
| 493 | mDPM.setCameraDisabled(mDeviceAdminSample, value); |
| 494 | ... |
| 495 | } |
| 496 | return true; |
| 497 | }</pre> |
| 498 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 499 | |
| 500 | <p>The line |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 501 | <code>intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 502 | mDeviceAdminSample)</code> states that <code>mDeviceAdminSample</code> (which is |
| 503 | a {@link android.app.admin.DeviceAdminReceiver} component) is the target policy. |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 504 | This line invokes the user interface shown in figure 2, which guides users through |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 505 | adding the device administrator to the system (or allows them to reject it).</p> |
| 506 | |
| 507 | <p>When the application needs to perform an operation that is contingent on the |
| 508 | device admin application being enabled, it confirms that the application is |
| 509 | active. To do this it uses the {@link android.app.admin.DevicePolicyManager} method |
| 510 | {@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()}. Notice that the {@link android.app.admin.DevicePolicyManager} |
| 511 | method {@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()} takes a {@link android.app.admin.DeviceAdminReceiver} |
| 512 | component as its argument:</p> |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 513 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 514 | <pre> |
| 515 | DevicePolicyManager mDPM; |
| 516 | ... |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 517 | private boolean isActiveAdmin() { |
| 518 | return mDPM.isAdminActive(mDeviceAdminSample); |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 519 | } |
| 520 | </pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 521 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 522 | |
| 523 | |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 524 | <h3 id="admin_ops">Managing policies</h3> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 525 | <p>{@link android.app.admin.DevicePolicyManager} is a public class for managing policies |
| 526 | enforced on a device. {@link android.app.admin.DevicePolicyManager} manages policies for one |
| 527 | or more {@link android.app.admin.DeviceAdminReceiver} instances. </p> |
| 528 | <p>You get a handle to the {@link android.app.admin.DevicePolicyManager} as follows: </p> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 529 | <pre> |
| 530 | DevicePolicyManager mDPM = |
| 531 | (DevicePolicyManager)getSystemService(Context.DEVICE_POLICY_SERVICE); |
| 532 | </pre> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 533 | <p>This section describes how to use {@link android.app.admin.DevicePolicyManager} to perform |
| 534 | administrative tasks:</p> |
| 535 | <ul> |
| 536 | <li><a href="#pwd">Set password policies</a></li> |
| 537 | <li><a href="#lock">Set device lock</a></li> |
| 538 | <li><a href="#wipe">Perform data wipe</a></li> |
| 539 | </ul> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 540 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 541 | <h4 id="pwd">Set password policies</h4> |
| 542 | <p>{@link android.app.admin.DevicePolicyManager} includes APIs for setting and enforcing the |
| 543 | device password policy. In the Device Administration API, the password only applies to |
| 544 | screen lock. This section describes common password-related tasks.</p> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 545 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 546 | <h5>Set a password for the device</h5> |
| 547 | <p>This code displays a user interface prompting the user to set a password:</p> |
| 548 | <pre>Intent intent = new Intent(DevicePolicyManager.ACTION_SET_NEW_PASSWORD); |
| 549 | startActivity(intent); |
| 550 | </pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 551 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 552 | <h5>Set the password quality</h5> |
| 553 | <p>The password quality can be one of the following {@link android.app.admin.DevicePolicyManager} constants: </p> |
| 554 | <dl> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 555 | <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_ALPHABETIC}</dt><dd>The user must enter a |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 556 | password containing at least alphabetic (or other symbol) characters.</dd> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 557 | <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_ALPHANUMERIC}</dt><dd>The user must enter a |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 558 | password containing at least <em>both</em> numeric <em>and</em> alphabetic (or |
| 559 | other symbol) characters.</dd> |
| 560 | <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_NUMERIC}</dt><dd>The user must enter a password |
| 561 | containing at least numeric characters.</dd> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 562 | <dt>{@link |
| 563 | android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_COMPLEX}</dt><dd>The user |
| 564 | must have entered a password containing at least a letter, a numerical digit and |
| 565 | a special symbol.</dd> |
| 566 | <dt>{@link |
| 567 | android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_SOMETHING}</dt><dd>The |
| 568 | policy requires some kind |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 569 | of password, but doesn't care what it is.</dd> |
| 570 | <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_UNSPECIFIED}</dt><dd> |
| 571 | The policy has no requirements for the password. </dd> |
| 572 | </dl> |
| 573 | <p>For example, this is how you would set the password policy to require an alphanumeric password:</p> |
| 574 | <pre> |
| 575 | DevicePolicyManager mDPM; |
| 576 | ComponentName mDeviceAdminSample; |
| 577 | ... |
| 578 | mDPM.setPasswordQuality(mDeviceAdminSample, DevicePolicyManager.PASSWORD_QUALITY_ALPHANUMERIC); |
| 579 | </pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 580 | |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 581 | <h5>Set password content requirements</h5> |
| 582 | |
| 583 | <p>Beginning with Android 3.0, the {@link android.app.admin.DevicePolicyManager} class |
| 584 | includes methods that let you fine-tune the contents of the password. For |
| 585 | example, you could set a policy that states that passwords must contain at least |
| 586 | <em>n</em> uppercase letters. Here are the methods for fine-tuning a password's |
| 587 | contents:</p> |
| 588 | <ul> |
| 589 | |
| 590 | <li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumLetters(android.content.ComponentName,int) setPasswordMinimumLetters()}</li> |
| 591 | |
| 592 | <li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumLowerCase(android.content.ComponentName,int) setPasswordMinimumLowerCase()}</li> |
| 593 | |
| 594 | <li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumUpperCase(android.content.ComponentName,int) setPasswordMinimumUpperCase()}</li> |
| 595 | |
| 596 | <li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumNonLetter(android.content.ComponentName,int) setPasswordMinimumNonLetter()}</li> |
| 597 | |
| 598 | <li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumNumeric(android.content.ComponentName,int) setPasswordMinimumNumeric()}</li> |
| 599 | |
| 600 | <li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumSymbols(android.content.ComponentName,int) setPasswordMinimumSymbols()}</li> |
| 601 | </ul> |
| 602 | <p>For example, this snippet states that the password must have at least 2 uppercase letters:</p> |
| 603 | <pre> |
| 604 | DevicePolicyManager mDPM; |
| 605 | ComponentName mDeviceAdminSample; |
| 606 | int pwMinUppercase = 2; |
| 607 | ... |
| 608 | mDPM.setPasswordMinimumUpperCase(mDeviceAdminSample, pwMinUppercase);</pre> |
| 609 | |
| 610 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 611 | <h5>Set the minimum password length</h5> |
| 612 | <p>You can specify that a password must be at least the specified minimum |
| 613 | length. For example:</p> |
| 614 | <pre>DevicePolicyManager mDPM; |
| 615 | ComponentName mDeviceAdminSample; |
| 616 | int pwLength; |
| 617 | ... |
| 618 | mDPM.setPasswordMinimumLength(mDeviceAdminSample, pwLength); |
| 619 | </pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 620 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 621 | <h5>Set maximum failed password attempts</h5> |
| 622 | <p>You can set the maximum number of allowed failed password attempts before the |
| 623 | device is wiped (that is, reset to factory settings). For example:</p> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 624 | <pre>DevicePolicyManager mDPM; |
| 625 | ComponentName mDeviceAdminSample; |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 626 | int maxFailedPw; |
| 627 | ... |
| 628 | mDPM.setMaximumFailedPasswordsForWipe(mDeviceAdminSample, maxFailedPw);</pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 629 | |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 630 | <h5 id="expiration">Set password expiration timeout</h5> |
| 631 | <p>Beginning with Android 3.0, you can use the |
| 632 | {@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()} |
| 633 | method to set when a password will expire, expressed as a delta in milliseconds from when a device admin sets the expiration timeout. For example:</p> |
| 634 | |
| 635 | <pre>DevicePolicyManager mDPM; |
| 636 | ComponentName mDeviceAdminSample; |
| 637 | long pwExpiration; |
| 638 | ... |
| 639 | mDPM.setPasswordExpirationTimeout(mDeviceAdminSample, pwExpiration); |
| 640 | </pre> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 641 | |
| 642 | <h5 id="history">Restrict password based on history</h5> |
| 643 | |
| 644 | <p>Beginning with Android 3.0, you can use the |
| 645 | {@link android.app.admin.DevicePolicyManager#setPasswordHistoryLength(android.content.ComponentName,int) setPasswordHistoryLength()} |
| 646 | method to limit users' |
| 647 | ability to reuse old passwords. This method takes a <em>length</em> |
| 648 | parameter, which specifies how many old |
| 649 | passwords are stored. When this policy is active, users cannot enter a new |
| 650 | password that matches the last <em>n</em> passwords. This prevents |
| 651 | users from using the same password over and over. This policy is typically used |
| 652 | in conjunction with |
| 653 | {@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()}, |
| 654 | which forces users |
| 655 | to update their passwords after a specified amount of time has elapsed. </p> |
| 656 | |
| 657 | <p>For example, this snippet prohibits users from reusing any of their last 5 passwords:</p> |
| 658 | |
| 659 | <pre>DevicePolicyManager mDPM; |
| 660 | ComponentName mDeviceAdminSample; |
| 661 | int pwHistoryLength = 5; |
| 662 | ... |
| 663 | mDPM.setPasswordHistoryLength(mDeviceAdminSample, pwHistoryLength); |
| 664 | </pre> |
| 665 | |
| 666 | <h4 id="lock">Set device lock</h4> |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 667 | <p>You can set the maximum period of user inactivity that can occur before the |
| 668 | device locks. For example:</p> |
| 669 | <pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 670 | DevicePolicyManager mDPM; |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 671 | ComponentName mDeviceAdminSample; |
| 672 | ... |
| 673 | long timeMs = 1000L*Long.parseLong(mTimeout.getText().toString()); |
| 674 | mDPM.setMaximumTimeToLock(mDeviceAdminSample, timeMs); |
| 675 | </pre> |
| 676 | <p>You can also programmatically tell the device to lock immediately:</p> |
| 677 | <pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 678 | DevicePolicyManager mDPM; |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 679 | mDPM.lockNow();</pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 680 | |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 681 | |
| 682 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 683 | <h4 id="wipe">Perform data wipe</h4> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 684 | |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 685 | <p>You can use the {@link android.app.admin.DevicePolicyManager} method |
| 686 | {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} to reset the device to factory settings. This is useful |
| 687 | if the device is lost or stolen. Often the decision to wipe the device is the |
| 688 | result of certain conditions being met. For example, you can use |
| 689 | {@link android.app.admin.DevicePolicyManager#setMaximumFailedPasswordsForWipe setMaximumFailedPasswordsForWipe()} to state that a device should be |
| 690 | wiped after a specific number of failed password attempts.</p> |
| 691 | <p>You wipe data as follows:</p> |
| 692 | <pre> |
Scott Main | 50f86c6 | 2010-10-08 16:06:40 -0700 | [diff] [blame] | 693 | DevicePolicyManager mDPM; |
Katie McCormick | 262b431 | 2010-09-30 16:27:25 -0700 | [diff] [blame] | 694 | mDPM.wipeData(0);</pre> |
| 695 | <p>The {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} method takes as its parameter a bit mask of |
| 696 | additional options. Currently the value must be 0. </p> |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 697 | |
Katie McCormick | 6c5951b | 2011-10-28 14:15:41 -0700 | [diff] [blame] | 698 | <h4>Disable camera</h4> |
| 699 | <p>Beginning with Android 4.0, you can disable the camera. Note that this doesn't have to be a permanent disabling. The camera can be enabled/disabled dynamically based on context, time, and so on. </p> |
| 700 | <p>You control whether the camera is disabled by using the |
| 701 | {@link android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) setCameraDisabled()} method. For example, this snippet sets the camera to be enabled or disabled based on a checkbox setting:</p> |
| 702 | |
| 703 | <pre>private CheckBoxPreference mDisableCameraCheckbox; |
| 704 | DevicePolicyManager mDPM; |
| 705 | ComponentName mDeviceAdminSample; |
| 706 | ... |
| 707 | mDPM.setCameraDisabled(mDeviceAdminSample, mDisableCameraCheckbox.isChecked());<br /> |
| 708 | </pre> |
| 709 | |
| 710 | |
Katie McCormick | 62922c3 | 2011-04-28 17:05:17 -0700 | [diff] [blame] | 711 | <h4 id=storage">Storage encryption</h4> |
| 712 | <p>Beginning with Android 3.0, you can use the |
| 713 | {@link android.app.admin.DevicePolicyManager#setStorageEncryption(android.content.ComponentName,boolean) setStorageEncryption()} |
| 714 | method to set a policy requiring encryption of the storage area, where supported.</p> |
| 715 | |
| 716 | <p>For example:</p> |
| 717 | |
| 718 | <pre> |
| 719 | DevicePolicyManager mDPM; |
| 720 | ComponentName mDeviceAdminSample; |
| 721 | ... |
| 722 | mDPM.setStorageEncryption(mDeviceAdminSample, true); |
| 723 | </pre> |
| 724 | <p> |
| 725 | See the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/DeviceAdminSample.html"> Device Administration API sample</a> for a complete |
| 726 | example of how to enable storage encryption.</p> |