Offline attacks¶

Provided that userspace chooses a strong encryption key, fscrypt protects the confidentiality of file contents and filenames in the event of a single point-in-time permanent offline compromise of the block device content. fscrypt does not protect the confidentiality of non-filename metadata, e.g. file sizes, file permissions, file timestamps, and extended attributes. Also, the existence and location of holes (unallocated blocks which logically contain all zeroes) in files is not protected.

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

Online attacks¶

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

Master Keys¶

Each encrypted directory tree is protected by a master key. Master keys can be up to 64 bytes long, and must be at least as long as the greater of the security strength of the contents and filenames encryption modes being used. For example, if any AES-256 mode is used, the master key must be at least 256 bits, i.e. 32 bytes. A stricter requirement applies if the key is used by a v1 encryption policy and AES-256-XTS is used; such keys must be 64 bytes.

To “unlock” an encrypted directory tree, userspace must provide the appropriate master key. There can be any number of master keys, each of which protects any number of directory trees on any number of filesystems.

Master keys must be real cryptographic keys, i.e. indistinguishable from random bytestrings of the same length. This implies that users must not directly use a password as a master key, zero-pad a shorter key, or repeat a shorter key. Security cannot be guaranteed if userspace makes any such error, as the cryptographic proofs and analysis would no longer apply.

Instead, users should generate master keys either using a cryptographically 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 such as a passphrase, it is critical that a KDF designed for this purpose be used, such as scrypt, PBKDF2, or Argon2.

Key derivation function¶

With one exception, fscrypt never uses the master key(s) for encryption 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 whether the key is used for v1 encryption policies or for v2 encryption policies. Users must not use the same key for both v1 and v2 encryption policies. (No real-world attack is currently known on this specific case of key reuse, but its security cannot be guaranteed since the cryptographic proofs and analysis would no longer apply.)

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

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

HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because HKDF is more flexible, is nonreversible, and evenly distributes entropy from the master key. HKDF is also standardized and widely used 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 two files doesn’t map to the same ciphertext, or vice versa. In most cases, fscrypt does this by deriving per-file keys. When a new encrypted inode (regular file, directory, or symlink) is created, fscrypt randomly generates a 16-byte nonce and stores it in the inode’s encryption xattr. Then, it uses a KDF (as described in Key derivation function) to derive the file’s key from the master key and nonce.

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

DIRECT_KEY policies¶

The Adiantum encryption mode (see Encryption modes and usage) is suitable for both contents and filenames encryption, and it accepts long IVs --- long enough to hold both an 8-byte data unit index and a 16-byte per-file nonce. Also, the overhead of each Adiantum key is greater 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 enabled this 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 is included in the IV. Moreover:

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

• For v2 encryption policies, the encryption is done with a per-mode key derived using the KDF. Users may use the same master key for other v2 encryption policies. However, using a distinct master key for each policy is still the best practice and normal usage.

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 mode number, and filesystem UUID. This normally results in all files protected by the same master key sharing a single contents encryption key and a single filenames encryption key. To still encrypt different files’ 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 hardware compliant with the UFS standard, which supports only 64 IV bits per I/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 for IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the SipHash key is derived from the master key) and added to the file data unit index mod 2^32 to produce a 32-bit IV.

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

IV_INO_LBLK_32 is supported only when the filesystem block size is equal to the page size.

Key identifiers¶

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

Dirhash keys¶

For directories that are indexed using a secret-keyed dirhash over the plaintext filenames, the KDF is also used to derive a 128-bit SipHash-2-4 key per directory in order to hash filenames. This works just like deriving a per-file encryption key, except that a different KDF 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 of the difficulty of dealing with ciphertext expansion. Therefore, contents encryption uses a block cipher in XTS mode or CBC-ESSIV mode, or a wide-block cipher. Filenames encryption uses a block cipher in CBC-CTS mode or a wide-block cipher.

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

The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that upgrades the filenames encryption to use a wide-block cipher. (A wide-block cipher, also called a tweakable super-pseudorandom permutation, has the property that changing one bit scrambles the entire result.) As described in Filenames encryption, a wide-block cipher is the ideal mode for the problem domain, though CBC-CTS is the “least bad” choice among the alternatives. For more information about HCTR2, see the HCTR2 paper.

Adiantum is recommended on systems where AES is too slow due to lack of hardware acceleration for AES. Adiantum is a wide-block cipher that uses XChaCha12 and AES-256 as its underlying components. Most of the work is done by XChaCha12, which is much faster than AES when AES acceleration is unavailable. For more information about Adiantum, see the Adiantum paper.

