Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Adding N preview docs on Direct Boot feature

Browse Source 
Adding API overview summary and new topic on Direct Boot.
Direct Boot was formerly known as File-Based Encryption.
Adding changes based on review suggestions.

Bug: 26570782
Change-Id: Ibe253101c69e3c73122477c3af116e33fb8591a7
This commit is contained in:
Daniel Yu
2016-02-19 15:37:17 -08:00
parent 9447820dcb
commit e3d4ef0342
1 changed files with 176 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
docs/html/preview/features/direct-boot.jd Normal file
View File

@@ -0,0 +1,176 @@
page.title=Direct Boot
page.keywords=preview,sdk,direct boot
page.tags=androidn
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>In this document</h2>
<ol>
<li><a href="#run">Requesting Access to Run During Direct Boot</a></li>
<li><a href="#access">Accessing Device Encrypted Storage</a></li>
<li><a href="#notification">Getting Notified of User Unlock</a></li>
<li><a href="#migrating">Migrating Existing Data</a></li>
<li><a href="#testing">Testing Your Encryption Aware App</a></li>
</ol>
</div>
</div>
<p>The system now runs in a secure, Direct Boot mode when the device has been
powered on but the user has not unlocked the device. To support this, the
system provides two storage locations for data:</p>
<ul>
<li><i>Credential encrypted storage</i>, which is the default storage location
and available only after the user has unlocked the device.</li>
<li><i>Device encrypted storage</i>, which is a storage location available both
during Direct Boot mode and after the user has unlocked the device.</li>
</ul>
<p>By default apps will not run during Direct Boot mode, because apps won't
have access to credential encrypted storage.</p>
<p>If your app needs to take action during Direct Boot mode, you can register
app components that should be run during this mode. Some common use cases
for applications needing to run during Direct Boot mode include:</p>
<ul>
<li>Applications that have scheduled notifications, such as alarm clock
apps.</li>
<li>Applications that provide important user notifications, like SMS apps.</li>
<li>Applications providing accessibility services, like Talkback.</li>
</ul>
<p>If your app needs to access data while running in Direct Boot mode, use
device encrypted storage. Device encrypted storage contains data
encrypted with a key that is only available after a device has performed a
successful verified boot.</p>
<p>For data that should be encrypted with a key associated with user
credentials, such as a PIN or password, use credential encrypted storage.
Credential encrypted storage is only available after the user has successfully
unlocked the device, up until when the user restarts the device again. If the
user enables the lock screen after unlocking the device, this will not lock
credential encrypted storage.</p>
<h2 id="run">Requesting Access to Run During Direct Boot</h2>
<p>Applications must register their components with the system before they
can run during the limited Direct Boot mode, or access device encrypted
storage. Applications register with the system by marking components as
<i>encryption aware</i>. To mark your component as encryption aware, set the
<code>android:encryptionAware</code> attribute to true in your manifest.<p>
<p>When a component is marked as encryption aware, the component receives a
new <code>LOCKED_BOOT_COMPLETED</code> broadcast message from the
system when the device has been restarted. At this point device encrypted
storage is available, and your component can run whatever tasks need to be
done during Direct Boot mode, such as triggering a scheduled alarm.</p>
<p>The following code snippet is an example of how to register a
<code>BroadcastReceiver</code> as encryption aware, and add an intent filter
for <code>LOCKED_BOOT_COMPLETED</code>, in the application manifest:</p>
<pre>
&lt;receiever
android:encryptionAware="true" &gt;
...
&lt;intent-filter&gt;
&lt;action android:name="android.intent.action.LOCKED_BOOT_COMPLETED" /&gt;
&lt;/intent-filter&gt;
&lt;/receiver&gt;
</pre>
<p>Once the user has unlocked the device, components can access both the
device encrypted storage as well as credential encrypted storage.</p>
<h2 id="access">Accessing Device Encrypted Storage</h2>
<p>To access device encrypted storage, create a second <code>Context</code>
instance by calling <code>Context.createDeviceEncryptedStorageContext()</code>.
All storage API calls made using this context access the device encrypted
storage. The following example accesses the device encrypted storage and opens
an existing app data file:</p>
<pre>
Context directBootContext = Context.createDeviceEncryptedStorageContext();
// Access appDataFilename that lives in device encrypted storage
FileInputStream inStream = directBootContext.openFileInput(appDataFilename);
// Use inStream to read content...
</pre>
<p class="note"><strong>Note:</strong> Use device encrypted storage only for
information that must be accessible during the Direct Boot mode.
Don't use device encrypted storage as a general-purpose encrypted store.
For private user information, or encrypted data that isn't needed during
Direct Boot mode, use credential encrypted storage.</p>
<h2 id="notification">Getting Notified of User Unlock</h2>
<p>Once the user unlocks the device after restart, your app can switch to
accessing credential encrypted storage and use regular system services that
depend on user credentials, like Google Play Services.</p>
<p>To get notified when the user unlocks the device after a reboot,
register a <code>BroadcastReceiver</code> from a running component to listen
for the <code>ACTION_USER_UNLOCKED</code> message. Or, you can receive the
existing <code>BOOT_COMPLETED</code> message, which now indicates the
device has booted and the user has unlocked the device.</p>
<p>You can directly query if the user has unlocked the device by calling
<code>UserManager.isUserUnlocked()</code>.</p>
<h2 id="migrating">Migrating Existing Data</h2>
<p>If a user updates their device to use Direct Boot mode, you might have
existing data that needs to get migrated to device encrypted storage. Use
<code>Context.migrateSharedPreferencesFrom()</code> and
<code>Context.migrateDatabaseFrom()</code> to migrate preference and database
data between credential encrypted storage and device encrypted storage.</p>
<p>Use your best judgment when deciding what data to migrate from credential
encrypted storage to device encrypted storage. You should not be migrating
private user information, such as passwords or authorization tokens, to
device encrypted storage. In some scenarios, you might need to manage
separate sets of data in the two encrypted stores.</p>
<h2 id="testing">Testing Your Encryption Aware App</h2>
<p>Test your encryption aware application using the new Direct Boot mode.
On supported devices with Android N Developer Preview installed, enable Direct
Boot by doing one of the following:</p>
<ul>
<li>On the device, enable <b>Developer options</b> if you haven't already by
going to <b>Settings &gt; About phone</b>, and tap <b>Build number</b> seven
times. Once developer options is available, go to <b>Settings &gt;
Developer options</b> and select <b>Convert to file encryption</b>.
Note that enabling Direct Boot will wipe user data.</li>
<li>Use the following adb shell commands to wipe user data and enable Direct
Boot mode:
<pre class="no-pretty-print">
$ adb reboot-bootloader
$ fastboot --wipe-and-use-fbe
</pre>
</li>
</ul>
<p>An emulated Direct Boot mode is also available, in case you need to switch
modes on your test devices. Emulated mode should only be used during
development and may cause data loss. To enable emulated Direct Boot mode,
set a lock pattern on the device, choose "No thanks" if prompted for a
secure start-up screen when setting a lock pattern, and then use the
following adb shell command:</p>
<pre class="no-pretty-print">
$ adb shell sm set-emulate-fbe true
</pre>
<p>To turn off emulated Direct Boot mode, use the following command:</p>
<pre class="no-pretty-print">
$ adb shell sm set-emulate-fbe false
</pre>
<p>Note that using these commands will automatically cause the device to
reboot.</p>