1f4f864c1SEric Biggers===================================== 2f4f864c1SEric BiggersFilesystem-level encryption (fscrypt) 3f4f864c1SEric Biggers===================================== 4f4f864c1SEric Biggers 5f4f864c1SEric BiggersIntroduction 6f4f864c1SEric Biggers============ 7f4f864c1SEric Biggers 8f4f864c1SEric Biggersfscrypt is a library which filesystems can hook into to support 9f4f864c1SEric Biggerstransparent encryption of files and directories. 10f4f864c1SEric Biggers 11f4f864c1SEric BiggersNote: "fscrypt" in this document refers to the kernel-level portion, 12f4f864c1SEric Biggersimplemented in ``fs/crypto/``, as opposed to the userspace tool 13f4f864c1SEric Biggers`fscrypt <https://github.com/google/fscrypt>`_. This document only 14f4f864c1SEric Biggerscovers the kernel-level portion. For command-line examples of how to 15f4f864c1SEric Biggersuse encryption, see the documentation for the userspace tool `fscrypt 16f4f864c1SEric Biggers<https://github.com/google/fscrypt>`_. Also, it is recommended to use 17f4f864c1SEric Biggersthe fscrypt userspace tool, or other existing userspace tools such as 18f4f864c1SEric Biggers`fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key 19f4f864c1SEric Biggersmanagement system 20f4f864c1SEric Biggers<https://source.android.com/security/encryption/file-based>`_, over 21f4f864c1SEric Biggersusing the kernel's API directly. Using existing tools reduces the 22f4f864c1SEric Biggerschance of introducing your own security bugs. (Nevertheless, for 23f4f864c1SEric Biggerscompleteness this documentation covers the kernel's API anyway.) 24f4f864c1SEric Biggers 25f4f864c1SEric BiggersUnlike dm-crypt, fscrypt operates at the filesystem level rather than 26f4f864c1SEric Biggersat the block device level. This allows it to encrypt different files 27f4f864c1SEric Biggerswith different keys and to have unencrypted files on the same 28f4f864c1SEric Biggersfilesystem. This is useful for multi-user systems where each user's 29f4f864c1SEric Biggersdata-at-rest needs to be cryptographically isolated from the others. 30f4f864c1SEric BiggersHowever, except for filenames, fscrypt does not encrypt filesystem 31f4f864c1SEric Biggersmetadata. 32f4f864c1SEric Biggers 33f4f864c1SEric BiggersUnlike eCryptfs, which is a stacked filesystem, fscrypt is integrated 34f4f864c1SEric Biggersdirectly into supported filesystems --- currently ext4, F2FS, and 35f4f864c1SEric BiggersUBIFS. This allows encrypted files to be read and written without 36f4f864c1SEric Biggerscaching both the decrypted and encrypted pages in the pagecache, 37f4f864c1SEric Biggersthereby nearly halving the memory used and bringing it in line with 38f4f864c1SEric Biggersunencrypted files. Similarly, half as many dentries and inodes are 39f4f864c1SEric Biggersneeded. eCryptfs also limits encrypted filenames to 143 bytes, 40f4f864c1SEric Biggerscausing application compatibility issues; fscrypt allows the full 255 41f4f864c1SEric Biggersbytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be 42f4f864c1SEric Biggersused by unprivileged users, with no need to mount anything. 43f4f864c1SEric Biggers 44f4f864c1SEric Biggersfscrypt does not support encrypting files in-place. Instead, it 45f4f864c1SEric Biggerssupports marking an empty directory as encrypted. Then, after 46f4f864c1SEric Biggersuserspace provides the key, all regular files, directories, and 47f4f864c1SEric Biggerssymbolic links created in that directory tree are transparently 48f4f864c1SEric Biggersencrypted. 49f4f864c1SEric Biggers 50f4f864c1SEric BiggersThreat model 51f4f864c1SEric Biggers============ 52f4f864c1SEric Biggers 53f4f864c1SEric BiggersOffline attacks 54f4f864c1SEric Biggers--------------- 55f4f864c1SEric Biggers 56f4f864c1SEric BiggersProvided that userspace chooses a strong encryption key, fscrypt 57f4f864c1SEric Biggersprotects the confidentiality of file contents and filenames in the 58f4f864c1SEric Biggersevent of a single point-in-time permanent offline compromise of the 59f4f864c1SEric Biggersblock device content. fscrypt does not protect the confidentiality of 60f4f864c1SEric Biggersnon-filename metadata, e.g. file sizes, file permissions, file 61f4f864c1SEric Biggerstimestamps, and extended attributes. Also, the existence and location 62f4f864c1SEric Biggersof holes (unallocated blocks which logically contain all zeroes) in 63f4f864c1SEric Biggersfiles is not protected. 64f4f864c1SEric Biggers 65f4f864c1SEric Biggersfscrypt is not guaranteed to protect confidentiality or authenticity 66f4f864c1SEric Biggersif an attacker is able to manipulate the filesystem offline prior to 67f4f864c1SEric Biggersan authorized user later accessing the filesystem. 68f4f864c1SEric Biggers 69f4f864c1SEric BiggersOnline attacks 70f4f864c1SEric Biggers-------------- 71f4f864c1SEric Biggers 72f4f864c1SEric Biggersfscrypt (and storage encryption in general) can only provide limited 73f4f864c1SEric Biggersprotection, if any at all, against online attacks. In detail: 74f4f864c1SEric Biggers 75f4f864c1SEric Biggersfscrypt is only resistant to side-channel attacks, such as timing or 76f4f864c1SEric Biggerselectromagnetic attacks, to the extent that the underlying Linux 77f4f864c1SEric BiggersCryptographic API algorithms are. If a vulnerable algorithm is used, 78f4f864c1SEric Biggerssuch as a table-based implementation of AES, it may be possible for an 79f4f864c1SEric Biggersattacker to mount a side channel attack against the online system. 80f4f864c1SEric BiggersSide channel attacks may also be mounted against applications 81f4f864c1SEric Biggersconsuming decrypted data. 82f4f864c1SEric Biggers 83f4f864c1SEric BiggersAfter an encryption key has been provided, fscrypt is not designed to 84f4f864c1SEric Biggershide the plaintext file contents or filenames from other users on the 85f4f864c1SEric Biggerssame system, regardless of the visibility of the keyring key. 86f4f864c1SEric BiggersInstead, existing access control mechanisms such as file mode bits, 87f4f864c1SEric BiggersPOSIX ACLs, LSMs, or mount namespaces should be used for this purpose. 88f4f864c1SEric BiggersAlso note that as long as the encryption keys are *anywhere* in 89f4f864c1SEric Biggersmemory, an online attacker can necessarily compromise them by mounting 90f4f864c1SEric Biggersa physical attack or by exploiting any kernel security vulnerability 91f4f864c1SEric Biggerswhich provides an arbitrary memory read primitive. 92f4f864c1SEric Biggers 93f4f864c1SEric BiggersWhile it is ostensibly possible to "evict" keys from the system, 94f4f864c1SEric Biggersrecently accessed encrypted files will remain accessible at least 95f4f864c1SEric Biggersuntil the filesystem is unmounted or the VFS caches are dropped, e.g. 96f4f864c1SEric Biggersusing ``echo 2 > /proc/sys/vm/drop_caches``. Even after that, if the 97f4f864c1SEric BiggersRAM is compromised before being powered off, it will likely still be 98f4f864c1SEric Biggerspossible to recover portions of the plaintext file contents, if not 99f4f864c1SEric Biggerssome of the encryption keys as well. (Since Linux v4.12, all 100f4f864c1SEric Biggersin-kernel keys related to fscrypt are sanitized before being freed. 101f4f864c1SEric BiggersHowever, userspace would need to do its part as well.) 102f4f864c1SEric Biggers 103f4f864c1SEric BiggersCurrently, fscrypt does not prevent a user from maliciously providing 104f4f864c1SEric Biggersan incorrect key for another user's existing encrypted files. A 105f4f864c1SEric Biggersprotection against this is planned. 106f4f864c1SEric Biggers 107f4f864c1SEric BiggersKey hierarchy 108f4f864c1SEric Biggers============= 109f4f864c1SEric Biggers 110f4f864c1SEric BiggersMaster Keys 111f4f864c1SEric Biggers----------- 112f4f864c1SEric Biggers 113f4f864c1SEric BiggersEach encrypted directory tree is protected by a *master key*. Master 114f4f864c1SEric Biggerskeys can be up to 64 bytes long, and must be at least as long as the 115f4f864c1SEric Biggersgreater of the key length needed by the contents and filenames 116f4f864c1SEric Biggersencryption modes being used. For example, if AES-256-XTS is used for 117f4f864c1SEric Biggerscontents encryption, the master key must be 64 bytes (512 bits). Note 118f4f864c1SEric Biggersthat the XTS mode is defined to require a key twice as long as that 119f4f864c1SEric Biggersrequired by the underlying block cipher. 120f4f864c1SEric Biggers 121f4f864c1SEric BiggersTo "unlock" an encrypted directory tree, userspace must provide the 122f4f864c1SEric Biggersappropriate master key. There can be any number of master keys, each 123f4f864c1SEric Biggersof which protects any number of directory trees on any number of 124f4f864c1SEric Biggersfilesystems. 125f4f864c1SEric Biggers 126f4f864c1SEric BiggersUserspace should generate master keys either using a cryptographically 127f4f864c1SEric Biggerssecure random number generator, or by using a KDF (Key Derivation 128f4f864c1SEric BiggersFunction). Note that whenever a KDF is used to "stretch" a 129f4f864c1SEric Biggerslower-entropy secret such as a passphrase, it is critical that a KDF 130f4f864c1SEric Biggersdesigned for this purpose be used, such as scrypt, PBKDF2, or Argon2. 131f4f864c1SEric Biggers 132f4f864c1SEric BiggersPer-file keys 133f4f864c1SEric Biggers------------- 134f4f864c1SEric Biggers 135f4f864c1SEric BiggersMaster keys are not used to encrypt file contents or names directly. 136f4f864c1SEric BiggersInstead, a unique key is derived for each encrypted file, including 137f4f864c1SEric Biggerseach regular file, directory, and symbolic link. This has several 138f4f864c1SEric Biggersadvantages: 139f4f864c1SEric Biggers 140f4f864c1SEric Biggers- In cryptosystems, the same key material should never be used for 141f4f864c1SEric Biggers different purposes. Using the master key as both an XTS key for 142f4f864c1SEric Biggers contents encryption and as a CTS-CBC key for filenames encryption 143f4f864c1SEric Biggers would violate this rule. 144f4f864c1SEric Biggers- Per-file keys simplify the choice of IVs (Initialization Vectors) 145f4f864c1SEric Biggers for contents encryption. Without per-file keys, to ensure IV 146f4f864c1SEric Biggers uniqueness both the inode and logical block number would need to be 147f4f864c1SEric Biggers encoded in the IVs. This would make it impossible to renumber 148f4f864c1SEric Biggers inodes, which e.g. ``resize2fs`` can do when resizing an ext4 149f4f864c1SEric Biggers filesystem. With per-file keys, it is sufficient to encode just the 150f4f864c1SEric Biggers logical block number in the IVs. 151f4f864c1SEric Biggers- Per-file keys strengthen the encryption of filenames, where IVs are 152f4f864c1SEric Biggers reused out of necessity. With a unique key per directory, IV reuse 153f4f864c1SEric Biggers is limited to within a single directory. 154f4f864c1SEric Biggers- Per-file keys allow individual files to be securely erased simply by 155f4f864c1SEric Biggers securely erasing their keys. (Not yet implemented.) 156f4f864c1SEric Biggers 157f4f864c1SEric BiggersA KDF (Key Derivation Function) is used to derive per-file keys from 158f4f864c1SEric Biggersthe master key. This is done instead of wrapping a randomly-generated 159f4f864c1SEric Biggerskey for each file because it reduces the size of the encryption xattr, 160f4f864c1SEric Biggerswhich for some filesystems makes the xattr more likely to fit in-line 161f4f864c1SEric Biggersin the filesystem's inode table. With a KDF, only a 16-byte nonce is 162f4f864c1SEric Biggersrequired --- long enough to make key reuse extremely unlikely. A 163f4f864c1SEric Biggerswrapped key, on the other hand, would need to be up to 64 bytes --- 164f4f864c1SEric Biggersthe length of an AES-256-XTS key. Furthermore, currently there is no 165f4f864c1SEric Biggersrequirement to support unlocking a file with multiple alternative 166f4f864c1SEric Biggersmaster keys or to support rotating master keys. Instead, the master 167f4f864c1SEric Biggerskeys may be wrapped in userspace, e.g. as done by the `fscrypt 168f4f864c1SEric Biggers<https://github.com/google/fscrypt>`_ tool. 169f4f864c1SEric Biggers 170f4f864c1SEric BiggersThe current KDF encrypts the master key using the 16-byte nonce as an 171f4f864c1SEric BiggersAES-128-ECB key. The output is used as the derived key. If the 172f4f864c1SEric Biggersoutput is longer than needed, then it is truncated to the needed 173f4f864c1SEric Biggerslength. Truncation is the norm for directories and symlinks, since 174f4f864c1SEric Biggersthose use the CTS-CBC encryption mode which requires a key half as 175f4f864c1SEric Biggerslong as that required by the XTS encryption mode. 176f4f864c1SEric Biggers 177f4f864c1SEric BiggersNote: this KDF meets the primary security requirement, which is to 178f4f864c1SEric Biggersproduce unique derived keys that preserve the entropy of the master 179f4f864c1SEric Biggerskey, assuming that the master key is already a good pseudorandom key. 180f4f864c1SEric BiggersHowever, it is nonstandard and has some problems such as being 181f4f864c1SEric Biggersreversible, so it is generally considered to be a mistake! It may be 182f4f864c1SEric Biggersreplaced with HKDF or another more standard KDF in the future. 183f4f864c1SEric Biggers 184f4f864c1SEric BiggersEncryption modes and usage 185f4f864c1SEric Biggers========================== 186f4f864c1SEric Biggers 187f4f864c1SEric Biggersfscrypt allows one encryption mode to be specified for file contents 188f4f864c1SEric Biggersand one encryption mode to be specified for filenames. Different 189f4f864c1SEric Biggersdirectory trees are permitted to use different encryption modes. 190f4f864c1SEric BiggersCurrently, the following pairs of encryption modes are supported: 191f4f864c1SEric Biggers 192f4f864c1SEric Biggers- AES-256-XTS for contents and AES-256-CTS-CBC for filenames 193f4f864c1SEric Biggers- AES-128-CBC for contents and AES-128-CTS-CBC for filenames 194f4f864c1SEric Biggers 195f4f864c1SEric BiggersIt is strongly recommended to use AES-256-XTS for contents encryption. 196f4f864c1SEric BiggersAES-128-CBC was added only for low-powered embedded devices with 197f4f864c1SEric Biggerscrypto accelerators such as CAAM or CESA that do not support XTS. 198f4f864c1SEric Biggers 199f4f864c1SEric BiggersNew encryption modes can be added relatively easily, without changes 200f4f864c1SEric Biggersto individual filesystems. However, authenticated encryption (AE) 201f4f864c1SEric Biggersmodes are not currently supported because of the difficulty of dealing 202f4f864c1SEric Biggerswith ciphertext expansion. 203f4f864c1SEric Biggers 204f4f864c1SEric BiggersFor file contents, each filesystem block is encrypted independently. 205f4f864c1SEric BiggersCurrently, only the case where the filesystem block size is equal to 206f4f864c1SEric Biggersthe system's page size (usually 4096 bytes) is supported. With the 207f4f864c1SEric BiggersXTS mode of operation (recommended), the logical block number within 208f4f864c1SEric Biggersthe file is used as the IV. With the CBC mode of operation (not 209f4f864c1SEric Biggersrecommended), ESSIV is used; specifically, the IV for CBC is the 210f4f864c1SEric Biggerslogical block number encrypted with AES-256, where the AES-256 key is 211f4f864c1SEric Biggersthe SHA-256 hash of the inode's data encryption key. 212f4f864c1SEric Biggers 213f4f864c1SEric BiggersFor filenames, the full filename is encrypted at once. Because of the 214f4f864c1SEric Biggersrequirements to retain support for efficient directory lookups and 215f4f864c1SEric Biggersfilenames of up to 255 bytes, a constant initialization vector (IV) is 216f4f864c1SEric Biggersused. However, each encrypted directory uses a unique key, which 217f4f864c1SEric Biggerslimits IV reuse to within a single directory. Note that IV reuse in 218f4f864c1SEric Biggersthe context of CTS-CBC encryption means that when the original 219f4f864c1SEric Biggersfilenames share a common prefix at least as long as the cipher block 220f4f864c1SEric Biggerssize (16 bytes for AES), the corresponding encrypted filenames will 221f4f864c1SEric Biggersalso share a common prefix. This is undesirable; it may be fixed in 222f4f864c1SEric Biggersthe future by switching to an encryption mode that is a strong 223f4f864c1SEric Biggerspseudorandom permutation on arbitrary-length messages, e.g. the HEH 224f4f864c1SEric Biggers(Hash-Encrypt-Hash) mode. 225f4f864c1SEric Biggers 226f4f864c1SEric BiggersSince filenames are encrypted with the CTS-CBC mode of operation, the 227f4f864c1SEric Biggersplaintext and ciphertext filenames need not be multiples of the AES 228f4f864c1SEric Biggersblock size, i.e. 16 bytes. However, the minimum size that can be 229f4f864c1SEric Biggersencrypted is 16 bytes, so shorter filenames are NUL-padded to 16 bytes 230f4f864c1SEric Biggersbefore being encrypted. In addition, to reduce leakage of filename 231f4f864c1SEric Biggerslengths via their ciphertexts, all filenames are NUL-padded to the 232f4f864c1SEric Biggersnext 4, 8, 16, or 32-byte boundary (configurable). 32 is recommended 233f4f864c1SEric Biggerssince this provides the best confidentiality, at the cost of making 234f4f864c1SEric Biggersdirectory entries consume slightly more space. Note that since NUL 235f4f864c1SEric Biggers(``\0``) is not otherwise a valid character in filenames, the padding 236f4f864c1SEric Biggerswill never produce duplicate plaintexts. 237f4f864c1SEric Biggers 238f4f864c1SEric BiggersSymbolic link targets are considered a type of filename and are 239f4f864c1SEric Biggersencrypted in the same way as filenames in directory entries. Each 240f4f864c1SEric Biggerssymlink also uses a unique key; hence, the hardcoded IV is not a 241f4f864c1SEric Biggersproblem for symlinks. 242f4f864c1SEric Biggers 243f4f864c1SEric BiggersUser API 244f4f864c1SEric Biggers======== 245f4f864c1SEric Biggers 246f4f864c1SEric BiggersSetting an encryption policy 247f4f864c1SEric Biggers---------------------------- 248f4f864c1SEric Biggers 249f4f864c1SEric BiggersThe FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an 250f4f864c1SEric Biggersempty directory or verifies that a directory or regular file already 251f4f864c1SEric Biggershas the specified encryption policy. It takes in a pointer to a 252f4f864c1SEric Biggers:c:type:`struct fscrypt_policy`, defined as follows:: 253f4f864c1SEric Biggers 254f4f864c1SEric Biggers #define FS_KEY_DESCRIPTOR_SIZE 8 255f4f864c1SEric Biggers 256f4f864c1SEric Biggers struct fscrypt_policy { 257f4f864c1SEric Biggers __u8 version; 258f4f864c1SEric Biggers __u8 contents_encryption_mode; 259f4f864c1SEric Biggers __u8 filenames_encryption_mode; 260f4f864c1SEric Biggers __u8 flags; 261f4f864c1SEric Biggers __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; 262f4f864c1SEric Biggers }; 263f4f864c1SEric Biggers 264f4f864c1SEric BiggersThis structure must be initialized as follows: 265f4f864c1SEric Biggers 266f4f864c1SEric Biggers- ``version`` must be 0. 267f4f864c1SEric Biggers 268f4f864c1SEric Biggers- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must 269f4f864c1SEric Biggers be set to constants from ``<linux/fs.h>`` which identify the 270f4f864c1SEric Biggers encryption modes to use. If unsure, use 271f4f864c1SEric Biggers FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` 272f4f864c1SEric Biggers and FS_ENCRYPTION_MODE_AES_256_CTS (4) for 273f4f864c1SEric Biggers ``filenames_encryption_mode``. 274f4f864c1SEric Biggers 275f4f864c1SEric Biggers- ``flags`` must be set to a value from ``<linux/fs.h>`` which 276f4f864c1SEric Biggers identifies the amount of NUL-padding to use when encrypting 277f4f864c1SEric Biggers filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3). 278f4f864c1SEric Biggers 279f4f864c1SEric Biggers- ``master_key_descriptor`` specifies how to find the master key in 280f4f864c1SEric Biggers the keyring; see `Adding keys`_. It is up to userspace to choose a 281f4f864c1SEric Biggers unique ``master_key_descriptor`` for each master key. The e4crypt 282f4f864c1SEric Biggers and fscrypt tools use the first 8 bytes of 283f4f864c1SEric Biggers ``SHA-512(SHA-512(master_key))``, but this particular scheme is not 284f4f864c1SEric Biggers required. Also, the master key need not be in the keyring yet when 285f4f864c1SEric Biggers FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added 286f4f864c1SEric Biggers before any files can be created in the encrypted directory. 287f4f864c1SEric Biggers 288f4f864c1SEric BiggersIf the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY 289f4f864c1SEric Biggersverifies that the file is an empty directory. If so, the specified 290f4f864c1SEric Biggersencryption policy is assigned to the directory, turning it into an 291f4f864c1SEric Biggersencrypted directory. After that, and after providing the 292f4f864c1SEric Biggerscorresponding master key as described in `Adding keys`_, all regular 293f4f864c1SEric Biggersfiles, directories (recursively), and symlinks created in the 294f4f864c1SEric Biggersdirectory will be encrypted, inheriting the same encryption policy. 295f4f864c1SEric BiggersThe filenames in the directory's entries will be encrypted as well. 296f4f864c1SEric Biggers 297f4f864c1SEric BiggersAlternatively, if the file is already encrypted, then 298f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption 299f4f864c1SEric Biggerspolicy exactly matches the actual one. If they match, then the ioctl 300f4f864c1SEric Biggersreturns 0. Otherwise, it fails with EEXIST. This works on both 301f4f864c1SEric Biggersregular files and directories, including nonempty directories. 302f4f864c1SEric Biggers 303f4f864c1SEric BiggersNote that the ext4 filesystem does not allow the root directory to be 304f4f864c1SEric Biggersencrypted, even if it is empty. Users who want to encrypt an entire 305f4f864c1SEric Biggersfilesystem with one key should consider using dm-crypt instead. 306f4f864c1SEric Biggers 307f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: 308f4f864c1SEric Biggers 309f4f864c1SEric Biggers- ``EACCES``: the file is not owned by the process's uid, nor does the 310f4f864c1SEric Biggers process have the CAP_FOWNER capability in a namespace with the file 311f4f864c1SEric Biggers owner's uid mapped 312f4f864c1SEric Biggers- ``EEXIST``: the file is already encrypted with an encryption policy 313f4f864c1SEric Biggers different from the one specified 314f4f864c1SEric Biggers- ``EINVAL``: an invalid encryption policy was specified (invalid 315f4f864c1SEric Biggers version, mode(s), or flags) 316f4f864c1SEric Biggers- ``ENOTDIR``: the file is unencrypted and is a regular file, not a 317f4f864c1SEric Biggers directory 318f4f864c1SEric Biggers- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory 319f4f864c1SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 320f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 321f4f864c1SEric Biggers support for this filesystem, or the filesystem superblock has not 322f4f864c1SEric Biggers had encryption enabled on it. (For example, to use encryption on an 323f4f864c1SEric Biggers ext4 filesystem, CONFIG_EXT4_ENCRYPTION must be enabled in the 324f4f864c1SEric Biggers kernel config, and the superblock must have had the "encrypt" 325f4f864c1SEric Biggers feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O 326f4f864c1SEric Biggers encrypt``.) 327f4f864c1SEric Biggers- ``EPERM``: this directory may not be encrypted, e.g. because it is 328f4f864c1SEric Biggers the root directory of an ext4 filesystem 329f4f864c1SEric Biggers- ``EROFS``: the filesystem is readonly 330f4f864c1SEric Biggers 331f4f864c1SEric BiggersGetting an encryption policy 332f4f864c1SEric Biggers---------------------------- 333f4f864c1SEric Biggers 334f4f864c1SEric BiggersThe FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct 335f4f864c1SEric Biggersfscrypt_policy`, if any, for a directory or regular file. See above 336f4f864c1SEric Biggersfor the struct definition. No additional permissions are required 337f4f864c1SEric Biggersbeyond the ability to open the file. 338f4f864c1SEric Biggers 339f4f864c1SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors: 340f4f864c1SEric Biggers 341f4f864c1SEric Biggers- ``EINVAL``: the file is encrypted, but it uses an unrecognized 342f4f864c1SEric Biggers encryption context format 343f4f864c1SEric Biggers- ``ENODATA``: the file is not encrypted 344f4f864c1SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 345f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 346f4f864c1SEric Biggers support for this filesystem 347f4f864c1SEric Biggers 348f4f864c1SEric BiggersNote: if you only need to know whether a file is encrypted or not, on 349f4f864c1SEric Biggersmost filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl 350f4f864c1SEric Biggersand check for FS_ENCRYPT_FL, or to use the statx() system call and 351f4f864c1SEric Biggerscheck for STATX_ATTR_ENCRYPTED in stx_attributes. 352f4f864c1SEric Biggers 353f4f864c1SEric BiggersGetting the per-filesystem salt 354f4f864c1SEric Biggers------------------------------- 355f4f864c1SEric Biggers 356f4f864c1SEric BiggersSome filesystems, such as ext4 and F2FS, also support the deprecated 357f4f864c1SEric Biggersioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly 358f4f864c1SEric Biggersgenerated 16-byte value stored in the filesystem superblock. This 359f4f864c1SEric Biggersvalue is intended to used as a salt when deriving an encryption key 360f4f864c1SEric Biggersfrom a passphrase or other low-entropy user credential. 361f4f864c1SEric Biggers 362f4f864c1SEric BiggersFS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to 363f4f864c1SEric Biggersgenerate and manage any needed salt(s) in userspace. 364f4f864c1SEric Biggers 365f4f864c1SEric BiggersAdding keys 366f4f864c1SEric Biggers----------- 367f4f864c1SEric Biggers 368f4f864c1SEric BiggersTo provide a master key, userspace must add it to an appropriate 369f4f864c1SEric Biggerskeyring using the add_key() system call (see: 370f4f864c1SEric Biggers``Documentation/security/keys/core.rst``). The key type must be 371f4f864c1SEric Biggers"logon"; keys of this type are kept in kernel memory and cannot be 372f4f864c1SEric Biggersread back by userspace. The key description must be "fscrypt:" 373f4f864c1SEric Biggersfollowed by the 16-character lower case hex representation of the 374f4f864c1SEric Biggers``master_key_descriptor`` that was set in the encryption policy. The 375f4f864c1SEric Biggerskey payload must conform to the following structure:: 376f4f864c1SEric Biggers 377f4f864c1SEric Biggers #define FS_MAX_KEY_SIZE 64 378f4f864c1SEric Biggers 379f4f864c1SEric Biggers struct fscrypt_key { 380f4f864c1SEric Biggers u32 mode; 381f4f864c1SEric Biggers u8 raw[FS_MAX_KEY_SIZE]; 382f4f864c1SEric Biggers u32 size; 383f4f864c1SEric Biggers }; 384f4f864c1SEric Biggers 385f4f864c1SEric Biggers``mode`` is ignored; just set it to 0. The actual key is provided in 386f4f864c1SEric Biggers``raw`` with ``size`` indicating its size in bytes. That is, the 387f4f864c1SEric Biggersbytes ``raw[0..size-1]`` (inclusive) are the actual key. 388f4f864c1SEric Biggers 389f4f864c1SEric BiggersThe key description prefix "fscrypt:" may alternatively be replaced 390f4f864c1SEric Biggerswith a filesystem-specific prefix such as "ext4:". However, the 391f4f864c1SEric Biggersfilesystem-specific prefixes are deprecated and should not be used in 392f4f864c1SEric Biggersnew programs. 393f4f864c1SEric Biggers 394f4f864c1SEric BiggersThere are several different types of keyrings in which encryption keys 395f4f864c1SEric Biggersmay be placed, such as a session keyring, a user session keyring, or a 396f4f864c1SEric Biggersuser keyring. Each key must be placed in a keyring that is "attached" 397f4f864c1SEric Biggersto all processes that might need to access files encrypted with it, in 398f4f864c1SEric Biggersthe sense that request_key() will find the key. Generally, if only 399f4f864c1SEric Biggersprocesses belonging to a specific user need to access a given 400f4f864c1SEric Biggersencrypted directory and no session keyring has been installed, then 401f4f864c1SEric Biggersthat directory's key should be placed in that user's user session 402f4f864c1SEric Biggerskeyring or user keyring. Otherwise, a session keyring should be 403f4f864c1SEric Biggersinstalled if needed, and the key should be linked into that session 404f4f864c1SEric Biggerskeyring, or in a keyring linked into that session keyring. 405f4f864c1SEric Biggers 406f4f864c1SEric BiggersNote: introducing the complex visibility semantics of keyrings here 407f4f864c1SEric Biggerswas arguably a mistake --- especially given that by design, after any 408f4f864c1SEric Biggersprocess successfully opens an encrypted file (thereby setting up the 409f4f864c1SEric Biggersper-file key), possessing the keyring key is not actually required for 410f4f864c1SEric Biggersany process to read/write the file until its in-memory inode is 411f4f864c1SEric Biggersevicted. In the future there probably should be a way to provide keys 412f4f864c1SEric Biggersdirectly to the filesystem instead, which would make the intended 413f4f864c1SEric Biggerssemantics clearer. 414f4f864c1SEric Biggers 415f4f864c1SEric BiggersAccess semantics 416f4f864c1SEric Biggers================ 417f4f864c1SEric Biggers 418f4f864c1SEric BiggersWith the key 419f4f864c1SEric Biggers------------ 420f4f864c1SEric Biggers 421f4f864c1SEric BiggersWith the encryption key, encrypted regular files, directories, and 422f4f864c1SEric Biggerssymlinks behave very similarly to their unencrypted counterparts --- 423f4f864c1SEric Biggersafter all, the encryption is intended to be transparent. However, 424f4f864c1SEric Biggersastute users may notice some differences in behavior: 425f4f864c1SEric Biggers 426f4f864c1SEric Biggers- Unencrypted files, or files encrypted with a different encryption 427f4f864c1SEric Biggers policy (i.e. different key, modes, or flags), cannot be renamed or 428f4f864c1SEric Biggers linked into an encrypted directory; see `Encryption policy 429f4f864c1SEric Biggers enforcement`_. Attempts to do so will fail with EPERM. However, 430f4f864c1SEric Biggers encrypted files can be renamed within an encrypted directory, or 431f4f864c1SEric Biggers into an unencrypted directory. 432f4f864c1SEric Biggers 433f4f864c1SEric Biggers- Direct I/O is not supported on encrypted files. Attempts to use 434f4f864c1SEric Biggers direct I/O on such files will fall back to buffered I/O. 435f4f864c1SEric Biggers 436f4f864c1SEric Biggers- The fallocate operations FALLOC_FL_COLLAPSE_RANGE, 437f4f864c1SEric Biggers FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported 438f4f864c1SEric Biggers on encrypted files and will fail with EOPNOTSUPP. 439f4f864c1SEric Biggers 440f4f864c1SEric Biggers- Online defragmentation of encrypted files is not supported. The 441f4f864c1SEric Biggers EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with 442f4f864c1SEric Biggers EOPNOTSUPP. 443f4f864c1SEric Biggers 444f4f864c1SEric Biggers- The ext4 filesystem does not support data journaling with encrypted 445f4f864c1SEric Biggers regular files. It will fall back to ordered data mode instead. 446f4f864c1SEric Biggers 447f4f864c1SEric Biggers- DAX (Direct Access) is not supported on encrypted files. 448f4f864c1SEric Biggers 449f4f864c1SEric Biggers- The st_size of an encrypted symlink will not necessarily give the 450f4f864c1SEric Biggers length of the symlink target as required by POSIX. It will actually 451*2f46a2bcSEric Biggers give the length of the ciphertext, which will be slightly longer 452*2f46a2bcSEric Biggers than the plaintext due to NUL-padding and an extra 2-byte overhead. 453*2f46a2bcSEric Biggers 454*2f46a2bcSEric Biggers- The maximum length of an encrypted symlink is 2 bytes shorter than 455*2f46a2bcSEric Biggers the maximum length of an unencrypted symlink. For example, on an 456*2f46a2bcSEric Biggers EXT4 filesystem with a 4K block size, unencrypted symlinks can be up 457*2f46a2bcSEric Biggers to 4095 bytes long, while encrypted symlinks can only be up to 4093 458*2f46a2bcSEric Biggers bytes long (both lengths excluding the terminating null). 459f4f864c1SEric Biggers 460f4f864c1SEric BiggersNote that mmap *is* supported. This is possible because the pagecache 461f4f864c1SEric Biggersfor an encrypted file contains the plaintext, not the ciphertext. 462f4f864c1SEric Biggers 463f4f864c1SEric BiggersWithout the key 464f4f864c1SEric Biggers--------------- 465f4f864c1SEric Biggers 466f4f864c1SEric BiggersSome filesystem operations may be performed on encrypted regular 467f4f864c1SEric Biggersfiles, directories, and symlinks even before their encryption key has 468f4f864c1SEric Biggersbeen provided: 469f4f864c1SEric Biggers 470f4f864c1SEric Biggers- File metadata may be read, e.g. using stat(). 471f4f864c1SEric Biggers 472f4f864c1SEric Biggers- Directories may be listed, in which case the filenames will be 473f4f864c1SEric Biggers listed in an encoded form derived from their ciphertext. The 474f4f864c1SEric Biggers current encoding algorithm is described in `Filename hashing and 475f4f864c1SEric Biggers encoding`_. The algorithm is subject to change, but it is 476f4f864c1SEric Biggers guaranteed that the presented filenames will be no longer than 477f4f864c1SEric Biggers NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and 478f4f864c1SEric Biggers will uniquely identify directory entries. 479f4f864c1SEric Biggers 480f4f864c1SEric Biggers The ``.`` and ``..`` directory entries are special. They are always 481f4f864c1SEric Biggers present and are not encrypted or encoded. 482f4f864c1SEric Biggers 483f4f864c1SEric Biggers- Files may be deleted. That is, nondirectory files may be deleted 484f4f864c1SEric Biggers with unlink() as usual, and empty directories may be deleted with 485f4f864c1SEric Biggers rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as 486f4f864c1SEric Biggers expected. 487f4f864c1SEric Biggers 488f4f864c1SEric Biggers- Symlink targets may be read and followed, but they will be presented 489f4f864c1SEric Biggers in encrypted form, similar to filenames in directories. Hence, they 490f4f864c1SEric Biggers are unlikely to point to anywhere useful. 491f4f864c1SEric Biggers 492f4f864c1SEric BiggersWithout the key, regular files cannot be opened or truncated. 493f4f864c1SEric BiggersAttempts to do so will fail with ENOKEY. This implies that any 494f4f864c1SEric Biggersregular file operations that require a file descriptor, such as 495f4f864c1SEric Biggersread(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. 496f4f864c1SEric Biggers 497f4f864c1SEric BiggersAlso without the key, files of any type (including directories) cannot 498f4f864c1SEric Biggersbe created or linked into an encrypted directory, nor can a name in an 499f4f864c1SEric Biggersencrypted directory be the source or target of a rename, nor can an 500f4f864c1SEric BiggersO_TMPFILE temporary file be created in an encrypted directory. All 501f4f864c1SEric Biggerssuch operations will fail with ENOKEY. 502f4f864c1SEric Biggers 503f4f864c1SEric BiggersIt is not currently possible to backup and restore encrypted files 504f4f864c1SEric Biggerswithout the encryption key. This would require special APIs which 505f4f864c1SEric Biggershave not yet been implemented. 506f4f864c1SEric Biggers 507f4f864c1SEric BiggersEncryption policy enforcement 508f4f864c1SEric Biggers============================= 509f4f864c1SEric Biggers 510f4f864c1SEric BiggersAfter an encryption policy has been set on a directory, all regular 511f4f864c1SEric Biggersfiles, directories, and symbolic links created in that directory 512f4f864c1SEric Biggers(recursively) will inherit that encryption policy. Special files --- 513f4f864c1SEric Biggersthat is, named pipes, device nodes, and UNIX domain sockets --- will 514f4f864c1SEric Biggersnot be encrypted. 515f4f864c1SEric Biggers 516f4f864c1SEric BiggersExcept for those special files, it is forbidden to have unencrypted 517f4f864c1SEric Biggersfiles, or files encrypted with a different encryption policy, in an 518f4f864c1SEric Biggersencrypted directory tree. Attempts to link or rename such a file into 519f4f864c1SEric Biggersan encrypted directory will fail with EPERM. This is also enforced 520f4f864c1SEric Biggersduring ->lookup() to provide limited protection against offline 521f4f864c1SEric Biggersattacks that try to disable or downgrade encryption in known locations 522f4f864c1SEric Biggerswhere applications may later write sensitive data. It is recommended 523f4f864c1SEric Biggersthat systems implementing a form of "verified boot" take advantage of 524f4f864c1SEric Biggersthis by validating all top-level encryption policies prior to access. 525f4f864c1SEric Biggers 526f4f864c1SEric BiggersImplementation details 527f4f864c1SEric Biggers====================== 528f4f864c1SEric Biggers 529f4f864c1SEric BiggersEncryption context 530f4f864c1SEric Biggers------------------ 531f4f864c1SEric Biggers 532f4f864c1SEric BiggersAn encryption policy is represented on-disk by a :c:type:`struct 533f4f864c1SEric Biggersfscrypt_context`. It is up to individual filesystems to decide where 534f4f864c1SEric Biggersto store it, but normally it would be stored in a hidden extended 535f4f864c1SEric Biggersattribute. It should *not* be exposed by the xattr-related system 536f4f864c1SEric Biggerscalls such as getxattr() and setxattr() because of the special 537f4f864c1SEric Biggerssemantics of the encryption xattr. (In particular, there would be 538f4f864c1SEric Biggersmuch confusion if an encryption policy were to be added to or removed 539f4f864c1SEric Biggersfrom anything other than an empty directory.) The struct is defined 540f4f864c1SEric Biggersas follows:: 541f4f864c1SEric Biggers 542f4f864c1SEric Biggers #define FS_KEY_DESCRIPTOR_SIZE 8 543f4f864c1SEric Biggers #define FS_KEY_DERIVATION_NONCE_SIZE 16 544f4f864c1SEric Biggers 545f4f864c1SEric Biggers struct fscrypt_context { 546f4f864c1SEric Biggers u8 format; 547f4f864c1SEric Biggers u8 contents_encryption_mode; 548f4f864c1SEric Biggers u8 filenames_encryption_mode; 549f4f864c1SEric Biggers u8 flags; 550f4f864c1SEric Biggers u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; 551f4f864c1SEric Biggers u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; 552f4f864c1SEric Biggers }; 553f4f864c1SEric Biggers 554f4f864c1SEric BiggersNote that :c:type:`struct fscrypt_context` contains the same 555f4f864c1SEric Biggersinformation as :c:type:`struct fscrypt_policy` (see `Setting an 556f4f864c1SEric Biggersencryption policy`_), except that :c:type:`struct fscrypt_context` 557f4f864c1SEric Biggersalso contains a nonce. The nonce is randomly generated by the kernel 558f4f864c1SEric Biggersand is used to derive the inode's encryption key as described in 559f4f864c1SEric Biggers`Per-file keys`_. 560f4f864c1SEric Biggers 561f4f864c1SEric BiggersData path changes 562f4f864c1SEric Biggers----------------- 563f4f864c1SEric Biggers 564f4f864c1SEric BiggersFor the read path (->readpage()) of regular files, filesystems can 565f4f864c1SEric Biggersread the ciphertext into the page cache and decrypt it in-place. The 566f4f864c1SEric Biggerspage lock must be held until decryption has finished, to prevent the 567f4f864c1SEric Biggerspage from becoming visible to userspace prematurely. 568f4f864c1SEric Biggers 569f4f864c1SEric BiggersFor the write path (->writepage()) of regular files, filesystems 570f4f864c1SEric Biggerscannot encrypt data in-place in the page cache, since the cached 571f4f864c1SEric Biggersplaintext must be preserved. Instead, filesystems must encrypt into a 572f4f864c1SEric Biggerstemporary buffer or "bounce page", then write out the temporary 573f4f864c1SEric Biggersbuffer. Some filesystems, such as UBIFS, already use temporary 574f4f864c1SEric Biggersbuffers regardless of encryption. Other filesystems, such as ext4 and 575f4f864c1SEric BiggersF2FS, have to allocate bounce pages specially for encryption. 576f4f864c1SEric Biggers 577f4f864c1SEric BiggersFilename hashing and encoding 578f4f864c1SEric Biggers----------------------------- 579f4f864c1SEric Biggers 580f4f864c1SEric BiggersModern filesystems accelerate directory lookups by using indexed 581f4f864c1SEric Biggersdirectories. An indexed directory is organized as a tree keyed by 582f4f864c1SEric Biggersfilename hashes. When a ->lookup() is requested, the filesystem 583f4f864c1SEric Biggersnormally hashes the filename being looked up so that it can quickly 584f4f864c1SEric Biggersfind the corresponding directory entry, if any. 585f4f864c1SEric Biggers 586f4f864c1SEric BiggersWith encryption, lookups must be supported and efficient both with and 587f4f864c1SEric Biggerswithout the encryption key. Clearly, it would not work to hash the 588f4f864c1SEric Biggersplaintext filenames, since the plaintext filenames are unavailable 589f4f864c1SEric Biggerswithout the key. (Hashing the plaintext filenames would also make it 590f4f864c1SEric Biggersimpossible for the filesystem's fsck tool to optimize encrypted 591f4f864c1SEric Biggersdirectories.) Instead, filesystems hash the ciphertext filenames, 592f4f864c1SEric Biggersi.e. the bytes actually stored on-disk in the directory entries. When 593f4f864c1SEric Biggersasked to do a ->lookup() with the key, the filesystem just encrypts 594f4f864c1SEric Biggersthe user-supplied name to get the ciphertext. 595f4f864c1SEric Biggers 596f4f864c1SEric BiggersLookups without the key are more complicated. The raw ciphertext may 597f4f864c1SEric Biggerscontain the ``\0`` and ``/`` characters, which are illegal in 598f4f864c1SEric Biggersfilenames. Therefore, readdir() must base64-encode the ciphertext for 599f4f864c1SEric Biggerspresentation. For most filenames, this works fine; on ->lookup(), the 600f4f864c1SEric Biggersfilesystem just base64-decodes the user-supplied name to get back to 601f4f864c1SEric Biggersthe raw ciphertext. 602f4f864c1SEric Biggers 603f4f864c1SEric BiggersHowever, for very long filenames, base64 encoding would cause the 604f4f864c1SEric Biggersfilename length to exceed NAME_MAX. To prevent this, readdir() 605f4f864c1SEric Biggersactually presents long filenames in an abbreviated form which encodes 606f4f864c1SEric Biggersa strong "hash" of the ciphertext filename, along with the optional 607f4f864c1SEric Biggersfilesystem-specific hash(es) needed for directory lookups. This 608f4f864c1SEric Biggersallows the filesystem to still, with a high degree of confidence, map 609f4f864c1SEric Biggersthe filename given in ->lookup() back to a particular directory entry 610f4f864c1SEric Biggersthat was previously listed by readdir(). See :c:type:`struct 611f4f864c1SEric Biggersfscrypt_digested_name` in the source for more details. 612f4f864c1SEric Biggers 613f4f864c1SEric BiggersNote that the precise way that filenames are presented to userspace 614f4f864c1SEric Biggerswithout the key is subject to change in the future. It is only meant 615f4f864c1SEric Biggersas a way to temporarily present valid filenames so that commands like 616f4f864c1SEric Biggers``rm -r`` work as expected on encrypted directories. 617