The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair was added to try to provide a more efficient option for systems that lack AES instructions in the CPU but do have a non-inline crypto engine such as CAAM or CESA that supports AES-CBC (and not AES-XTS). This is deprecated. It has been 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 they receive limited security review compared to the usual choices such as AES and ChaCha. They also don’t bring much new to the table. It is suggested to only use these ciphers where their use is mandated.

Kernel config options¶

Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in only the basic support from the crypto API needed to use AES-256-XTS and AES-256-CBC-CTS encryption. For optimal performance, it is strongly recommended to also enable any available platform-specific kconfig options that provide acceleration for the algorithm(s) you wish to use. Support for any “non-default” encryption modes typically requires extra kconfig options as well.

Below, some relevant options are listed by encryption mode. Note, acceleration options not listed below may be available for your platform; refer to the kconfig menus. File contents encryption can also be configured to use inline encryption hardware instead of the kernel crypto API (see Inline encryption support); in that case, the file contents mode doesn’t need to supported in the kernel crypto API, 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

    • x86: CONFIG_CRYPTO_AES_NI_INTEL

• Adiantum

  • Mandatory:

    • CONFIG_CRYPTO_ADIANTUM

• 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 “data units”. Each data unit is encrypted independently. The IV for each data unit incorporates the zero-based index of the data unit within the file. This ensures that each data unit within a file is encrypted differently, which is essential to prevent leaking information.

Note: the encryption depending on the offset into the file means that operations like “collapse range” and “insert range” that rearrange the extent 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 UBIFS work. A file’s data units are all the same size; the last data unit is zero-padded if needed. By default, the data unit size is equal to the filesystem block size. On some filesystems, users can select a sub-block data unit size via the log2_data_unit_size field of the encryption policy; see FS_IOC_SET_ENCRYPTION_POLICY.

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

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

As mentioned in Key hierarchy, the default encryption setting uses per-file keys. In this case, the IV for each data unit is simply the index of the data unit in the file. However, users can select an encryption setting that does not use per-file keys. For these, some kind of file identifier is incorporated into the IVs as follows:

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

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

• With IV_INO_LBLK_32 policies, the file’s inode number is hashed and added to the data unit index. The resulting value is truncated to 32 bits and placed in bits 0-31 of the IV. This setting is only allowed 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, an ESSIV layer is automatically included. In this case, before the IV is passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256 key is the SHA-256 hash of the file’s contents encryption key.

Filenames encryption¶

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

