1page.title=Direct Boot 2page.keywords=preview,sdk,direct boot 3page.tags=androidn 4page.image=images/cards/card-nyc_2x.jpg 5 6@jd:body 7 8<div id="qv-wrapper"> 9<div id="qv"> 10 <h2>In this document</h2> 11 <ol> 12 <li><a href="#run">Requesting Access to Run During Direct Boot</a></li> 13 <li><a href="#access">Accessing Device Encrypted Storage</a></li> 14 <li><a href="#notification">Getting Notified of User Unlock</a></li> 15 <li><a href="#migrating">Migrating Existing Data</a></li> 16 <li><a href="#testing">Testing Your Encryption Aware App</a></li> 17 </ol> 18</div> 19</div> 20 21<p>Android N runs in a secure, <i>Direct Boot</i> mode 22when the device has been powered on but the user has not unlocked the 23device. To support this, the system provides two storage locations for data:</p> 24 25<ul> 26<li><i>Credential encrypted storage</i>, which is the default storage location 27and only available after the user has unlocked the device.</li> 28<li><i>Device encrypted storage</i>, which is a storage location available both 29during Direct Boot mode and after the user has unlocked the device.</li> 30</ul> 31 32<p>By default, apps do not run during Direct Boot mode. 33If your app needs to take action during Direct Boot mode, you can register 34app components that should be run during this mode. Some common use cases 35for apps needing to run during Direct Boot mode include:</p> 36 37<ul> 38<li>Apps that have scheduled notifications, such as alarm clock 39apps.</li> 40<li>Apps that provide important user notifications, like SMS apps.</li> 41<li>Apps that provide accessibility services, like Talkback.</li> 42</ul> 43 44<p>If your app needs to access data while running in Direct Boot mode, use 45device encrypted storage. Device encrypted storage contains data 46encrypted with a key that is only available after a device has performed a 47successful verified boot.</p> 48 49<p>For data that should be encrypted with a key associated with user 50credentials, such as a PIN or password, use credential encrypted storage. 51Credential encrypted storage is only available after the user has successfully 52unlocked the device, up until when the user restarts the device again. If the 53user enables the lock screen after unlocking the device, this doesn't lock 54credential encrypted storage.</p> 55 56<h2 id="run">Requesting Access to Run During Direct Boot</h2> 57 58<p>Apps must register their components with the system before they 59can run during Direct Boot mode or access device encrypted 60storage. Apps register with the system by marking components as 61<i>encryption aware</i>. To mark your component as encryption aware, set the 62<code>android:directBootAware</code> attribute to true in your manifest.<p> 63 64<p>Encryption aware components can register to receive a 65<code>LOCKED_BOOT_COMPLETED</code> broadcast message from the 66system when the device has been restarted. At this point device encrypted 67storage is available, and your component can execute tasks that need to be 68run during Direct Boot mode, such as triggering a scheduled alarm.</p> 69 70<p>The following code snippet is an example of how to register a 71{@link android.content.BroadcastReceiver} as encryption aware, and add an 72intent filter for <code>LOCKED_BOOT_COMPLETED</code>, in the app manifest:</p> 73 74<pre> 75<receiver 76 android:directBootAware="true" > 77 ... 78 <intent-filter> 79 <action android:name="android.intent.action.LOCKED_BOOT_COMPLETED" /> 80 </intent-filter> 81</receiver> 82</pre> 83 84<p>Once the user has unlocked the device, all components can access both the 85device encrypted storage as well as credential encrypted storage.</p> 86 87<h2 id="access">Accessing Device Encrypted Storage</h2> 88 89<p>To access device encrypted storage, create a second 90{@link android.content.Context} instance by calling 91<code>Context.createDeviceProtectedStorageContext()</code>. All storage API 92calls made using this context access the device encrypted storage. The 93following example accesses the device encrypted storage and opens an existing 94app data file:</p> 95 96<pre> 97Context directBootContext = appContext.createDeviceProtectedStorageContext(); 98// Access appDataFilename that lives in device encrypted storage 99FileInputStream inStream = directBootContext.openFileInput(appDataFilename); 100// Use inStream to read content... 101</pre> 102 103<p>Use device encrypted storage only for 104information that must be accessible during Direct Boot mode. 105Don't use device encrypted storage as a general-purpose encrypted store. 106For private user information, or encrypted data that isn't needed during 107Direct Boot mode, use credential encrypted storage.</p> 108 109<h2 id="notification">Getting Notified of User Unlock</h2> 110 111<p>When the user unlocks the device after restart, your app can switch to 112accessing credential encrypted storage and use regular system services that 113depend on user credentials.</p> 114 115<p>To get notified when the user unlocks the device after a reboot, 116register a {@link android.content.BroadcastReceiver} from a running component 117to listen for unlock notification messages. When the user unlocks the device 118after boot: 119</p> 120<ul> 121<li>If your app has foreground processes that need immediate notification, 122listen for the {@code ACTION_USER_UNLOCKED} message.</li> 123<li>If your app only uses background processes that can act on a delayed 124notification, listen for the 125{@link android.content.Intent#ACTION_BOOT_COMPLETED ACTION_BOOT_COMPLETED} 126message.</li> 127</ul> 128 129<p>If the user has unlocked the device, you can find out by calling 130<code>UserManager.isUserUnlocked()</code>.</p> 131 132<h2 id="migrating">Migrating Existing Data</h2> 133 134<p>If a user updates their device to use Direct Boot mode, you might have 135existing data that needs to get migrated to device encrypted storage. Use 136<code>Context.moveSharedPreferencesFrom()</code> and 137<code>Context.moveDatabaseFrom()</code> to migrate preference and database 138data between credential encrypted storage and device encrypted storage.</p> 139 140<p>Use your best judgment when deciding what data to migrate from credential 141encrypted storage to device encrypted storage. You should not migrate 142private user information, such as passwords or authorization tokens, to 143device encrypted storage. In some scenarios, you might need to manage 144separate sets of data in the two encrypted stores.</p> 145 146<h2 id="testing">Testing Your Encryption Aware App</h2> 147 148<p>Test your encryption aware app using the new Direct Boot mode. There are 149two ways to enable Direct Boot.</p> 150 151<p class="caution"><strong>Caution:</strong> Enabling Direct Boot 152wipes all user data on the device.</p> 153 154<p>On supported devices with Android N installed, enable 155Direct Boot by doing one of the following:</p> 156 157<ul> 158<li>On the device, enable <b>Developer options</b> if you haven't already by 159going to <b>Settings > About phone</b>, and tapping <b>Build number</b> 160seven times. Once the developer options screen is available, go to 161<b>Settings > Developer options</b> and select 162<b>Convert to file encryption</b>.</li> 163<li>Use the following adb shell commands to enable Direct Boot mode: 164<pre class="no-pretty-print"> 165$ adb reboot-bootloader 166$ fastboot --wipe-and-use-fbe 167</pre> 168</li> 169</ul> 170 171<p>An emulated Direct Boot mode is also available, in case you need to switch 172modes on your test devices. Emulated mode should only be used during 173development and may cause data loss. To enable emulated Direct Boot mode, 174set a lock pattern on the device, choose "No thanks" if prompted for a 175secure start-up screen when setting a lock pattern, and then use the 176following adb shell command:</p> 177 178<pre class="no-pretty-print"> 179$ adb shell sm set-emulate-fbe true 180</pre> 181 182<p>To turn off emulated Direct Boot mode, use the following command:</p> 183 184<pre class="no-pretty-print"> 185$ adb shell sm set-emulate-fbe false 186</pre> 187 188<p>Using these commands causes the device to reboot.</p> 189
