Offline attacks¶

Provided that userspace chooses a strong encryption key, fscryptprotects the confidentiality of file contents and filenames in theevent of a single point-in-time permanent offline compromise of theblock device content. fscrypt does not protect the confidentiality ofnon-filename metadata, e.g. file sizes, file permissions, filetimestamps, and extended attributes. Also, the existence and locationof holes (unallocated blocks which logically contain all zeroes) infiles is not protected.

fscrypt is not guaranteed to protect confidentiality or authenticityif an attacker is able to manipulate the filesystem offline prior toan authorized user later accessing the filesystem.

Online attacks¶

fscrypt (and storage encryption in general) can only provide limitedprotection against online attacks. In detail:

Master Keys¶

Each encrypted directory tree is protected by amaster key. Masterkeys can be up to 64 bytes long, and must be at least as long as thegreater of the security strength of the contents and filenamesencryption modes being used. For example, if any AES-256 mode isused, the master key must be at least 256 bits, i.e. 32 bytes. Astricter requirement applies if the key is used by a v1 encryptionpolicy and AES-256-XTS is used; such keys must be 64 bytes.

To “unlock” an encrypted directory tree, userspace must provide theappropriate master key. There can be any number of master keys, eachof which protects any number of directory trees on any number offilesystems.

Master keys must be real cryptographic keys, i.e. indistinguishablefrom random bytestrings of the same length. This implies that usersmust not directly use a password as a master key, zero-pad ashorter key, or repeat a shorter key. Security cannot be guaranteedif userspace makes any such error, as the cryptographic proofs andanalysis would no longer apply.

Instead, users should generate master keys either using acryptographically secure random number generator, or by using a KDF(Key Derivation Function). The kernel does not do any key stretching;therefore, if userspace derives the key from a low-entropy secret suchas a passphrase, it is critical that a KDF designed for this purposebe used, such as scrypt, PBKDF2, or Argon2.

Key derivation function¶

With one exception, fscrypt never uses the master key(s) forencryption directly. Instead, they are only used as input to a KDF(Key Derivation Function) to derive the actual keys.

The KDF used for a particular master key differs depending on whetherthe key is used for v1 encryption policies or for v2 encryptionpolicies. Usersmust not use the same key for both v1 and v2encryption policies. (No real-world attack is currently known on thisspecific case of key reuse, but its security cannot be guaranteedsince the cryptographic proofs and analysis would no longer apply.)

For v1 encryption policies, the KDF only supports deriving per-fileencryption keys. It works by encrypting the master key withAES-128-ECB, using the file’s 16-byte nonce as the AES key. Theresulting ciphertext is used as the derived key. If the ciphertext islonger than needed, then it is truncated to the needed length.

For v2 encryption policies, the KDF is HKDF-SHA512. The master key ispassed as the “input keying material”, no salt is used, and a distinct“application-specific information string” is used for each distinctkey to be derived. For example, when a per-file encryption key isderived, the application-specific information string is the file’snonce prefixed with “fscrypt\0” and a context byte. Differentcontext bytes are used for other types of derived keys.

HKDF-SHA512 is preferred to the original AES-128-ECB based KDF becauseHKDF is more flexible, is nonreversible, and evenly distributesentropy from the master key. HKDF is also standardized and widelyused by other software, whereas the AES-128-ECB based KDF is ad-hoc.

Per-file encryption keys¶

Since each master key can protect many files, it is necessary to“tweak” the encryption of each file so that the same plaintext in twofiles doesn’t map to the same ciphertext, or vice versa. In mostcases, fscrypt does this by deriving per-file keys. When a newencrypted inode (regular file, directory, or symlink) is created,fscrypt randomly generates a 16-byte nonce and stores it in theinode’s encryption xattr. Then, it uses a KDF (as described inKeyderivation function) to derive the file’s key from the master keyand nonce.

Key derivation was chosen over key wrapping because wrapped keys wouldrequire larger xattrs which would be less likely to fit in-line in thefilesystem’s inode table, and there didn’t appear to be anysignificant advantages to key wrapping. In particular, currentlythere is no requirement to support unlocking a file with multiplealternative master keys or to support rotating master keys. Instead,the master keys may be wrapped in userspace, e.g. as is done by thefscrypt tool.

