Android 7.0 and later supports file-based encryption (FBE). File-based encryption allows different files to be encrypted with different keys that can be unlocked independently.
This article describes how to enable file-based encryption on new devices and how system applications can be updated to take full advantage of the new Direct Boot APIs and offer users the best, most secure experience possible.
Warning: File-based encryption cannot currently be used together with adoptable storage. On devices using file-based encryption, new storage media (such as an SD card) must be used as traditional storage.
File-based encryption enables a new feature introduced in Android 7.0 called Direct Boot. Direct Boot allows encrypted devices to boot straight to the lock screen. Previously, on encrypted devices using full-disk encryption (FDE), users needed to provide credentials before any data could be accessed, preventing the phone from performing all but the most basic of operations. For example, alarms could not operate, accessibility services were unavailable, and phones could not receive calls but were limited to only basic emergency dialer operations.
With the introduction of file-based encryption (FBE) and new APIs to make applications aware of encryption, it is possible for these apps to operate within a limited context. This can happen before users have provided their credentials while still protecting private user information.
On an FBE-enabled device, each user of the device has two storage locations available to applications:
This separation makes work profiles more secure because it allows more than one user to be protected at a time as the encryption is no longer based solely on a boot time password.
The Direct Boot API allows encryption-aware applications to access each of these areas. There are changes to the application lifecycle to accommodate the need to notify applications when a user’s CE storage is unlocked in response to first entering credentials at the lock screen, or in the case of work profile providing a work challenge. Devices running Android 7.0 must support these new APIs and lifecycles regardless of whether or not they implement FBE. Although, without FBE, DE and CE storage will always be in the unlocked state.
A complete implementation of file-based encryption on an Ext4 file system is provided in the Android Open Source Project (AOSP) and needs only be enabled on devices that meet the requirements. Manufacturers electing to use FBE may wish to explore ways of optimizing the feature based on the system on chip (SoC) used.
All the necessary packages in AOSP have been updated to be direct-boot aware. However, where device manufacturers use customized versions of these apps, they will want to ensure at a minimum there are direct-boot aware packages providing the following services:
Android provides a reference implementation of file-based encryption, in which vold (system/vold) provides the functionality for managing storage devices and volumes on Android. The addition of FBE provides vold with several new commands to support key management for the CE and DE keys of multiple users. In addition to the core changes to use the ext4 Encryption capabilities in kernel many system packages including the lockscreen and the SystemUI have been modified to support the FBE and Direct Boot features. These include:
* System applications that use the defaultToDeviceProtectedStorage
manifest attribute
More examples of applications and services that are encryption aware can be
found by running the command mangrep directBootAware in the
frameworks or packages directory of the AOSP
source tree.
To use the AOSP implementation of FBE securely, a device needs to meet the following dependencies:
Note: Storage policies are applied to a folder and all of its subfolders. Manufacturers should limit the contents that go unencrypted to the OTA folder and the folder that holds the key that decrypts the system. Most contents should reside in credential-encrypted storage rather than device-encrypted storage.
First and foremost, apps such as alarm clocks, phone, accessibility features should be made android:directBootAware according to Direct Boot developer documentation.
The AOSP implementation of file-based encryption uses the ext4 encryption features in the Linux 4.4 kernel. The recommended solution is to use a kernel based on 4.4 or later. Ext4 encryption has also been backported to a 3.10 kernel in the Android common repositories and for the supported Nexus kernels.
The android-3.10.y branch in the AOSP kernel/common git repository may provide a good starting point for device manufacturers that want to import this capability into their own device kernels. However, it is necessary to apply the most recent patches from the latest stable Linux kernel (currently linux-4.6) of the ext4 and jbd2 projects. The Nexus device kernels already include many of these patches.
| Device | Kernel |
|---|---|
| Android Common | kernel/common android-3.10.y (git) |
| Nexus 5X (bullhead) | kernel/msm android-msm-bullhead-3.10-n-preview-2 (git) |
| Nexus 6P (angler) | kernel/msm android-msm-angler-3.10-n-preview-2 (git) |
Note that each of these kernels uses a backport to 3.10. The ext4 and jbd2 drivers from linux 3.18 were transplanted into existing kernels based on 3.10. Due to interdependencies between parts of the kernel, this backport breaks support for a number of features that are not used by Nexus devices. These include:
In addition to functional support for ext4 encryption, device manufacturers may also consider implementing cryptographic acceleration to speed up file-based encryption and improve the user experience.
FBE is enabled by adding the flag fileencryption with no parameters
to the fstab line in the final column for the userdata
partition. You can see an example at:
https://android.googlesource.com/device/lge/bullhead/+/nougat-release/fstab_fbe.bullhead
Whilst testing the FBE implementation on a device, it is possible to specify the
following flag:
forcefdeorfbe="<path/to/metadata/partition>"
This sets the device up with FDE but allows conversion to FBE for developers. By
default, this behaves like forceencrypt, putting the device into
FDE mode. However, it will expose a debug option allowing a device to be put
into FBE mode as is the case in the developer preview. It is also possible to
enable FBE from fastboot using this command:
fastboot --wipe-and-use-fbe
This is intended solely for development purposes as a platform for demonstrating the feature before actual FBE devices are released. This flag may be deprecated in the future.
The generation of keys and management of the kernel keyring is handled by
vold. The AOSP implementation of FBE requires that the device
support Keymaster HAL version 1.0 or later. There is no support for earlier
versions of the Keymaster HAL.
On first boot, user 0’s keys are generated and installed early in the boot
process. By the time the on-post-fs phase of init
completes, the Keymaster must be ready to handle requests. On Nexus devices,
this is handled by having a script block:
/data is mounted
Note: All encryption is based on AES-256 in XTS mode. Due to the way XTS is defined, it needs two 256-bit keys; so in effect, both CE and DE keys are 512-bit keys.
Ext4 encryption applies the encryption policy at the directory level. When a
device’s userdata partition is first created, the basic structures
and policies are applied by the init scripts. These scripts will
trigger the creation of the first user’s (user 0’s) CE and DE keys as well as
define which directories are to be encrypted with these keys. When additional
users and profiles are created, the necessary additional keys are generated and
stored in the keystore; their credential and devices storage locations are
created and the encryption policy links these keys to those directories.
In the current AOSP implementation, the encryption policy is hardcoded into this location:
/system/extras/ext4_utils/ext4_crypt_init_extensions.cpp
It is possible to add exceptions in this file to prevent certain directories
from being encrypted at all, by adding to the directories_to_exclude
list. If modifications of this sort are made then the device
manufacturer should include
SELinux policies that only grant access to the
applications that need to use the unencrypted directory. This should exclude all
untrusted applications.
The only known acceptable use case for this is in support of legacy OTA capabilities.
To facilitate rapid migration of system apps, there are two new attributes that
can be set at the application level. The
defaultToDeviceProtectedStorage attribute is available only to
system apps. The directBootAware attribute is available to all.
<application
android:directBootAware="true"
android:defaultToDeviceProtectedStorage="true">
The directBootAware attribute at the application level is shorthand for marking
all components in the app as being encryption aware.
The defaultToDeviceProtectedStorage attribute redirects the default
app storage location to point at DE storage instead of pointing at CE storage.
System apps using this flag must carefully audit all data stored in the default
location, and change the paths of sensitive data to use CE storage. Device
manufactures using this option should carefully inspect the data that they are
storing to ensure that it contains no personal information.
When running in this mode, the following System APIs are available to explicitly manage a Context backed by CE storage when needed, which are equivalent to their Device Protected counterparts.
Context.createCredentialProtectedStorageContext()
Context.isCredentialProtectedStorage()Each user in a multi-user environment gets a separate encryption key. Every user gets two keys: a DE and a CE key. User 0 must log into the device first as it is a special user. This is pertinent for Device Administration uses.
Crypto-aware applications interact across users in this manner:
INTERACT_ACROSS_USERS and INTERACT_ACROSS_USERS_FULL
allow an application to act across all the users on the device. However, those
apps will be able to access only CE-encrypted directories for users that are
already unlocked.
An application may be able to interact freely across the DE areas, but one user unlocked does not mean that all the users on the device are unlocked. The application should check this status before trying to access these areas.
Each work profile user ID also gets two keys: DE and CE. When the work challenge is met, the profile user is unlocked and the Keymaster (in TEE) can provide the profile’s TEE key.
The recovery partition is unable to access the DE protected storage on the userdata partition. Devices implementing FBE are strongly recommended to support OTA using the upcoming A/B system updates. As the OTA can be applied during normal operation there is no need for recovery to access data on the encrypted drive.
If a legacy OTA solution is used, which requires recovery to access the OTA file on the userdata partition then:
Within this folder create a directory to contain the OTA packages.
To ensure the implemented version of the feature works as intended, employ the many CTS encryption tests.
Once the kernel builds for your board, also build for x86 and run under QEMU in order to test with xfstest by using:
kvm-xfstests -c encrypt -g auto
In addition, device manufacturers may perform these manual tests. On a device with FBE enabled:
ro.crypto.state exists
ro.crypto.state is encryptedro.crypto.type exists
ro.crypto.type is set to file
Additionally, testers can boot a userdebug instance with a lockscreen set on the
primary user. Then adb shell into the device and use
su to become root. Make sure /data/data contains
encrypted filenames; if it does not, something is wrong.
This section provides details on the AOSP implementation and describes how file-based encryption works. It should not be necessary for device manufacturers to make any changes here to use FBE and Direct Boot on their devices.
The AOSP implementation uses ext4 encryption in kernel and is configured to:
Disk encryption keys, which are 512-bit AES-XTS keys, are stored encrypted by another key (a 256-bit AES-GCM key) held in the TEE. To use this TEE key, three requirements must be met:
The auth token is a cryptographically authenticated token generated by Gatekeeper when a user successfully logs in. The TEE will refuse to use the key unless the correct auth token is supplied. If the user has no credential, then no auth token is used nor needed.
The stretched credential is the user credential after salting and
stretching with the scrypt algorithm. The credential is actually
hashed once in the lock settings service before being passed to
vold for passing to scrypt. This is cryptographically
bound to the key in the TEE with all the guarantees that apply to
KM_TAG_APPLICATION_ID. If the user has no credential, then no
stretched credential is used nor needed.
The secdiscardable hash is a 512-bit hash of a random 16 KB file
stored alongside other information used to reconstruct the key, such as the
seed. This file is securely deleted when the key is deleted, or it is encrypted
in a new way; this added protection ensures an attacker must recover every bit
of this securely deleted file to recover the key. This is cryptographically
bound to the key in the TEE with all the guarantees that apply to
KM_TAG_APPLICATION_ID. See the Keystore
Implementer's Reference.