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