DIRECT_KEY policies¶

The Adiantum encryption mode (seeEncryption modes and usage) issuitable for both contents and filenames encryption, and it acceptslong IVs --- long enough to hold both an 8-byte data unit index and a16-byte per-file nonce. Also, the overhead of each Adiantum key isgreater than that of an AES-256-XTS key.

Therefore, to improve performance and save memory, for Adiantum a“direct key” configuration is supported. When the user has enabledthis by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,per-file encryption keys are not used. Instead, whenever any data(contents or filenames) is encrypted, the file’s 16-byte nonce isincluded in the IV. Moreover:

• For v1 encryption policies, the encryption is done directly with themaster key. Because of this, usersmust not use the same masterkey for any other purpose, even for other v1 policies.

• For v2 encryption policies, the encryption is done with a per-modekey derived using the KDF. Users may use the same master key forother v2 encryption policies.

IV_INO_LBLK_64 policies¶

When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy,the encryption keys are derived from the master key, encryption modenumber, and filesystem UUID. This normally results in all filesprotected by the same master key sharing a single contents encryptionkey and a single filenames encryption key. To still encrypt differentfiles’ data differently, inode numbers are included in the IVs.Consequently, shrinking the filesystem may not be allowed.

This format is optimized for use with inline encryption hardwarecompliant with the UFS standard, which supports only 64 IV bits perI/O request and may have only a small number of keyslots.

IV_INO_LBLK_32 policies¶

IV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that forIV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where theSipHash key is derived from the master key) and added to the file dataunit index mod 2^32 to produce a 32-bit IV.

This format is optimized for use with inline encryption hardwarecompliant with the eMMC v5.2 standard, which supports only 32 IV bitsper I/O request and may have only a small number of keyslots. Thisformat results in some level of IV reuse, so it should only be usedwhen necessary due to hardware limitations.

Key identifiers¶

For master keys used for v2 encryption policies, a unique 16-byte “keyidentifier” is also derived using the KDF. This value is stored inthe clear, since it is needed to reliably identify the key itself.

Dirhash keys¶

For directories that are indexed using a secret-keyed dirhash over theplaintext filenames, the KDF is also used to derive a 128-bitSipHash-2-4 key per directory in order to hash filenames. This worksjust like deriving a per-file encryption key, except that a differentKDF context is used. Currently, only casefolded (“case-insensitive”)encrypted directories use this style of hashing.

Supported modes¶

Currently, the following pairs of encryption modes are supported:

• AES-256-XTS for contents and AES-256-CBC-CTS for filenames

• AES-256-XTS for contents and AES-256-HCTR2 for filenames

• Adiantum for both contents and filenames

• AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames

• SM4-XTS for contents and SM4-CBC-CTS for filenames

Note: in the API, “CBC” means CBC-ESSIV, and “CTS” means CBC-CTS.So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.

Authenticated encryption modes are not currently supported because ofthe difficulty of dealing with ciphertext expansion. Therefore,contents encryption uses a block cipher inXTS mode orCBC-ESSIV mode,or a wide-block cipher. Filenames encryption uses ablock cipher inCBC-CTS mode or a wide-blockcipher.

The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default.It is also the only option that isguaranteed to always be supportedif the kernel supports fscrypt at all; seeKernel config options.

The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice thatupgrades the filenames encryption to use a wide-block cipher. (Awide-block cipher, also called a tweakable super-pseudorandompermutation, has the property that changing one bit scrambles theentire result.) As described inFilenames encryption, a wide-blockcipher is the ideal mode for the problem domain, though CBC-CTS is the“least bad” choice among the alternatives. For more information aboutHCTR2, seethe HCTR2 paper.

Adiantum is recommended on systems where AES is too slow due to lackof hardware acceleration for AES. Adiantum is a wide-block cipherthat uses XChaCha12 and AES-256 as its underlying components. Most ofthe work is done by XChaCha12, which is much faster than AES when AESacceleration is unavailable. For more information about Adiantum, seethe Adiantum paper.

The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair was added to try toprovide a more efficient option for systems that lack AES instructionsin the CPU but do have a non-inline crypto engine such as CAAM or CESAthat supports AES-CBC (and not AES-XTS). This is deprecated. It hasbeen shown that just doing AES on the CPU is actually faster.Moreover, Adiantum is faster still and is recommended on such systems.

