tranminhdung.vn 7.0 and higher supports file-based encryption (FBE).File-based encryption allows different files to be encryptedwith different keys that can be unlocked independently.
Đang xem: Save project là gì
This article describes how to enable file-based encryption on new devicesand how system applications can use the Direct Boot APIs to offer usersthe best, most secure experience possible.
Caution: Devices running tranminhdung.vn 9 and higher can use adoptable storage and file-based encryption.
File-based encryption enables a new feature introduced in tranminhdung.vn 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:
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 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 user’s CE storage is unlocked in response tofirst entering credentials at the lock screen, or in the case of work profileproviding aworkchallenge. Devices running tranminhdung.vn 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 the Ext4 and F2FS filesystems is provided in the tranminhdung.vn Open tranminhdung.vn Project (AOSP) and needs only beenabled on devices that meet the requirements. Manufacturers electing to use FBEmay 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, theywill want to ensure at a minimum there are direct-boot aware packages providingthe following services:
Telephony Services and DialerInput method for entering passwords into the lock screen
Examples and tranminhdung.vn
tranminhdung.vn provides a reference implementation of file-based encryption, in whichvold (system/vold)provides the functionality for managing storage devices andvolumes on tranminhdung.vn. 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 file-basedencryption capabilities in kernel, many system packages including thelockscreen and the SystemUI have been modified to support the FBE and DirectBoot 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 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 AOSPtranminhdung.vn tree.
To use the AOSP implementation of FBE securely, a device needs to meet thefollowing dependencies:
Kernel Support for Ext4 encryption or F2FS encryption.KeymasterSupport with a HAL version 1.0 or 2.0. There is no support forKeymaster 0.3 as that does not provide that necessary capabilities or assuresufficient protection for encryption keys.Keymaster/Keystore andGatekeeper must be implemented in a Trusted ExecutionEnvironment (TEE) to provide protection for the DE keys so that anunauthorized OS (custom OS flashed onto the device) cannot simply request theDE keys.Hardware Root of Trust and Verified Bootbound to the keymaster initialisation is required to ensure that DeviceEncryption credentials are not accessible by an unauthorized operatingsystem.
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 tranminhdung.vn:directBootAware according to DirectBoot developer documentation.
Kernel support for Ext4 and F2FS encryption is available in the tranminhdung.vn commonkernels, version 3.18 and higher. To enable it in a kernel that is version 5.1or higher, use:
CONFIG_FS_ENCRYPTION=yFor older kernels, use CONFIG_EXT4_ENCRYPTION=y if your device”suserdata filesystem is Ext4, or useCONFIG_F2FS_FS_ENCRYPTION=y if your device”s userdatafilesystem is F2FS.
If your device will support adoptablestorage or will use metadataencryption on internal storage, also enable the kernel configuration optionsneeded for metadata encryption as described in the metadata encryption documentation.
In addition to functional support for Ext4 or F2FS encryption, devicemanufacturers should also enable cryptographic acceleration to speed upfile-based encryption and improve the user experience. For example, onARM64-based devices, ARMv8 CE (Cryptography Extensions) acceleration can beenabled by setting the following kernel configuration options:
CONFIG_CRYPTO_AES_ARM64_CE_BLK=yCONFIG_CRYPTO_SHA2_ARM64_CE=yTo further improve performance and reduce power usage, device manufacturers mayalso consider implementing inline encryption hardware, whichencrypts/decrypts the data while it is on the way to/from the storage device.The tranminhdung.vn common kernels (version 4.14 and higher) contain a framework thatallows inline encryption to be used when hardware and vendor driver support isavailable. The inline encryption framework can be enabled by setting thefollowing kernel configuration options:
CONFIG_BLK_INLINE_ENCRYPTION=yCONFIG_FS_ENCRYPTION=yCONFIG_FS_ENCRYPTION_INLINE_CRYPT=yIf your device uses UFS-based storage, also enable:
CONFIG_SCSI_UFS_CRYPTO=yIf your device uses eMMC-based storage, also enable:
Enabling file-based encryption
Enabling FBE on a device requires enabling it on the internal storage(userdata). This also automatically enables FBE on adoptablestorage; however, the encryption format on adoptable storage may be overriddenif necessary.
FBE is enabled by adding the optionfileencryption=contents_encryption_mode<:filenames_encryption_mode<:flags>>to the fs_mgr_flags column of the fstab line foruserdata. This option defines the encryption format on internalstorage. 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 tranminhdung.vn 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 tranminhdung.vn 11, is a list of flags separated by the + character. The following flags are supported: 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. The wrappedkey_v0 flag enables the use of hardware-wrapped keys. When enabled, FBE keys are not generated by software, but rather are generated by Keymaster using the STORAGE_KEY tag. Then, each FBE key actually provided to the kernel is the STORAGE_KEY key exported from Keymaster, which causes it to be wrapped with a per-boot ephemeral key. The kernel then provides the wrapped keys directly to the inline encryption hardware. When implemented correctly, the unwrapped keys are never present in system memory, and a compromised wrapped key cannot be used after a reboot. This flag requires hardware support, Keymaster support for STORAGE_KEY, kernel driver support, the inlinecrypt mount option, and either the inlinecrypt_optimized or emmc_optimized flags.
If you aren”t using inline encryption hardware the recommended setting for mostdevices is fileencryption=aes-256-xts. If you are using inlineencryption hardware the recommended setting for most devices isfileencryption=aes-256-xts:aes-256-cts:inlinecrypt_optimized(or equivalently fileencryption=::inlinecrypt_optimized). Ondevices without any form of AES acceleration, Adiantum may be used instead of AES bysetting fileencryption=adiantum.
On devices that launched with tranminhdung.vn 10 or lower,fileencryption=ice is also accepted to specify the use of theFSCRYPT_MODE_PRIVATE file contents encryption mode. This mode isunimplemented by the tranminhdung.vn common kernels, but it could be implemented byvendors using custom kernel patches. The on-disk format produced by this modewas vendor-specific. On devices launching with tranminhdung.vn11 or higher, this mode is no longer allowed and astandard encryption format must be used instead.
Caution: Since the fileencryption option defines the on-disk format, it cannot be changed by an OTA.
By default, file contents encryption is done using the Linux kernel”scryptography API. If you want to use inline encryption hardware instead, alsoadd the inlinecrypt mount option. For example, a fullfstab 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 tranminhdung.vn 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 tranminhdung.vn 9, FBE andadoptable storage can be used together.
Specifying the fileencryption fstab option foruserdata also automatically enables both FBE and metadata encryption on adoptablestorage. However, you may override the FBE and/or metadata encryption formats onadoptable storage by setting properties inPRODUCT_PROPERTY_OVERRIDES.
On devices that launched with tranminhdung.vn 11 or higher, usethe following properties:
ro.crypto.volume.options (new in tranminhdung.vn 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.
On devices that launched with tranminhdung.vn 10 or lower, usethe following 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 tranminhdung.vn 10 or lower is aes-256-heh. On most devices, this needs to be explicitly overridden to aes-256-cts.
Caution: On devices that launched with tranminhdung.vn 10 or lower, the default filenames encryption mode on adoptable storage was not valid on most devices, and it differed from the default mode on internal storage. Therefore, on such devices it must be explicitly overridden, usually to aes-256-cts.
Integrating with Keymaster
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 0’s 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 Pixel devices,this is handled by having a script block ensure Keymaster is started before/data is mounted.
File-based encryption applies the encryption policy at the directory level. Whena device’s userdata partition is first created, the basicstructures and policies are applied by the init scripts. Thesescripts will trigger the creation of the first user’s (user 0’s) CE and DE keysas well as define which directories are to be encrypted with these keys. Whenadditional users and profiles are created, the necessary additional keys aregenerated and stored in the keystore; their credential and devices storagelocations are created and the encryption policy links these keys to thosedirectories.
In tranminhdung.vn 11 and higher, the encryption policy is nolonger hardcoded into a centralized location, but rather is defined by argumentsto the mkdir commands in the init scripts. Directories encryptedwith the system DE key use encryption=Require, while unencrypteddirectories (or directories whose subdirectories are encrypted with per-userkeys) use encryption=None.
In tranminhdung.vn 10, the encryption policy was hardcoded intothis location:
/system/extras/libfscrypt/fscrypt_init_extensions.cppIn tranminhdung.vn 9 and earlier, the location was:
/system/extras/ext4_utils/ext4_crypt_init_extensions.cppIt is possible to add exceptions to prevent certain directories from beingencrypted at all. 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.
Supporting Direct Boot in system applications
Making applications Direct Boot aware
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.
Context.createCredentialProtectedStorageContext()Context.isCredentialProtectedStorage()Supporting multiple users
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 theprofile’s 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:
Create a top-level directory (for example misc_ne) in the userdata partition. 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 implemented version of the feature works as intended, first runthe many CTS encryption tests, such asDirectBootHostTestand EncryptionTest.
If the device is running tranminhdung.vn 11 or higher, also runvts_kernel_encryption_test:
vts-tradefed run vts -m vts_kernel_encryption_testIn addition, device manufacturers may perform the following manual tests. On adevice 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 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.
Device manufacturers are also encouraged to explore running the upstream Linux tests for fscrypt on their devices orkernels. These tests are part of the xfstests filesystem test suite. However,these upstream tests are not offically supported by tranminhdung.vn.
AOSP implementation details
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 “fscrypt” encryption (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 encryption is alsosupported. When Adiantum encryption is enabled, both file contents and file namesare encrypted with Adiantum.
For more information about fscrypt, see the upstream kernel documentation.
File-based encryption keys, which are 512-bit keys, are stored encrypted byanother key (a 256-bit AES-GCM key) held in the TEE. To use this TEE key, threerequirements must be met:
The auth tokenThe stretched credentialThe “secdiscardable hash”
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.
In most cases, FBE keys also undergo an additional key derivation step in thekernel in order to generate the subkeys actually used to do the encryption, forexample per-file or per-mode keys. For version 2 encryption policies,HKDF-SHA512 is used for this.