File-Based Encryption | Android Open Source Project

Android 7.0 and later supports file-based encryption (FBE). File-basedencryption allows different files to be encrypted with different keys that canbe unlocked independently.

This article describes how to enable file-based encryption on new devicesand how system applications can be updated to take full advantage of the newDirect Boot APIs and offer users the best, most secure experience possible.

Warning: File-based encryption cannotcurrently be used together with adoptable storage. On devices usingfile-based encryption, new storage media (such as an SD card) must be used astraditional storage.

File-based encryption enables a new feature introduced in Android 7.0 called DirectBoot. Direct Boot allows encrypted devices to boot straight to the lockscreen. Previously, on encrypted devices using full-diskencryption (FDE), users needed to provide credentials before any data couldbe accessed, preventing the phone from performing all but the most basic ofoperations. For example, alarms could not operate, accessibility services wereunavailable, and phones could not receive calls but were limited to only basicemergency dialer operations.

With the introduction of file-based encryption (FBE) and new APIs to makeapplications aware of encryption, it is possible for these apps to operatewithin a limited context. This can happen before users have provided theircredentials while still protecting private user information.

On an FBE-enabled device, each user of the device has two storage locationsavailable to applications:

This separation makes work profiles more secure because it allows more than oneuser to be protected at a time as the encryption is no longer based solely on aboot time password.

The Direct Boot API allows encryption-aware applications to access each of theseareas. There are changes to the application lifecycle to accommodate the need tonotify applications when a users CE storage is unlocked in response tofirst entering credentials at the lock screen, or in the case of work profileproviding aworkchallenge. Devices running Android 7.0 must support these new APIs andlifecycles regardless of whether or not they implement FBE. Although, withoutFBE, DE and CE storage will always be in the unlocked state.

A complete implementation of file-based encryption on an Ext4 file system isprovided in the Android Open Source Project (AOSP) and needs only be enabled ondevices that meet the requirements. Manufacturers electing to use FBE may wishto 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, theywill want to ensure at a minimum there are direct-boot aware packages providingthe following services:

Android provides a reference implementation of file-based encryption, in whichvold (system/vold)provides the functionality for managing storage devices andvolumes on Android. The addition of FBE provides vold with several new commandsto support key management for the CE and DE keys of multiple users. In additionto the core changes to use the ext4 Encryptioncapabilities in kernel many system packages including the lockscreen and theSystemUI have been modified to support the FBE and Direct Boot features. Theseinclude:

* System applications that use the defaultToDeviceProtectedStoragemanifest attribute

More examples of applications and services that are encryption aware can befound by running the command mangrep directBootAware in theframeworks or packages directory of the AOSPsource tree.

To use the AOSP implementation of FBE securely, a device needs to meet thefollowing dependencies:

Note: Storage policies are applied to a folder and all of itssubfolders. Manufacturers should limit the contents that go unencrypted to theOTA folder and the folder that holds the key that decrypts the system. Mostcontents should reside in credential-encrypted storage rather thandevice-encrypted storage.

First and foremost, apps such as alarm clocks, phone, accessibility featuresshould be made android:directBootAware according to DirectBoot developer documentation.

The AOSP implementation of file-based encryption uses the ext4 encryptionfeatures in the Linux 4.4 kernel. The recommended solution is to use a kernelbased on 4.4 or later. Ext4 encryption has also been backported to a 3.10 kernelin the Android common repositories and for the supported Nexus kernels.

The android-3.10.y branch in the AOSP kernel/common git repository mayprovide a good starting point for device manufacturers that want to import thiscapability into their own device kernels. However, it is necessary to applythe 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 ofthese patches.

Note that each of these kernels uses a backport to 3.10. The ext4and jbd2 drivers from linux 3.18 were transplanted into existing kernels basedon 3.10. Due to interdependencies between parts of the kernel, this backportbreaks 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 mayalso consider implementing cryptographic acceleration to speed up file-basedencryption and improve the user experience.

FBE is enabled by adding the flagfileencryption=contents_encryption_mode[:filenames_encryption_mode]to the fstab line in the final column for the userdatapartition. contents_encryption_mode parameter defines whichcryptographic algorithm is used for the encryption of file contents andfilenames_encryption_mode for the encryption of filenames.contents_encryption_mode can be only aes-256-xts.filenames_encryption_mode has two possible values: aes-256-ctsand aes-256-heh. If filenames_encryption_mode is not specifiedthen aes-256-cts value is used.

Whilst testing the FBE implementation on a device, it is possible to specify thefollowing flag:forcefdeorfbe=""

This sets the device up with FDE but allows conversion to FBE for developers. Bydefault, this behaves like forceencrypt, putting the device intoFDE mode. However, it will expose a debug option allowing a device to be putinto FBE mode as is the case in the developer preview. It is also possible toenable FBE from fastboot using this command:

This is intended solely for development purposes as a platform for demonstratingthe feature before actual FBE devices are released. This flag may be deprecatedin the future.

The generation of keys and management of the kernel keyring is handled byvold. The AOSP implementation of FBE requires that the devicesupport Keymaster HAL version 1.0 or later. There is no support for earlierversions of the Keymaster HAL.

On first boot, user 0s keys are generated and installed early in the bootprocess. By the time the on-post-fs phase of initcompletes, the Keymaster must be ready to handle requests. On Nexus devices,this is handled by having a script block:

Note: All encryption is based on AES-256 inXTS mode. Due to the way XTS is defined, it needs two 256-bit keys; so ineffect, both CE and DE keys are 512-bit keys.

Ext4 encryption applies the encryption policy at the directory level. When adevices userdata partition is first created, the basic structuresand policies are applied by the init scripts. These scripts willtrigger the creation of the first users (user 0s) CE and DE keys as well asdefine which directories are to be encrypted with these keys. When additionalusers and profiles are created, the necessary additional keys are generated andstored in the keystore; their credential and devices storage locations arecreated and the encryption policy links these keys to those directories.

In the current AOSP implementation, the encryption policy is hardcoded into thislocation:

It is possible to add exceptions in this file to prevent certain directoriesfrom being encrypted at all, by adding to the directories_to_excludelist. If modifications of this sort are made then the devicemanufacturer should include SELinux policies that only grant access to theapplications that need to use the unencrypted directory. This should exclude alluntrusted applications.

The only known acceptable use case for this is in support of legacy OTAcapabilities.

To facilitate rapid migration of system apps, there are two new attributes thatcan be set at the application level. ThedefaultToDeviceProtectedStorage attribute is available only tosystem apps. The directBootAware attribute is available to all.

The directBootAware attribute at the application level is shorthand for markingall components in the app as being encryption aware.

The defaultToDeviceProtectedStorage attribute redirects the defaultapp 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 defaultlocation, and change the paths of sensitive data to use CE storage. Devicemanufactures using this option should carefully inspect the data that they arestoring to ensure that it contains no personal information.

When running in this mode, the following System APIs areavailable to explicitly manage a Context backed by CE storage when needed, whichare equivalent to their Device Protected counterparts.

Each user in a multi-user environment gets a separate encryption key. Every usergets two keys: a DE and a CE key. User 0 must log into the device first as it isa special user. This is pertinent for DeviceAdministration uses.

Crypto-aware applications interact across users in this manner:INTERACT_ACROSS_USERS and INTERACT_ACROSS_USERS_FULLallow an application to act across all the users on the device. However, thoseapps will be able to access only CE-encrypted directories for users that arealready unlocked.

An application may be able to interact freely across the DE areas, but one userunlocked does not mean that all the users on the device are unlocked. Theapplication 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 challengeis met, the profile user is unlocked and the Keymaster (in TEE) can provide theprofiles TEE key.

The recovery partition is unable to access the DE-protected storage on theuserdata partition. Devices implementing FBE are strongly recommended to supportOTA using A/B system updates. Asthe OTA can be applied during normal operation there is no need for recovery toaccess data on the encrypted drive.

When using a legacy OTA solution, which requires recovery to access the OTA fileon the userdata partition:

To ensure the implemented version of the feature works as intended, employ themany CTS encryption tests.

Once the kernel builds for your board, also build for x86 and run under QEMU inorder to test with xfstest by using:

In addition, device manufacturers may perform these manual tests. On a devicewith FBE enabled:

Additionally, testers can boot a userdebug instance with a lockscreen set on theprimary user. Then adb shell into the device and usesu to become root. Make sure /data/data containsencrypted filenames; if it does not, something is wrong.

This section provides details on the AOSP implementation and describes howfile-based encryption works. It should not be necessary for device manufacturersto 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 encryptedby 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 byGatekeeperwhen a user successfully logs in. The TEE will refuse to use the key unless thecorrect auth token is supplied. If the user has no credential, then no authtoken is used nor needed.

The stretched credential is the user credential after salting andstretching with the scrypt algorithm. The credential is actuallyhashed once in the lock settings service before being passed tovold for passing to scrypt. This is cryptographicallybound to the key in the TEE with all the guarantees that apply toKM_TAG_APPLICATION_ID. If the user has no credential, then nostretched credential is used nor needed.

The secdiscardable hash is a 512-bit hash of a random 16 KB filestored alongside other information used to reconstruct the key, such as theseed. This file is securely deleted when the key is deleted, or it is encryptedin a new way; this added protection ensures an attacker must recover every bitof this securely deleted file to recover the key. This is cryptographicallybound to the key in the TEE with all the guarantees that apply toKM_TAG_APPLICATION_ID. See the KeystoreImplementer's Reference.

Continued here:
File-Based Encryption | Android Open Source Project