The remaining mode pairs are the “national pride ciphers”:

• (SM4-XTS, SM4-CBC-CTS)

Generally speaking, these ciphers aren’t “bad” per se, but theyreceive limited security review compared to the usual choices such asAES and ChaCha. They also don’t bring much new to the table. It issuggested to only use these ciphers where their use is mandated.

Kernel config options¶

Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls inonly the basic support from the crypto API needed to use AES-256-XTSand AES-256-CBC-CTS encryption. For optimal performance, it isstrongly recommended to also enable any available platform-specifickconfig options that provide acceleration for the algorithm(s) youwish to use. Support for any “non-default” encryption modes typicallyrequires extra kconfig options as well.

Below, some relevant options are listed by encryption mode. Note,acceleration options not listed below may be available for yourplatform; refer to the kconfig menus. File contents encryption canalso be configured to use inline encryption hardware instead of thekernel crypto API (seeInline encryption support); in that case,the file contents mode doesn’t need to supported in the kernel cryptoAPI, but the filenames mode still does.

• AES-256-XTS and AES-256-CBC-CTS

  • Recommended:

    • arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK

    • x86: CONFIG_CRYPTO_AES_NI_INTEL

• AES-256-HCTR2

  • Mandatory:

    • CONFIG_CRYPTO_HCTR2

  • Recommended:

    • arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK

    • arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE

    • x86: CONFIG_CRYPTO_AES_NI_INTEL

    • x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI

• Adiantum

  • Mandatory:

    • CONFIG_CRYPTO_ADIANTUM

  • Recommended:

    • arm32: CONFIG_CRYPTO_NHPOLY1305_NEON

    • arm64: CONFIG_CRYPTO_NHPOLY1305_NEON

    • x86: CONFIG_CRYPTO_NHPOLY1305_SSE2

    • x86: CONFIG_CRYPTO_NHPOLY1305_AVX2

• AES-128-CBC-ESSIV and AES-128-CBC-CTS:

  • Mandatory:

    • CONFIG_CRYPTO_ESSIV

    • CONFIG_CRYPTO_SHA256 or another SHA-256 implementation

  • Recommended:

    • AES-CBC acceleration

Contents encryption¶

For contents encryption, each file’s contents is divided into “dataunits”. Each data unit is encrypted independently. The IV for eachdata unit incorporates the zero-based index of the data unit withinthe file. This ensures that each data unit within a file is encrypteddifferently, which is essential to prevent leaking information.

Note: the encryption depending on the offset into the file means thatoperations like “collapse range” and “insert range” that rearrange theextent mapping of files are not supported on encrypted files.

There are two cases for the sizes of the data units:

• Fixed-size data units. This is how all filesystems other than UBIFSwork. A file’s data units are all the same size; the last data unitis zero-padded if needed. By default, the data unit size is equalto the filesystem block size. On some filesystems, users can selecta sub-block data unit size via thelog2_data_unit_size field ofthe encryption policy; seeFS_IOC_SET_ENCRYPTION_POLICY.

• Variable-size data units. This is what UBIFS does. Each “UBIFSdata node” is treated as a crypto data unit. Each contains variablelength, possibly compressed data, zero-padded to the next 16-byteboundary. Users cannot select a sub-block data unit size on UBIFS.

In the case of compression + encryption, the compressed data isencrypted. UBIFS compression works as described above. f2fscompression works a bit differently; it compresses a number offilesystem blocks into a smaller number of filesystem blocks.Therefore a f2fs-compressed file still uses fixed-size data units, andit is encrypted in a similar way to a file containing holes.

As mentioned inKey hierarchy, the default encryption setting usesper-file keys. In this case, the IV for each data unit is simply theindex of the data unit in the file. However, users can select anencryption setting that does not use per-file keys. For these, somekind of file identifier is incorporated into the IVs as follows:

• WithDIRECT_KEY policies, the data unit index is placed in bits0-63 of the IV, and the file’s nonce is placed in bits 64-191.

• WithIV_INO_LBLK_64 policies, the data unit index is placed inbits 0-31 of the IV, and the file’s inode number is placed in bits32-63. This setting is only allowed when data unit indices andinode numbers fit in 32 bits.

