This article describes how to enable file-based encoding on new devices and how system applications can use the Direct Boot APIs to offer users the best, most impregnable experience possible .
- For new devices running Android 10 and
encryption is required.
- Devices running Android 9 and higher can use adoptable storage
and file-based encryption.
- For devices running Android 7.0–8.1, file-based
encryption can’t be used together with adoptable storage. If file-based
encryption is enabled on these devices, new storage media (such as an SD
card) must be used as traditional
File-based encoding enables a new have introduced in Android 7.0 called Direct Boot. Direct Boot allows encrypted devices to boot uncoiled to the interlock screen. previously, on code devices using full-disk encoding ( FDE ), users needed to provide credentials before any data could be accessed, preventing the earphone from performing all but the most basic of operations. For example, alarms could not operate, handiness services were unavailable, and phones could not receive calls but were limited to only basic hand brake dialer operations.
With the introduction of file-based encoding ( FBE ) and newfangled APIs to make applications aware of encoding, 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 drug user of the device has two storehouse locations available to applications :
- Credential Encrypted (CE) storage, which is the default storage location
and only available after the user has unlocked the device.
- Device Encrypted (DE) storage, which is a storage location available both
during Direct Boot mode and after the user has unlocked the device.
This separation makes sour profiles more secure because it allows more than one exploiter to be protected at a time as the encoding is no longer based entirely on a kick 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 motivation to notify applications when a exploiter ’ south CE repositing is unlocked in reaction to foremost enter 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 careless of whether or not they implement FBE. Although, without FBE, DE and CE repositing will always be in the unlock submit .
A complete implementation of file-based encoding on the Ext4 and F2FS file systems 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 organization on chip ( SoC ) used .
All the necessary packages in AOSP have been updated to be direct-boot aware. however, where device manufacturers use customize versions of these apps, they will want to ensure at a minimal there are direct-boot mindful packages providing the pursuit services :
- Telephony Services and Dialer
- Input method for entering passwords into the lock screen
Examples and source
Android provides a reference implementation of file-based encoding, in which vold ( system/vold ) provides the functionality for managing memory devices and volumes on Android. The accession of FBE provides vold with several new commands to support winder management for the CE and DE keys of multiple users. In addition to the core changes to use the file-based encoding capabilities in kernel, many organization packages including the lockscreen and the SystemUI have been modified to support the FBE and Direct Boot features. These include :
- AOSP Dialer (packages/apps/Dialer)
- Desk Clock (packages/apps/DeskClock)
- LatinIME (packages/inputmethods/LatinIME)*
- Settings App (packages/apps/Settings)*
- SystemUI (frameworks/base/packages/SystemUI)*
* System applications that use the
defaultToDeviceProtectedStorage manifest attribute
More examples of applications and services that are encoding mindful can be found by running the command
mangrep directBootAware in the frameworks or packages directory of the AOSP source tree .
To use the AOSP execution of FBE securely, a device needs to meet the pursuit dependencies :
- Kernel Support for Ext4 encryption or F2FS encryption.
Support with a HAL version 1.0 or 2.0. There is no support for
Keymaster 0.3 as that does not provide that necessary capabilities or assure
sufficient protection for encryption keys.
- Keymaster/Keystore and
Gatekeeper must be implemented in a Trusted Execution
Environment (TEE) to provide protection for the DE keys so that an
unauthorized OS (custom OS flashed onto the device) cannot simply request the
- Hardware Root of Trust and Verified Boot
bound to the keymaster initialisation is required to ensure that Device
Encryption credentials are not accessible by an unauthorized operating
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 booklet that holds the key that decrypts the system. Most contents should reside in credential-encrypted storage quite than device-encrypted storage .
first and first, apps such as alarm clocks, telephone, approachability features should be made android : directBootAware according to Direct Boot developer documentation .
Kernel back for Ext4 and F2FS encoding is available in the Android common kernels, interpretation 3.18 and higher. To enable it in a kernel that is version 5.1 or higher, use :
For older kernels, use
CONFIG_EXT4_ENCRYPTION=y if your device ‘s
userdata filesystem is Ext4, or use
CONFIG_F2FS_FS_ENCRYPTION=y if your device ‘s
userdata filesystem is F2FS .
If your device will support adoptable storage or will use metadata encoding on inner repositing, besides enable the kernel configuration options needed for metadata encoding as described in the metadata encoding documentation .
In addition to functional subscribe for Ext4 or F2FS encoding, device manufacturers should besides enable cryptanalytic acceleration to speed up file-based encoding and improve the drug user experience. For example, on ARM64-based devices, ARMv8 CE ( Cryptography Extensions ) acceleration can be enabled by setting the postdate kernel configuration options :
To foster improve operation and reduce exponent usage, device manufacturers may besides consider implementing inline encoding hardware, which encrypts/decrypts the data while it is on the room to/from the storage device. The Android park kernels ( version 4.14 and higher ) contain a model that allows inline encoding to be used when hardware and seller driver support is available. The inline encoding framework can be enabled by setting the watch kernel configuration options :
CONFIG_BLK_INLINE_ENCRYPTION=y CONFIG_FS_ENCRYPTION=y CONFIG_FS_ENCRYPTION_INLINE_CRYPT=y
If your device uses UFS-based storage, besides enable :
If your device uses eMMC-based storage, besides enable :
Enabling file-based encryption
Enabling FBE on a device requires enabling it on the home storehouse (
userdata ). This besides mechanically enables FBE on adoptable storage ; however, the encoding format on adoptable repositing may be override if necessary .
FBE is enabled by adding the option
fileencryption=contents_encryption_mode[:filenames_encryption_mode[:flags]] to the fs_mgr_flags column of the
fstab channel for
userdata. This choice defines the encoding format on internal storage. It contains up to three colon-separated parameters :
contents_encryption_modeparameter defines which
cryptographic algorithm is used to encrypt file contents. It can be either
adiantum. Since Android
11 it can also be left empty to specify the
default algorithm, which is
filenames_encryption_modeparameter defines which
cryptographic algorithm is used to encrypt file names. It can be either
adiantum. If not specified, it defaults to
aes-256-xts, or to
flagsparameter, new in Android
11, is a list of flags separated by the
+character. The following flags are supported:
v1flag selects version 1 encryption policies; the
v2flag selects version 2 encryption policies. Version
2 encryption policies use a more secure and flexible key derivation function. The default is v2 if
the device launched on Android 11 or higher
(as determined by
ro.product.first_api_level), or v1 if
the device launched on Android 10 or
inlinecrypt_optimizedflag selects an encryption
format that is optimized for inline encryption hardware that doesn’t
handle large numbers of keys efficiently. It does this by deriving
just one file contents encryption key per CE or DE key, rather than
one per file. The generation of IVs (initialization vectors) is
emmc_optimizedflag is similar to
inlinecrypt_optimized, but it also selects an IV
generation method that limits IVs to 32 bits. This flag should only
be used on inline encryption hardware that is compliant with the
JEDEC eMMC v5.2 specification and therefore supports only 32-bit
IVs. On other inline encryption hardware, use
inlinecrypt_optimizedinstead. This flag should never
be used on UFS-based storage; the UFS specification allows the use
of 64-bit IVs.
- On devices that support hardware-wrapped
wrappedkey_v0flag enables the use of
hardware-wrapped keys for FBE. This can only be used in combination
inlinecryptmount option, and either the
If you are n’t using inline encoding hardware the recommend place setting for most devices is
fileencryption=aes-256-xts. If you are using inline encoding hardware the recommend place for most devices is
fileencryption=aes-256-xts:aes-256-cts:inlinecrypt_optimized ( or equivalently
fileencryption=::inlinecrypt_optimized ). On devices without any mannequin of AES acceleration, Adiantum may be used rather of AES by setting
On devices that launched with Android 10 or lower,
fileencryption=ice is besides accepted to specify the use of the
FSCRYPT_MODE_PRIVATE file contents encoding mode. This manner is unimplemented by the Android common kernels, but it could be implemented by vendors using custom kernel patches. The on-disk format produced by this mode was vendor-specific. On devices launching with Android 11 or higher, this mode is no long allowed and a standard encoding format must be used alternatively .
Caution : Since the
fileencryption option defines the on-disk format, it can not be changed by an OTA .
By default option, file contents encoding is done using the Linux kernel’s cryptanalysis API. If you want to use inline encoding hardware rather, besides add the
inlinecrypt wax choice. For model, a wide
fstab line might look like :
/dev/block/by-name/userdata /data f2fs nodev,noatime,nosuid,errors=panic,inlinecrypt wait,fileencryption=aes-256-xts:aes-256-cts:inlinecrypt_optimized
go in different columns, since
filesystem mount option whereas
fileencryptionis a flag
for Android userspace.
- If your inline encryption hardware works correctly and the
wrappedkey_v0flag isn’t set, the
inlinecryptmount option can be added or removed at any
time without wiping the device. In other words, unless
hardware-wrapped keys are enabled,
only affect the implementation, not the on-disk format. You should
inlinecryptduring development to verify
that your inline encryption hardware is working correctly.
Since Android 9, FBE and adoptable storage can be used together .
fileencryption fstab choice for
userdata besides automatically enables both FBE and metadata encoding on adoptable storehouse. however, you may override the FBE and/or metadata encoding formats on adoptable storehouse by setting properties in
On devices that launched with Android 11 or higher, use the comply properties :
ro.crypto.volume.options(new in Android
11) selects the FBE encryption format on
adoptable storage. It has the same syntax as the argument to the
fileencryptionfstab option, and it uses the same defaults.
See the recommendations for
fileencryptionabove for what to
ro.crypto.volume.metadata.encryptionselects the metadata
encryption format on adoptable storage. See the metadata
On devices that launched with Android 10 or lower, use the be properties :
ro.crypto.volume.contents_modeselects the contents
encryption mode. This is equivalent to the first colon-separated field of
ro.crypto.volume.filenames_modeselects the filenames
encryption mode. This is equivalent to the second colon-separated field of
ro.crypto.volume.options, except that the default on devices
that launched with Android 10 or lower is
aes-256-heh. On most devices, this needs to be explicitly
ro.crypto.fde_sector_sizeselect the metadata encryption
format on adoptable storage. See the metadata
Caution : On devices that launched with Android 10 or lower, the default filenames encoding mode on adoptable memory was not valid on most devices, and it differed from the default option mode on inner storage. consequently, on such devices it must be explicitly override, normally to
Integrating with Keymaster
The generation of keys and management of the kernel keyring is handled by
vold. The AOSP implementation of FBE requires that the device back Keymaster HAL version 1.0 or late. There is no support for earlier versions of the Keymaster HAL .
On first boot, user 0 ’ mho keys are generated and installed early in the boot march. By the time the
on-post-fs phase of
init completes, the Keymaster must be fix to handle requests. On Pixel devices, this is handled by having a script forget ensure Keymaster is started before
/data is mounted .
File-based encoding applies the encoding policy at the directory grade. When a device ’ second
userdata partition is first created, the basic structures and policies are applied by the
init scripts. These scripts will trigger the initiation of the first base user ’ second ( drug user 0 ’ second ) CE and DE keys angstrom well as define which directories are to be encrypted with these keys. When extra users and profiles are created, the necessary extra keys are generated and stored in the keystore ; their certificate and devices storehouse locations are created and the encoding policy links these keys to those directories .
In Android 11 and higher, the encoding policy is no long hardcoded into a centralized location, but quite is defined by arguments to the
mkdir commands in the init scripts. Directories encrypted with the system DE key manipulation
encryption=Require, while unencrypted directories ( or directories whose subdirectories are encrypted with per-user keys ) use
In Android 10, the encoding policy was hardcoded into this location :
In Android 9 and earlier, the location was :
It is possible to add exceptions to prevent sealed directories from being encrypted at all. 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 merely know acceptable use case for this is in support of bequest OTA capabilities .
Supporting Direct Boot in system applications
Making applications Direct Boot aware
To facilitate rapid migration of system apps, there are two new attributes that can be set at the application floor. The
defaultToDeviceProtectedStorage impute is available only to system apps. The
directBootAware assign is available to all .
directBootAware attribute at the application level is shorthand for marking all components in the app as being encoding mindful .
defaultToDeviceProtectedStorage impute redirects the default app storage localization to point at DE storehouse alternatively of pointing at CE memory. System apps using this flag must carefully audit all data stored in the nonpayment location, and change the paths of sensitive data to use CE storage. Device manufactures using this option should cautiously inspect the data that they are storing to ensure that it contains no personal information .
When running in this mode, the follow system APIs are available to explicitly manage a Context backed by CE storage when needed, which are equivalent to their Device Protected counterparts .
Supporting multiple users
Each user in a multi-user environment gets a branch encoding keystone. Every exploiter gets two keys : a DE and a CE key. User 0 must log into the device first gear as it is a limited exploiter. This is apposite for Device Administration uses .
Crypto-aware applications interact across users in this manner :
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 unlock .
An application may be able to interact freely across the DE areas, but one drug user unlocked does not mean that all the users on the device are unlocked. The application should check this condition before trying to access these areas .
Each work profile exploiter ID besides gets two keys : DE and CE. When the solve challenge is met, the visibility exploiter is unlock and the Keymaster ( in TEE ) can provide the profile ’ s TEE samara .
The convalescence partition is unable to access the DE-protected storage on the userdata division. Devices implementing FBE are powerfully recommended to support OTA using A/B system updates. As the OTA can be applied during normal operation there is no need for convalescence to access data on the code drive .
When using a bequest OTA solution, which requires recovery to access the OTA file on the
userdata partition :
- Create a top-level directory (for example
misc_ne) in the
- Add this top-level directory to the encryption policy exception (see
Encryption policy above).
- Create a directory within the top-level directory to hold OTA packages.
- Add an SELinux rule and file contexts to control access to this folder and
it contents. Only the process or applications receiving OTA updates should be
able to read and write to this folder. No other application or process should
have access to this folder.
To ensure the enforce version of the feature works a intended, beginning run the many CTS encoding tests, such as DirectBootHostTest and EncryptionTest .
If the device is running Android 11 or higher, besides run vts_kernel_encryption_test :
vts-tradefed run vts -m vts_kernel_encryption_test
In summation, device manufacturers may perform the keep up manual tests. On a device with FBE enabled :
- Check that
- Check that
ro.crypto.typeis set to
additionally, testers can boot a
userdebug exemplify with a lockscreen typeset on the primary user. then
adb shell into the device and use
su to become rout. Make sure
/data/data contains encrypted filename ; if it does not, something is wrong .
Device manufacturers are besides encouraged to explore running the upriver Linux tests for fscrypt on their devices or kernels. These tests are part of the xfstests filesystem test cortege. however, these upstream tests are not offically supported by Android .
AOSP implementation details
This segment provides details on the AOSP execution and describes how file-based encoding 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 “ fscrypt ” encoding ( supported by ext4 and f2fs ) in the kernel and normally is configured to :
- Encrypt file contents with AES-256 in XTS mode
- Encrypt file names with AES-256 in CBC-CTS mode
Adiantum encoding is besides supported. When Adiantum encoding is enabled, both file contents and file names are encrypted with Adiantum .
For more information about fscrypt, see the upstream kernel software documentation .
File-based encoding keys, which are 512-bit keys, are stored encrypted by another identify ( a 256-bit AES-GCM key ) held in the TEE. To use this TEE winder, three requirements must be met :
- The auth token
- The stretched credential
- The “secdiscardable hash”
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 right auth token is supplied. If the exploiter has no certificate, then no auth token is used nor needed.
The stretch certificate is the user certificate after salting and stretching with the
scrypt algorithm. The certificate is actually hashed once in the lock in settings serve 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 exploiter has no certificate, then no load certificate is used nor needed .
secdiscardable hash is a 512-bit hash of a random 16 KB file stored alongside other information used to reconstruct the keystone, such as the seed. This charge is securely deleted when the key is deleted, or it is encrypted in a new way ; this added auspices ensures an attacker must recover every piece 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
In most cases, FBE keys besides undergo an extra winder derivation step in the kernel in order to generate the subkeys actually used to do the encoding, for exemplar per-file or per-mode keys. For translation 2 encoding policies, HKDF-SHA512 is used for this .