However, each encrypted directory still uses a unique key, or alternatively has the file’s nonce (for DIRECT_KEY policies) or inode number (for IV_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 a common prefix at least as long as the cipher block size (16 bytes for AES), the corresponding encrypted filenames will also share a common prefix. This is undesirable. Adiantum and HCTR2 do not have this weakness, as they are wide-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 before being encrypted. In addition, to reduce leakage of filename lengths via their ciphertexts, all filenames are NUL-padded to the next 4, 8, 16, or 32-byte boundary (configurable). 32 is recommended since this provides the best confidentiality, at the cost of making directory entries consume slightly more space. Note that since NUL (\0) is not otherwise a valid character in filenames, the padding will never produce duplicate plaintexts.

Symbolic link targets are considered a type of filename and are encrypted in the same way as filenames in directory entries, except that 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     8
struct 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     16
struct 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¶

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 deprecated ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly generated 16-byte value stored in the filesystem superblock. This value is intended to used as a salt when deriving an encryption key from a passphrase or other low-entropy user credential.

FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to generate 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 the encryption is being done correctly. It is not needed for normal use of 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        2

struct 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            64

struct 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 by FS_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 added or removed by non-root users.

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

Before using these ioctls, read the Online attacks section for a discussion 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, and symlinks 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 encryption policy (i.e. different key, modes, or flags), cannot be renamed or linked into an encrypted directory; see Encryption policy enforcement. Attempts to do so will fail with EXDEV. However, encrypted files can be renamed within an encrypted directory, or into an unencrypted directory.

  Note: “moving” an unencrypted file into an encrypted directory, e.g. with the mv program, is implemented in userspace by a copy followed by a delete. Be aware that the original unencrypted data may remain recoverable from free space on the disk; prefer to keep all files encrypted from the very beginning. The shred program may be used to overwrite the source files but isn’t guaranteed to be effective on all filesystems and storage devices.

• Direct I/O is supported on encrypted files only under some circumstances. For details, see Direct I/O support.

• The fallocate operations FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will fail with EOPNOTSUPP.

• Online defragmentation of encrypted files is not supported. The EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with EOPNOTSUPP.

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

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

• Encrypted files cannot be used directly as swap files. To swap to an encrypted file, set up a loopback device on top of it. Alternatively, encrypted swap can use a dm-crypt device.

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

Note that mmap is supported. This is possible because the pagecache for an encrypted file contains the plaintext, not the ciphertext.

Without the key¶

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

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

• Directories may be listed, in which case the filenames will be listed in an encoded form derived from their ciphertext. The current encoding algorithm is described in Filename hashing and encoding. The algorithm is subject to change, but it is guaranteed that the presented filenames will be no longer than NAME_MAX bytes, will not contain the / or \0 characters, and will uniquely identify directory entries.

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

• Files may be deleted. That is, nondirectory files may be deleted with unlink() as usual, and empty directories may be deleted with rmdir() as usual. Therefore, rm and rm -r will work as expected.

• Symlink targets may be read and followed, but they will be presented in encrypted form, similar to filenames in directories. Hence, they are 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 any regular file operations that require a file descriptor, such as read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.

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

It is not currently possible to backup and restore encrypted files without the encryption key. This would require special APIs which have not yet been implemented.

Hardware-wrapped keys¶

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

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

fscrypt supports hardware-wrapped keys by allowing the fscrypt master keys to be hardware-wrapped keys as an alternative to raw keys. To add a hardware-wrapped key with FS_IOC_ADD_ENCRYPTION_KEY, userspace must specify FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED in the flags field of struct fscrypt_add_key_arg and also in the flags field of struct fscrypt_provisioning_key_payload when applicable. The key must be in ephemerally-wrapped form, not long-term wrapped form.

Some limitations apply. First, files protected by a hardware-wrapped key are tied to the system’s inline encryption hardware. Therefore they 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 with IV_INO_LBLK_64 policies and IV_INO_LBLK_32 policies, as it assumes that there is just one file contents encryption key per fscrypt master key rather than one per file. Future work may address this limitation by passing per-file nonces down the storage stack to allow the hardware to derive per-file keys.

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

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

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

Encryption context¶

An encryption policy is represented on-disk by struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to individual filesystems to decide where to store it, but normally it would be stored in a hidden extended attribute. It should not be exposed by the xattr-related system calls such as getxattr() and setxattr() because of the special semantics of the encryption xattr. (In particular, there would be much confusion if an encryption policy were to be added to or removed from anything other than an empty directory.) These structs are defined as follows:

#define FSCRYPT_FILE_NONCE_SIZE 16

#define FSCRYPT_KEY_DESCRIPTOR_SIZE  8
struct 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  16
struct 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 corresponding policy structs (see Setting an encryption policy), except that the context structs also contain a nonce. The nonce is randomly generated by the kernel and is used as KDF input or as a tweak to cause different files to be encrypted differently; see Per-file encryption keys and DIRECT_KEY policies.

Data path changes¶

The block-based filesystems that support fscrypt, such as ext4 and f2fs, use blk-crypto (Inline Encryption) to implement file contents encryption and decryption. With blk-crypto, the filesystem assigns an encryption context to each I/O request it issues to the contents of an encrypted file. The encryption (for writes) or decryption (for reads) is handled by the block layer transparently to the filesystem, using either the CPU or inline encryption hardware.

Non-block-based filesystems can’t use blk-crypto, so they make the calls to the cryptographic algorithms at the filesystem layer instead.

Regardless of the layer in which they occur (blk-crypto-fallback or the filesystem), for CPU-based encryption and decryption of file contents:

• For reads, the ciphertext data is read from the storage backend (block device, network, UBI device, etc.) into the destination buffers, then decrypted in-place. The destination buffers are pagecache folios for buffered reads, or application-provided buffers for direct reads. In either case, the filesystem reports success only after decryption has successfully completed.

• For writes, the plaintext data is encrypted from the source buffers (which cannot be modified) into bounce buffers. Then, the ciphertext in the bounce buffers is written to the storage backend.

  The source buffers are usually pagecache folios for buffered writes, or application-provided buffers for direct writes. There are also some cases (all files on UBIFS, and compressed files on f2fs) where the filesystem already uses bounce buffers for writes for other reasons; in these cases the source plaintext data is already in bounce buffers. UBIFS optimizes this case by encrypting the data in-place in its existing bounce buffers.

When inline encryption hardware is used instead of the CPU, reads from the storage backend logically return plaintext data, and writes accept plaintext data. In that case the flow is simplified: there’s no scheduling of decryption work, and no bounce buffers are used.

Filename hashing and encoding¶

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

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

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

However, for very long filenames, base64url encoding would cause the filename length to exceed NAME_MAX. To prevent this, readdir() actually presents long filenames in an abbreviated form which encodes a strong “hash” of the ciphertext filename, along with the optional filesystem-specific hash(es) needed for directory lookups. This allows the filesystem to still, with a high degree of confidence, map the filename given in ->lookup() back to a particular directory entry that was previously listed by readdir(). See struct fscrypt_nokey_name in the source for more details.

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