• WithIV_INO_LBLK_32 policies, the file’s inode number is hashedand added to the data unit index. The resulting value is truncatedto 32 bits and placed in bits 0-31 of the IV. This setting is onlyallowed when data unit indices and inode numbers fit in 32 bits.

The byte order of the IV is always little endian.

If the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, anESSIV layer is automatically included. In this case, before the IV ispassed to AES-128-CBC, it is encrypted with AES-256 where the AES-256key is the SHA-256 hash of the file’s contents encryption key.

Filenames encryption¶

For filenames, each full filename is encrypted at once. Because ofthe requirements to retain support for efficient directory lookups andfilenames of up to 255 bytes, the same IV is used for every filenamein a directory.

However, each encrypted directory still uses a unique key, oralternatively has the file’s nonce (forDIRECT_KEY policies) orinode number (forIV_INO_LBLK_64 policies) included in the IVs.Thus, IV reuse is limited to within a single directory.

With CBC-CTS, the IV reuse means that when the plaintext filenames share acommon prefix at least as long as the cipher block size (16 bytes for AES), thecorresponding encrypted filenames will also share a common prefix. This isundesirable. Adiantum and HCTR2 do not have this weakness, as they arewide-block encryption modes.

All supported filenames encryption modes accept any plaintext length>= 16 bytes; cipher block alignment is not required. However,filenames shorter than 16 bytes are NUL-padded to 16 bytes beforebeing encrypted. In addition, to reduce leakage of filename lengthsvia their ciphertexts, all filenames are NUL-padded to the next 4, 8,16, or 32-byte boundary (configurable). 32 is recommended since thisprovides the best confidentiality, at the cost of making directoryentries consume slightly more space. Note that since NUL (\0) isnot otherwise a valid character in filenames, the padding will neverproduce duplicate plaintexts.

Symbolic link targets are considered a type of filename and areencrypted in the same way as filenames in directory entries, exceptthat IV reuse is not a problem as each symlink has its own inode.

Setting an encryption policy¶

#define FSCRYPT_POLICY_V1               0#define FSCRYPT_KEY_DESCRIPTOR_SIZE     8struct fscrypt_policy_v1 {        __u8 version;        __u8 contents_encryption_mode;        __u8 filenames_encryption_mode;        __u8 flags;        __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];};#define fscrypt_policy  fscrypt_policy_v1#define FSCRYPT_POLICY_V2               2#define FSCRYPT_KEY_IDENTIFIER_SIZE     16struct fscrypt_policy_v2 {        __u8 version;        __u8 contents_encryption_mode;        __u8 filenames_encryption_mode;        __u8 flags;        __u8 log2_data_unit_size;        __u8 __reserved[3];        __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];};

Getting an encryption policy¶

Two ioctls are available to get a file’s encryption policy:

• FS_IOC_GET_ENCRYPTION_POLICY_EX

• FS_IOC_GET_ENCRYPTION_POLICY

The extended (_EX) version of the ioctl is more general and isrecommended to use when possible. However, on older kernels only theoriginal ioctl is available. Applications should try the extendedversion, and if it fails with ENOTTY fall back to the originalversion.

struct fscrypt_get_policy_ex_arg {        __u64 policy_size; /* input/output */        union {                __u8 version;                struct fscrypt_policy_v1 v1;                struct fscrypt_policy_v2 v2;        } policy; /* output */};

Getting the per-filesystem salt¶

Some filesystems, such as ext4 and F2FS, also support the deprecatedioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomlygenerated 16-byte value stored in the filesystem superblock. Thisvalue is intended to used as a salt when deriving an encryption keyfrom a passphrase or other low-entropy user credential.

FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer togenerate and manage any needed salt(s) in userspace.

Getting a file’s encryption nonce¶

Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported.On encrypted files and directories it gets the inode’s 16-byte nonce.On unencrypted files and directories, it fails with ENODATA.

This ioctl can be useful for automated tests which verify that theencryption is being done correctly. It is not needed for normal useof fscrypt.

Adding keys¶

