File-Based Encryption | Android Open Source Project

Android 7.0 and higher supports file-based encoding ( FBE ). File-based encoding allows different files to be encrypted with unlike keys that can be unlocked independently .
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 .
Caution :

• For new devices running Android 10 and
  higher, file-based
  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
  storage.

Direct Boot

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 .

Dependencies

To use the AOSP execution of FBE securely, a device needs to meet the pursuit dependencies :

• Kernel Support for Ext4 encryption or F2FS encryption.
• Keymaster
  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
  DE keys.
• 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
  system.

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 .

Implementation

first and first, apps such as alarm clocks, telephone, approachability features should be made android : directBootAware according to Direct Boot developer documentation .

Kernel Support

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 :

CONFIG_FS_ENCRYPTION=y

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 :

CONFIG_CRYPTO_AES_ARM64_CE_BLK=y
CONFIG_CRYPTO_SHA2_ARM64_CE=y

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 :

CONFIG_SCSI_UFS_CRYPTO=y

If your device uses eMMC-based storage, besides enable :

CONFIG_MMC_CRYPTO=y

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 .

Internal storage

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 :

• The contents_encryption_mode parameter defines which
  cryptographic algorithm is used to encrypt file contents. It can be either
  aes-256-xts or adiantum. Since Android
  11 it can also be left empty to specify the
  default algorithm, which is aes-256-xts.
• The filenames_encryption_mode parameter defines which
  cryptographic algorithm is used to encrypt file names. It can be either
  aes-256-cts, aes-256-heh, or
  adiantum. If not specified, it defaults to
  aes-256-cts if contents_encryption_mode is
  aes-256-xts, or to adiantum if
  contents_encryption_mode is adiantum.
• The flags parameter, new in Android
  11, is a list of flags separated by the
  + character. The following flags are supported:
  • The v1 flag selects version 1 encryption policies; the
    v2 flag 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
    lower.
  • The inlinecrypt_optimized flag 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
    adjusted accordingly.
  • The emmc_optimized flag 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_optimized instead. 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
    keys, the wrappedkey_v0 flag enables the use of
    hardware-wrapped keys for FBE. This can only be used in combination
    with the inlinecrypt mount option, and either the
    inlinecrypt_optimized or emmc_optimized
    flag.

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 fileencryption=adiantum .
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

Note :

• The inlinecrypt and fileencryption options
  go in different columns, since inlinecrypt is a
  filesystem mount option whereas fileencryption is a flag
  for Android userspace.
• If your inline encryption hardware works correctly and the
  wrappedkey_v0 flag isn’t set, the
  inlinecrypt mount option can be added or removed at any
  time without wiping the device. In other words, unless
  hardware-wrapped keys are enabled, inlinecrypt should
  only affect the implementation, not the on-disk format. You should
  test removing inlinecrypt during development to verify
  that your inline encryption hardware is working correctly.

Adoptable storage

Since Android 9, FBE and adoptable storage can be used together .
Specifying the 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 PRODUCT_PROPERTY_OVERRIDES .
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
  fileencryption fstab option, and it uses the same defaults.
  See the recommendations for fileencryption above for what to
  use here.
• ro.crypto.volume.metadata.encryption selects the metadata
  encryption format on adoptable storage. See the metadata
  encryption documentation.

On devices that launched with Android 10 or lower, use the be properties :

• ro.crypto.volume.contents_mode selects the contents
  encryption mode. This is equivalent to the first colon-separated field of
  ro.crypto.volume.options.
• ro.crypto.volume.filenames_mode selects 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
  overridden to aes-256-cts.
• ro.crypto.fde_algorithm and
  ro.crypto.fde_sector_size select the metadata encryption
  format on adoptable storage. See the metadata
  encryption documentation.

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 aes-256-cts.

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 .

Encryption policy

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 encryption=None .
In Android 10, the encoding policy was hardcoded into this location :

/system/extras/libfscrypt/fscrypt_init_extensions.cpp

In Android 9 and earlier, the location was :

/system/extras/ext4_utils/ext4_crypt_init_extensions.cpp

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 .

The directBootAware attribute at the application level is shorthand for marking all components in the app as being encoding mindful .
The 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 .

• Context.createCredentialProtectedStorageContext()
• Context.isCredentialProtectedStorage()

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 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 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 :

1. Create a top-level directory (for example misc_ne) in the
   userdata partition.
2. Add this top-level directory to the encryption policy exception (see
   Encryption policy above).
3. Create a directory within the top-level directory to hold OTA packages.
4. 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.

Validation

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 :

atest vts_kernel_encryption_test

or :

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 ro.crypto.state exists
  • Ensure ro.crypto.state is encrypted
• Check that ro.crypto.type exists
  • Ensure ro.crypto.type is set to file

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 .

fscrypt encryption

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 .

Key derivation

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 .
The 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 KM_TAG_APPLICATION_ID .
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 .

source : https://coinselected.com
Category : crypto topics