struct fscrypt_add_key_arg {        struct fscrypt_key_specifier key_spec;        __u32 raw_size;        __u32 key_id;#define FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED 0x00000001        __u32 flags;        __u32 __reserved[7];        __u8 raw[];};#define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR        1#define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER        2struct fscrypt_key_specifier {        __u32 type;     /* one of FSCRYPT_KEY_SPEC_TYPE_* */        __u32 __reserved;        union {                __u8 __reserved[32]; /* reserve some extra space */                __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];                __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];        } u;};struct fscrypt_provisioning_key_payload {        __u32 type;        __u32 flags;        __u8 raw[];};

#define FSCRYPT_MAX_KEY_SIZE            64struct fscrypt_key {        __u32 mode;        __u8 raw[FSCRYPT_MAX_KEY_SIZE];        __u32 size;};

Removing keys¶

Two ioctls are available for removing a key that was added byFS_IOC_ADD_ENCRYPTION_KEY:

• FS_IOC_REMOVE_ENCRYPTION_KEY

• FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS

These two ioctls differ only in cases where v2 policy keys are addedor removed by non-root users.

These ioctls don’t work on keys that were added via the legacyprocess-subscribed keyrings mechanism.

Before using these ioctls, read theOnline attacks section for adiscussion of the security goals and limitations of these ioctls.

struct fscrypt_remove_key_arg {        struct fscrypt_key_specifier key_spec;#define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY      0x00000001#define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS     0x00000002        __u32 removal_status_flags;     /* output */        __u32 __reserved[5];};

Getting key status¶

struct fscrypt_get_key_status_arg {        /* input */        struct fscrypt_key_specifier key_spec;        __u32 __reserved[6];        /* output */#define FSCRYPT_KEY_STATUS_ABSENT               1#define FSCRYPT_KEY_STATUS_PRESENT              2#define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3        __u32 status;#define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF   0x00000001        __u32 status_flags;        __u32 user_count;        __u32 __out_reserved[13];};

With the key¶

With the encryption key, encrypted regular files, directories, andsymlinks behave very similarly to their unencrypted counterparts ---after all, the encryption is intended to be transparent. However,astute users may notice some differences in behavior:

• Unencrypted files, or files encrypted with a different encryptionpolicy (i.e. different key, modes, or flags), cannot be renamed orlinked into an encrypted directory; seeEncryption policyenforcement. Attempts to do so will fail with EXDEV. However,encrypted files can be renamed within an encrypted directory, orinto an unencrypted directory.

  Note: “moving” an unencrypted file into an encrypted directory, e.g.with themv program, is implemented in userspace by a copyfollowed by a delete. Be aware that the original unencrypted datamay remain recoverable from free space on the disk; prefer to keepall files encrypted from the very beginning. Theshred programmay be used to overwrite the source files but isn’t guaranteed to beeffective on all filesystems and storage devices.

• Direct I/O is supported on encrypted files only under somecircumstances. For details, seeDirect I/O support.

• The fallocate operations FALLOC_FL_COLLAPSE_RANGE andFALLOC_FL_INSERT_RANGE are not supported on encrypted files and willfail with EOPNOTSUPP.

• Online defragmentation of encrypted files is not supported. TheEXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail withEOPNOTSUPP.

• The ext4 filesystem does not support data journaling with encryptedregular files. It will fall back to ordered data mode instead.

• DAX (Direct Access) is not supported on encrypted files.

• The maximum length of an encrypted symlink is 2 bytes shorter thanthe maximum length of an unencrypted symlink. For example, on anEXT4 filesystem with a 4K block size, unencrypted symlinks can be upto 4095 bytes long, while encrypted symlinks can only be up to 4093bytes long (both lengths excluding the terminating null).

Note that mmapis supported. This is possible because the pagecachefor an encrypted file contains the plaintext, not the ciphertext.

Without the key¶

Some filesystem operations may be performed on encrypted regularfiles, directories, and symlinks even before their encryption key hasbeen added, or after their encryption key has been removed:

• File metadata may be read, e.g. usingstat().

• Directories may be listed, in which case the filenames will belisted in an encoded form derived from their ciphertext. Thecurrent encoding algorithm is described inFilename hashing andencoding. The algorithm is subject to change, but it isguaranteed that the presented filenames will be no longer thanNAME_MAX bytes, will not contain the/ or\0 characters, andwill uniquely identify directory entries.

  The. and.. directory entries are special. They are alwayspresent and are not encrypted or encoded.

• Files may be deleted. That is, nondirectory files may be deletedwithunlink() as usual, and empty directories may be deleted withrmdir() as usual. Therefore,rm andrm-r will work asexpected.

• Symlink targets may be read and followed, but they will be presentedin encrypted form, similar to filenames in directories. Hence, theyare unlikely to point to anywhere useful.

Without the key, regular files cannot be opened or truncated.Attempts to do so will fail with ENOKEY. This implies that anyregular file operations that require a file descriptor, such asread(), write(), mmap(),fallocate(), and ioctl(), are also forbidden.

Also without the key, files of any type (including directories) cannotbe created or linked into an encrypted directory, nor can a name in anencrypted directory be the source or target of a rename, nor can anO_TMPFILE temporary file be created in an encrypted directory. Allsuch operations will fail with ENOKEY.

It is not currently possible to backup and restore encrypted fileswithout the encryption key. This would require special APIs whichhave not yet been implemented.

Hardware-wrapped keys¶

fscrypt supports usinghardware-wrapped keys when the inlineencryption hardware supports it. Such keys are only present in kernelmemory in wrapped (encrypted) form; they can only be unwrapped(decrypted) by the inline encryption hardware and are temporally boundto the current boot. This prevents the keys from being compromised ifkernel memory is leaked. This is done without limiting the number ofkeys that can be used and while still allowing the execution ofcryptographic tasks that are tied to the same key but can’t use inlineencryption hardware, e.g. filenames encryption.

Note that hardware-wrapped keys aren’t specific to fscrypt; they are ablock layer feature (part ofblk-crypto). For more details abouthardware-wrapped keys, see the block layer documentation atDocumentation/block/inline-encryption.rst. The rest of this section just focuses onthe details of how fscrypt can use hardware-wrapped keys.

fscrypt supports hardware-wrapped keys by allowing the fscrypt masterkeys to be hardware-wrapped keys as an alternative to raw keys. Toadd a hardware-wrapped key withFS_IOC_ADD_ENCRYPTION_KEY,userspace must specify FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED in theflags field ofstructfscrypt_add_key_arg and also in theflags field ofstructfscrypt_provisioning_key_payload whenapplicable. The key must be in ephemerally-wrapped form, notlong-term wrapped form.

Some limitations apply. First, files protected by a hardware-wrappedkey are tied to the system’s inline encryption hardware. Thereforethey can only be accessed when the “inlinecrypt” mount option is used,and they can’t be included in portable filesystem images. Second,currently the hardware-wrapped key support is only compatible withIV_INO_LBLK_64 policies andIV_INO_LBLK_32 policies, as itassumes that there is just one file contents encryption key perfscrypt master key rather than one per file. Future work may addressthis limitation by passing per-file nonces down the storage stack toallow the hardware to derive per-file keys.

Implementation-wise, to encrypt/decrypt the contents of files that areprotected by a hardware-wrapped key, fscrypt uses blk-crypto,attaching the hardware-wrapped key to the bio crypt contexts. As isthe case with raw keys, the block layer will program the key into akeyslot when it isn’t already in one. However, when programming ahardware-wrapped key, the hardware doesn’t program the given keydirectly into a keyslot but rather unwraps it (using the hardware’sephemeral wrapping key) and derives the inline encryption key from it.The inline encryption key is the key that actually gets programmedinto a keyslot, and it is never exposed to software.

However, fscrypt doesn’t just do file contents encryption; it alsouses its master keys to derive filenames encryption keys, keyidentifiers, and sometimes some more obscure types of subkeys such asdirhash keys. So even with file contents encryption out of thepicture, fscrypt still needs a raw key to work with. To get such akey from a hardware-wrapped key, fscrypt asks the inline encryptionhardware to derive a cryptographically isolated “software secret” fromthe hardware-wrapped key. fscrypt uses this “software secret” to keyits KDF to derive all subkeys other than file contents keys.

Note that this implies that the hardware-wrapped key feature onlyprotects the file contents encryption keys. It doesn’t protect otherfscrypt subkeys such as filenames encryption keys.

Encryption context¶

An encryption policy is represented on-disk bystructfscrypt_context_v1 orstructfscrypt_context_v2. It is up toindividual filesystems to decide where to store it, but normally itwould be stored in a hidden extended attribute. It shouldnot beexposed by the xattr-related system calls such asgetxattr() andsetxattr() because of the special semantics of the encryption xattr.(In particular, there would be much confusion if an encryption policywere to be added to or removed from anything other than an emptydirectory.) These structs are defined as follows:

#define FSCRYPT_FILE_NONCE_SIZE 16#define FSCRYPT_KEY_DESCRIPTOR_SIZE  8struct fscrypt_context_v1 {        u8 version;        u8 contents_encryption_mode;        u8 filenames_encryption_mode;        u8 flags;        u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];        u8 nonce[FSCRYPT_FILE_NONCE_SIZE];};#define FSCRYPT_KEY_IDENTIFIER_SIZE  16struct fscrypt_context_v2 {        u8 version;        u8 contents_encryption_mode;        u8 filenames_encryption_mode;        u8 flags;        u8 log2_data_unit_size;        u8 __reserved[3];        u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];        u8 nonce[FSCRYPT_FILE_NONCE_SIZE];};

The context structs contain the same information as the correspondingpolicy structs (seeSetting an encryption policy), except that thecontext structs also contain a nonce. The nonce is randomly generatedby the kernel and is used as KDF input or as a tweak to causedifferent files to be encrypted differently; seePer-file encryptionkeys andDIRECT_KEY policies.

Data path changes¶

When inline encryption is used, filesystems just need to associateencryption contexts with bios to specify how the block layer or theinline encryption hardware will encrypt/decrypt the file contents.

When inline encryption isn’t used, filesystems must encrypt/decryptthe file contents themselves, as described below:

For the read path (->read_folio()) of regular files, filesystems canread the ciphertext into the page cache and decrypt it in-place. Thefolio lock must be held until decryption has finished, to prevent thefolio from becoming visible to userspace prematurely.

For the write path (->writepages()) of regular files, filesystemscannot encrypt data in-place in the page cache, since the cachedplaintext must be preserved. Instead, filesystems must encrypt into atemporary buffer or “bounce page”, then write out the temporarybuffer. Some filesystems, such as UBIFS, already use temporarybuffers regardless of encryption. Other filesystems, such as ext4 andF2FS, have to allocate bounce pages specially for encryption.

Filename hashing and encoding¶

Modern filesystems accelerate directory lookups by using indexeddirectories. An indexed directory is organized as a tree keyed byfilename hashes. When a ->lookup() is requested, the filesystemnormally hashes the filename being looked up so that it can quicklyfind the corresponding directory entry, if any.

With encryption, lookups must be supported and efficient both with andwithout the encryption key. Clearly, it would not work to hash theplaintext filenames, since the plaintext filenames are unavailablewithout the key. (Hashing the plaintext filenames would also make itimpossible for the filesystem’s fsck tool to optimize encrypteddirectories.) Instead, filesystems hash the ciphertext filenames,i.e. the bytes actually stored on-disk in the directory entries. Whenasked to do a ->lookup() with the key, the filesystem just encryptsthe user-supplied name to get the ciphertext.

Lookups without the key are more complicated. The raw ciphertext maycontain the\0 and/ characters, which are illegal infilenames. Therefore,readdir() must base64url-encode the ciphertextfor presentation. For most filenames, this works fine; on ->lookup(),the filesystem just base64url-decodes the user-supplied name to getback to the raw ciphertext.

However, for very long filenames, base64url encoding would cause thefilename length to exceed NAME_MAX. To prevent this,readdir()actually presents long filenames in an abbreviated form which encodesa strong “hash” of the ciphertext filename, along with the optionalfilesystem-specific hash(es) needed for directory lookups. Thisallows the filesystem to still, with a high degree of confidence, mapthe filename given in ->lookup() back to a particular directory entrythat was previously listed byreaddir(). Seestructfscrypt_nokey_name in the source for more details.

Note that the precise way that filenames are presented to userspacewithout the key is subject to change in the future. It is only meantas a way to temporarily present valid filenames so that commands likerm-r work as expected on encrypted directories.