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 34c1f1f5bfSEric Biggersdirectly into supported filesystems --- currently ext4, F2FS, UBIFS, 35c1f1f5bfSEric Biggersand CephFS. This allows encrypted files to be read and written 36c1f1f5bfSEric Biggerswithout caching both the decrypted and encrypted pages in the 37c1f1f5bfSEric Biggerspagecache, thereby nearly halving the memory used and bringing it in 38c1f1f5bfSEric Biggersline with unencrypted files. Similarly, half as many dentries and 39c1f1f5bfSEric Biggersinodes are needed. eCryptfs also limits encrypted filenames to 143 40c1f1f5bfSEric Biggersbytes, causing application compatibility issues; fscrypt allows the 41c1f1f5bfSEric Biggersfull 255 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API 42c1f1f5bfSEric Biggerscan be used 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 75ba13f2c8SEric BiggersSide-channel attacks 76ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~ 77ba13f2c8SEric Biggers 78f4f864c1SEric Biggersfscrypt is only resistant to side-channel attacks, such as timing or 79f4f864c1SEric Biggerselectromagnetic attacks, to the extent that the underlying Linux 80abb861faSEric BiggersCryptographic API algorithms or inline encryption hardware are. If a 81abb861faSEric Biggersvulnerable algorithm is used, such as a table-based implementation of 82abb861faSEric BiggersAES, it may be possible for an attacker to mount a side channel attack 83abb861faSEric Biggersagainst the online system. Side channel attacks may also be mounted 84abb861faSEric Biggersagainst applications consuming decrypted data. 85f4f864c1SEric Biggers 86ba13f2c8SEric BiggersUnauthorized file access 87ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~ 88f4f864c1SEric Biggers 89ba13f2c8SEric BiggersAfter an encryption key has been added, fscrypt does not hide the 90ba13f2c8SEric Biggersplaintext file contents or filenames from other users on the same 91ba13f2c8SEric Biggerssystem. Instead, existing access control mechanisms such as file mode 92ba13f2c8SEric Biggersbits, POSIX ACLs, LSMs, or namespaces should be used for this purpose. 93f4f864c1SEric Biggers 94ba13f2c8SEric Biggers(For the reasoning behind this, understand that while the key is 95ba13f2c8SEric Biggersadded, the confidentiality of the data, from the perspective of the 96ba13f2c8SEric Biggerssystem itself, is *not* protected by the mathematical properties of 97ba13f2c8SEric Biggersencryption but rather only by the correctness of the kernel. 98ba13f2c8SEric BiggersTherefore, any encryption-specific access control checks would merely 99ba13f2c8SEric Biggersbe enforced by kernel *code* and therefore would be largely redundant 100ba13f2c8SEric Biggerswith the wide variety of access control mechanisms already available.) 101ba13f2c8SEric Biggers 102ba13f2c8SEric BiggersKernel memory compromise 103ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~ 104ba13f2c8SEric Biggers 105ba13f2c8SEric BiggersAn attacker who compromises the system enough to read from arbitrary 106ba13f2c8SEric Biggersmemory, e.g. by mounting a physical attack or by exploiting a kernel 107ba13f2c8SEric Biggerssecurity vulnerability, can compromise all encryption keys that are 108ba13f2c8SEric Biggerscurrently in use. 109ba13f2c8SEric Biggers 110ba13f2c8SEric BiggersHowever, fscrypt allows encryption keys to be removed from the kernel, 111ba13f2c8SEric Biggerswhich may protect them from later compromise. 112ba13f2c8SEric Biggers 113ba13f2c8SEric BiggersIn more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the 114ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master 115ba13f2c8SEric Biggersencryption key from kernel memory. If it does so, it will also try to 116ba13f2c8SEric Biggersevict all cached inodes which had been "unlocked" using the key, 117ba13f2c8SEric Biggersthereby wiping their per-file keys and making them once again appear 118ba13f2c8SEric Biggers"locked", i.e. in ciphertext or encrypted form. 119ba13f2c8SEric Biggers 120ba13f2c8SEric BiggersHowever, these ioctls have some limitations: 121ba13f2c8SEric Biggers 122ba13f2c8SEric Biggers- Per-file keys for in-use files will *not* be removed or wiped. 123ba13f2c8SEric Biggers Therefore, for maximum effect, userspace should close the relevant 124ba13f2c8SEric Biggers encrypted files and directories before removing a master key, as 125ba13f2c8SEric Biggers well as kill any processes whose working directory is in an affected 126ba13f2c8SEric Biggers encrypted directory. 127ba13f2c8SEric Biggers 128ba13f2c8SEric Biggers- The kernel cannot magically wipe copies of the master key(s) that 129ba13f2c8SEric Biggers userspace might have as well. Therefore, userspace must wipe all 130ba13f2c8SEric Biggers copies of the master key(s) it makes as well; normally this should 131ba13f2c8SEric Biggers be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting 132ba13f2c8SEric Biggers for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies 133ba13f2c8SEric Biggers to all higher levels in the key hierarchy. Userspace should also 134ba13f2c8SEric Biggers follow other security precautions such as mlock()ing memory 135ba13f2c8SEric Biggers containing keys to prevent it from being swapped out. 136ba13f2c8SEric Biggers 137ba13f2c8SEric Biggers- In general, decrypted contents and filenames in the kernel VFS 138ba13f2c8SEric Biggers caches are freed but not wiped. Therefore, portions thereof may be 139ba13f2c8SEric Biggers recoverable from freed memory, even after the corresponding key(s) 140ba13f2c8SEric Biggers were wiped. To partially solve this, you can set 141ba13f2c8SEric Biggers CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1 142ba13f2c8SEric Biggers to your kernel command line. However, this has a performance cost. 143ba13f2c8SEric Biggers 144ba13f2c8SEric Biggers- Secret keys might still exist in CPU registers, in crypto 145ba13f2c8SEric Biggers accelerator hardware (if used by the crypto API to implement any of 146ba13f2c8SEric Biggers the algorithms), or in other places not explicitly considered here. 147ba13f2c8SEric Biggers 148ba13f2c8SEric BiggersLimitations of v1 policies 149ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~ 150ba13f2c8SEric Biggers 151ba13f2c8SEric Biggersv1 encryption policies have some weaknesses with respect to online 152ba13f2c8SEric Biggersattacks: 153ba13f2c8SEric Biggers 154ba13f2c8SEric Biggers- There is no verification that the provided master key is correct. 155ba13f2c8SEric Biggers Therefore, a malicious user can temporarily associate the wrong key 156ba13f2c8SEric Biggers with another user's encrypted files to which they have read-only 157ba13f2c8SEric Biggers access. Because of filesystem caching, the wrong key will then be 158ba13f2c8SEric Biggers used by the other user's accesses to those files, even if the other 159ba13f2c8SEric Biggers user has the correct key in their own keyring. This violates the 160ba13f2c8SEric Biggers meaning of "read-only access". 161ba13f2c8SEric Biggers 162ba13f2c8SEric Biggers- A compromise of a per-file key also compromises the master key from 163ba13f2c8SEric Biggers which it was derived. 164ba13f2c8SEric Biggers 165ba13f2c8SEric Biggers- Non-root users cannot securely remove encryption keys. 166ba13f2c8SEric Biggers 167ba13f2c8SEric BiggersAll the above problems are fixed with v2 encryption policies. For 168ba13f2c8SEric Biggersthis reason among others, it is recommended to use v2 encryption 169ba13f2c8SEric Biggerspolicies on all new encrypted directories. 170f4f864c1SEric Biggers 171f4f864c1SEric BiggersKey hierarchy 172f4f864c1SEric Biggers============= 173f4f864c1SEric Biggers 174f4f864c1SEric BiggersMaster Keys 175f4f864c1SEric Biggers----------- 176f4f864c1SEric Biggers 177f4f864c1SEric BiggersEach encrypted directory tree is protected by a *master key*. Master 178f4f864c1SEric Biggerskeys can be up to 64 bytes long, and must be at least as long as the 1797f595d6aSEric Biggersgreater of the security strength of the contents and filenames 1807f595d6aSEric Biggersencryption modes being used. For example, if any AES-256 mode is 1817f595d6aSEric Biggersused, the master key must be at least 256 bits, i.e. 32 bytes. A 1827f595d6aSEric Biggersstricter requirement applies if the key is used by a v1 encryption 1837f595d6aSEric Biggerspolicy and AES-256-XTS is used; such keys must be 64 bytes. 184f4f864c1SEric Biggers 185f4f864c1SEric BiggersTo "unlock" an encrypted directory tree, userspace must provide the 186f4f864c1SEric Biggersappropriate master key. There can be any number of master keys, each 187f4f864c1SEric Biggersof which protects any number of directory trees on any number of 188f4f864c1SEric Biggersfilesystems. 189f4f864c1SEric Biggers 190ba13f2c8SEric BiggersMaster keys must be real cryptographic keys, i.e. indistinguishable 191ba13f2c8SEric Biggersfrom random bytestrings of the same length. This implies that users 192ba13f2c8SEric Biggers**must not** directly use a password as a master key, zero-pad a 193ba13f2c8SEric Biggersshorter key, or repeat a shorter key. Security cannot be guaranteed 194ba13f2c8SEric Biggersif userspace makes any such error, as the cryptographic proofs and 195ba13f2c8SEric Biggersanalysis would no longer apply. 196ba13f2c8SEric Biggers 197ba13f2c8SEric BiggersInstead, users should generate master keys either using a 198ba13f2c8SEric Biggerscryptographically secure random number generator, or by using a KDF 199ba13f2c8SEric Biggers(Key Derivation Function). The kernel does not do any key stretching; 200ba13f2c8SEric Biggerstherefore, if userspace derives the key from a low-entropy secret such 201ba13f2c8SEric Biggersas a passphrase, it is critical that a KDF designed for this purpose 202ba13f2c8SEric Biggersbe used, such as scrypt, PBKDF2, or Argon2. 203ba13f2c8SEric Biggers 204ba13f2c8SEric BiggersKey derivation function 205ba13f2c8SEric Biggers----------------------- 206ba13f2c8SEric Biggers 207ba13f2c8SEric BiggersWith one exception, fscrypt never uses the master key(s) for 208ba13f2c8SEric Biggersencryption directly. Instead, they are only used as input to a KDF 209ba13f2c8SEric Biggers(Key Derivation Function) to derive the actual keys. 210ba13f2c8SEric Biggers 211ba13f2c8SEric BiggersThe KDF used for a particular master key differs depending on whether 212ba13f2c8SEric Biggersthe key is used for v1 encryption policies or for v2 encryption 213ba13f2c8SEric Biggerspolicies. Users **must not** use the same key for both v1 and v2 214ba13f2c8SEric Biggersencryption policies. (No real-world attack is currently known on this 215ba13f2c8SEric Biggersspecific case of key reuse, but its security cannot be guaranteed 216ba13f2c8SEric Biggerssince the cryptographic proofs and analysis would no longer apply.) 217ba13f2c8SEric Biggers 218ba13f2c8SEric BiggersFor v1 encryption policies, the KDF only supports deriving per-file 219ba13f2c8SEric Biggersencryption keys. It works by encrypting the master key with 220ba13f2c8SEric BiggersAES-128-ECB, using the file's 16-byte nonce as the AES key. The 221ba13f2c8SEric Biggersresulting ciphertext is used as the derived key. If the ciphertext is 222ba13f2c8SEric Biggerslonger than needed, then it is truncated to the needed length. 223ba13f2c8SEric Biggers 224ba13f2c8SEric BiggersFor v2 encryption policies, the KDF is HKDF-SHA512. The master key is 225ba13f2c8SEric Biggerspassed as the "input keying material", no salt is used, and a distinct 226ba13f2c8SEric Biggers"application-specific information string" is used for each distinct 227ba13f2c8SEric Biggerskey to be derived. For example, when a per-file encryption key is 228ba13f2c8SEric Biggersderived, the application-specific information string is the file's 229ba13f2c8SEric Biggersnonce prefixed with "fscrypt\\0" and a context byte. Different 230ba13f2c8SEric Biggerscontext bytes are used for other types of derived keys. 231ba13f2c8SEric Biggers 232ba13f2c8SEric BiggersHKDF-SHA512 is preferred to the original AES-128-ECB based KDF because 233ba13f2c8SEric BiggersHKDF is more flexible, is nonreversible, and evenly distributes 234ba13f2c8SEric Biggersentropy from the master key. HKDF is also standardized and widely 235ba13f2c8SEric Biggersused by other software, whereas the AES-128-ECB based KDF is ad-hoc. 236f4f864c1SEric Biggers 237f592efe7SEric BiggersPer-file encryption keys 238f592efe7SEric Biggers------------------------ 239f4f864c1SEric Biggers 2408094c3ceSEric BiggersSince each master key can protect many files, it is necessary to 2418094c3ceSEric Biggers"tweak" the encryption of each file so that the same plaintext in two 2428094c3ceSEric Biggersfiles doesn't map to the same ciphertext, or vice versa. In most 2438094c3ceSEric Biggerscases, fscrypt does this by deriving per-file keys. When a new 2448094c3ceSEric Biggersencrypted inode (regular file, directory, or symlink) is created, 2458094c3ceSEric Biggersfscrypt randomly generates a 16-byte nonce and stores it in the 246ba13f2c8SEric Biggersinode's encryption xattr. Then, it uses a KDF (as described in `Key 247ba13f2c8SEric Biggersderivation function`_) to derive the file's key from the master key 248ba13f2c8SEric Biggersand nonce. 249f4f864c1SEric Biggers 2508094c3ceSEric BiggersKey derivation was chosen over key wrapping because wrapped keys would 2518094c3ceSEric Biggersrequire larger xattrs which would be less likely to fit in-line in the 2528094c3ceSEric Biggersfilesystem's inode table, and there didn't appear to be any 2538094c3ceSEric Biggerssignificant advantages to key wrapping. In particular, currently 2548094c3ceSEric Biggersthere is no requirement to support unlocking a file with multiple 2558094c3ceSEric Biggersalternative master keys or to support rotating master keys. Instead, 2568094c3ceSEric Biggersthe master keys may be wrapped in userspace, e.g. as is done by the 2578094c3ceSEric Biggers`fscrypt <https://github.com/google/fscrypt>`_ tool. 2588094c3ceSEric Biggers 259b103fb76SEric BiggersDIRECT_KEY policies 260b103fb76SEric Biggers------------------- 261ba13f2c8SEric Biggers 262ba13f2c8SEric BiggersThe Adiantum encryption mode (see `Encryption modes and usage`_) is 263ba13f2c8SEric Biggerssuitable for both contents and filenames encryption, and it accepts 2645b118884SEric Biggerslong IVs --- long enough to hold both an 8-byte data unit index and a 2655b118884SEric Biggers16-byte per-file nonce. Also, the overhead of each Adiantum key is 2665b118884SEric Biggersgreater than that of an AES-256-XTS key. 267ba13f2c8SEric Biggers 268ba13f2c8SEric BiggersTherefore, to improve performance and save memory, for Adiantum a 269ba13f2c8SEric Biggers"direct key" configuration is supported. When the user has enabled 270ba13f2c8SEric Biggersthis by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy, 271f592efe7SEric Biggersper-file encryption keys are not used. Instead, whenever any data 272f592efe7SEric Biggers(contents or filenames) is encrypted, the file's 16-byte nonce is 273f592efe7SEric Biggersincluded in the IV. Moreover: 274ba13f2c8SEric Biggers 275ba13f2c8SEric Biggers- For v1 encryption policies, the encryption is done directly with the 276ba13f2c8SEric Biggers master key. Because of this, users **must not** use the same master 277ba13f2c8SEric Biggers key for any other purpose, even for other v1 policies. 278ba13f2c8SEric Biggers 279ba13f2c8SEric Biggers- For v2 encryption policies, the encryption is done with a per-mode 280ba13f2c8SEric Biggers key derived using the KDF. Users may use the same master key for 281ba13f2c8SEric Biggers other v2 encryption policies. 282ba13f2c8SEric Biggers 283b103fb76SEric BiggersIV_INO_LBLK_64 policies 284b103fb76SEric Biggers----------------------- 285b103fb76SEric Biggers 286b103fb76SEric BiggersWhen FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy, 287b103fb76SEric Biggersthe encryption keys are derived from the master key, encryption mode 288b103fb76SEric Biggersnumber, and filesystem UUID. This normally results in all files 289b103fb76SEric Biggersprotected by the same master key sharing a single contents encryption 290b103fb76SEric Biggerskey and a single filenames encryption key. To still encrypt different 291b103fb76SEric Biggersfiles' data differently, inode numbers are included in the IVs. 292b103fb76SEric BiggersConsequently, shrinking the filesystem may not be allowed. 293b103fb76SEric Biggers 294b103fb76SEric BiggersThis format is optimized for use with inline encryption hardware 295e3b1078bSEric Biggerscompliant with the UFS standard, which supports only 64 IV bits per 296e3b1078bSEric BiggersI/O request and may have only a small number of keyslots. 297e3b1078bSEric Biggers 298e3b1078bSEric BiggersIV_INO_LBLK_32 policies 299e3b1078bSEric Biggers----------------------- 300e3b1078bSEric Biggers 301e3b1078bSEric BiggersIV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for 302e3b1078bSEric BiggersIV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the 3035b118884SEric BiggersSipHash key is derived from the master key) and added to the file data 3045b118884SEric Biggersunit index mod 2^32 to produce a 32-bit IV. 305e3b1078bSEric Biggers 306e3b1078bSEric BiggersThis format is optimized for use with inline encryption hardware 307e3b1078bSEric Biggerscompliant with the eMMC v5.2 standard, which supports only 32 IV bits 308e3b1078bSEric Biggersper I/O request and may have only a small number of keyslots. This 309e3b1078bSEric Biggersformat results in some level of IV reuse, so it should only be used 310e3b1078bSEric Biggerswhen necessary due to hardware limitations. 311b103fb76SEric Biggers 312ba13f2c8SEric BiggersKey identifiers 313ba13f2c8SEric Biggers--------------- 314ba13f2c8SEric Biggers 315ba13f2c8SEric BiggersFor master keys used for v2 encryption policies, a unique 16-byte "key 316ba13f2c8SEric Biggersidentifier" is also derived using the KDF. This value is stored in 317ba13f2c8SEric Biggersthe clear, since it is needed to reliably identify the key itself. 318ba13f2c8SEric Biggers 319aa408f83SDaniel RosenbergDirhash keys 320aa408f83SDaniel Rosenberg------------ 321aa408f83SDaniel Rosenberg 322aa408f83SDaniel RosenbergFor directories that are indexed using a secret-keyed dirhash over the 323aa408f83SDaniel Rosenbergplaintext filenames, the KDF is also used to derive a 128-bit 324aa408f83SDaniel RosenbergSipHash-2-4 key per directory in order to hash filenames. This works 325aa408f83SDaniel Rosenbergjust like deriving a per-file encryption key, except that a different 326aa408f83SDaniel RosenbergKDF context is used. Currently, only casefolded ("case-insensitive") 327aa408f83SDaniel Rosenbergencrypted directories use this style of hashing. 328aa408f83SDaniel Rosenberg 329f4f864c1SEric BiggersEncryption modes and usage 330f4f864c1SEric Biggers========================== 331f4f864c1SEric Biggers 332f4f864c1SEric Biggersfscrypt allows one encryption mode to be specified for file contents 333f4f864c1SEric Biggersand one encryption mode to be specified for filenames. Different 334f4f864c1SEric Biggersdirectory trees are permitted to use different encryption modes. 335324718ddSEric Biggers 336324718ddSEric BiggersSupported modes 337324718ddSEric Biggers--------------- 338324718ddSEric Biggers 339f4f864c1SEric BiggersCurrently, the following pairs of encryption modes are supported: 340f4f864c1SEric Biggers 341*2f944c66SEric Biggers- AES-256-XTS for contents and AES-256-CBC-CTS for filenames 342324718ddSEric Biggers- AES-256-XTS for contents and AES-256-HCTR2 for filenames 3438094c3ceSEric Biggers- Adiantum for both contents and filenames 344*2f944c66SEric Biggers- AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames 345*2f944c66SEric Biggers- SM4-XTS for contents and SM4-CBC-CTS for filenames 346*2f944c66SEric Biggers 347*2f944c66SEric BiggersNote: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS. 348*2f944c66SEric BiggersSo, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS. 349f4f864c1SEric Biggers 350324718ddSEric BiggersAuthenticated encryption modes are not currently supported because of 351324718ddSEric Biggersthe difficulty of dealing with ciphertext expansion. Therefore, 352324718ddSEric Biggerscontents encryption uses a block cipher in `XTS mode 353324718ddSEric Biggers<https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or 354324718ddSEric Biggers`CBC-ESSIV mode 355324718ddSEric Biggers<https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_, 356324718ddSEric Biggersor a wide-block cipher. Filenames encryption uses a 357*2f944c66SEric Biggersblock cipher in `CBC-CTS mode 358324718ddSEric Biggers<https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block 359324718ddSEric Biggerscipher. 3608094c3ceSEric Biggers 361*2f944c66SEric BiggersThe (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default. 362324718ddSEric BiggersIt is also the only option that is *guaranteed* to always be supported 363324718ddSEric Biggersif the kernel supports fscrypt at all; see `Kernel config options`_. 364f4f864c1SEric Biggers 365324718ddSEric BiggersThe (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that 366324718ddSEric Biggersupgrades the filenames encryption to use a wide-block cipher. (A 367324718ddSEric Biggers*wide-block cipher*, also called a tweakable super-pseudorandom 368324718ddSEric Biggerspermutation, has the property that changing one bit scrambles the 369324718ddSEric Biggersentire result.) As described in `Filenames encryption`_, a wide-block 370*2f944c66SEric Biggerscipher is the ideal mode for the problem domain, though CBC-CTS is the 371324718ddSEric Biggers"least bad" choice among the alternatives. For more information about 372324718ddSEric BiggersHCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_. 3738094c3ceSEric Biggers 374324718ddSEric BiggersAdiantum is recommended on systems where AES is too slow due to lack 375324718ddSEric Biggersof hardware acceleration for AES. Adiantum is a wide-block cipher 376324718ddSEric Biggersthat uses XChaCha12 and AES-256 as its underlying components. Most of 377324718ddSEric Biggersthe work is done by XChaCha12, which is much faster than AES when AES 378324718ddSEric Biggersacceleration is unavailable. For more information about Adiantum, see 379324718ddSEric Biggers`the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_. 3806b2a51ffSNathan Huckleberry 381*2f944c66SEric BiggersThe (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair exists only to support 382324718ddSEric Biggerssystems whose only form of AES acceleration is an off-CPU crypto 383324718ddSEric Biggersaccelerator such as CAAM or CESA that does not support XTS. 38441952551SEric Biggers 385324718ddSEric BiggersThe remaining mode pairs are the "national pride ciphers": 386324718ddSEric Biggers 387*2f944c66SEric Biggers- (SM4-XTS, SM4-CBC-CTS) 388324718ddSEric Biggers 389324718ddSEric BiggersGenerally speaking, these ciphers aren't "bad" per se, but they 390324718ddSEric Biggersreceive limited security review compared to the usual choices such as 391324718ddSEric BiggersAES and ChaCha. They also don't bring much new to the table. It is 392324718ddSEric Biggerssuggested to only use these ciphers where their use is mandated. 393324718ddSEric Biggers 394324718ddSEric BiggersKernel config options 395324718ddSEric Biggers--------------------- 396324718ddSEric Biggers 397324718ddSEric BiggersEnabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in 398324718ddSEric Biggersonly the basic support from the crypto API needed to use AES-256-XTS 399*2f944c66SEric Biggersand AES-256-CBC-CTS encryption. For optimal performance, it is 400324718ddSEric Biggersstrongly recommended to also enable any available platform-specific 401324718ddSEric Biggerskconfig options that provide acceleration for the algorithm(s) you 402324718ddSEric Biggerswish to use. Support for any "non-default" encryption modes typically 403324718ddSEric Biggersrequires extra kconfig options as well. 404324718ddSEric Biggers 405324718ddSEric BiggersBelow, some relevant options are listed by encryption mode. Note, 406324718ddSEric Biggersacceleration options not listed below may be available for your 407324718ddSEric Biggersplatform; refer to the kconfig menus. File contents encryption can 408324718ddSEric Biggersalso be configured to use inline encryption hardware instead of the 409324718ddSEric Biggerskernel crypto API (see `Inline encryption support`_); in that case, 410324718ddSEric Biggersthe file contents mode doesn't need to supported in the kernel crypto 411324718ddSEric BiggersAPI, but the filenames mode still does. 412324718ddSEric Biggers 413*2f944c66SEric Biggers- AES-256-XTS and AES-256-CBC-CTS 414324718ddSEric Biggers - Recommended: 415324718ddSEric Biggers - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK 416324718ddSEric Biggers - x86: CONFIG_CRYPTO_AES_NI_INTEL 417324718ddSEric Biggers 418324718ddSEric Biggers- AES-256-HCTR2 419324718ddSEric Biggers - Mandatory: 420324718ddSEric Biggers - CONFIG_CRYPTO_HCTR2 421324718ddSEric Biggers - Recommended: 422324718ddSEric Biggers - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK 423324718ddSEric Biggers - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE 424324718ddSEric Biggers - x86: CONFIG_CRYPTO_AES_NI_INTEL 425324718ddSEric Biggers - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI 426324718ddSEric Biggers 427324718ddSEric Biggers- Adiantum 428324718ddSEric Biggers - Mandatory: 429324718ddSEric Biggers - CONFIG_CRYPTO_ADIANTUM 430324718ddSEric Biggers - Recommended: 431324718ddSEric Biggers - arm32: CONFIG_CRYPTO_CHACHA20_NEON 432324718ddSEric Biggers - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON 433324718ddSEric Biggers - arm64: CONFIG_CRYPTO_CHACHA20_NEON 434324718ddSEric Biggers - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON 435324718ddSEric Biggers - x86: CONFIG_CRYPTO_CHACHA20_X86_64 436324718ddSEric Biggers - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 437324718ddSEric Biggers - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 438324718ddSEric Biggers 439*2f944c66SEric Biggers- AES-128-CBC-ESSIV and AES-128-CBC-CTS: 440324718ddSEric Biggers - Mandatory: 441324718ddSEric Biggers - CONFIG_CRYPTO_ESSIV 442324718ddSEric Biggers - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation 443324718ddSEric Biggers - Recommended: 444324718ddSEric Biggers - AES-CBC acceleration 445324718ddSEric Biggers 446324718ddSEric Biggersfscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512 447324718ddSEric Biggersacceleration is recommended: 448324718ddSEric Biggers 449324718ddSEric Biggers- SHA-512 450324718ddSEric Biggers - Recommended: 451324718ddSEric Biggers - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE 452324718ddSEric Biggers - x86: CONFIG_CRYPTO_SHA512_SSSE3 453f4f864c1SEric Biggers 4548094c3ceSEric BiggersContents encryption 4558094c3ceSEric Biggers------------------- 4568094c3ceSEric Biggers 4575b118884SEric BiggersFor contents encryption, each file's contents is divided into "data 4585b118884SEric Biggersunits". Each data unit is encrypted independently. The IV for each 4595b118884SEric Biggersdata unit incorporates the zero-based index of the data unit within 4605b118884SEric Biggersthe file. This ensures that each data unit within a file is encrypted 4615b118884SEric Biggersdifferently, which is essential to prevent leaking information. 462f4f864c1SEric Biggers 4635b118884SEric BiggersNote: the encryption depending on the offset into the file means that 4645b118884SEric Biggersoperations like "collapse range" and "insert range" that rearrange the 4655b118884SEric Biggersextent mapping of files are not supported on encrypted files. 466f4f864c1SEric Biggers 4675b118884SEric BiggersThere are two cases for the sizes of the data units: 4688094c3ceSEric Biggers 4695b118884SEric Biggers* Fixed-size data units. This is how all filesystems other than UBIFS 4705b118884SEric Biggers work. A file's data units are all the same size; the last data unit 4715b118884SEric Biggers is zero-padded if needed. By default, the data unit size is equal 4725b118884SEric Biggers to the filesystem block size. On some filesystems, users can select 4735b118884SEric Biggers a sub-block data unit size via the ``log2_data_unit_size`` field of 4745b118884SEric Biggers the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_. 475b103fb76SEric Biggers 4765b118884SEric Biggers* Variable-size data units. This is what UBIFS does. Each "UBIFS 4775b118884SEric Biggers data node" is treated as a crypto data unit. Each contains variable 4785b118884SEric Biggers length, possibly compressed data, zero-padded to the next 16-byte 4795b118884SEric Biggers boundary. Users cannot select a sub-block data unit size on UBIFS. 480b103fb76SEric Biggers 4815b118884SEric BiggersIn the case of compression + encryption, the compressed data is 4825b118884SEric Biggersencrypted. UBIFS compression works as described above. f2fs 4835b118884SEric Biggerscompression works a bit differently; it compresses a number of 4845b118884SEric Biggersfilesystem blocks into a smaller number of filesystem blocks. 4855b118884SEric BiggersTherefore a f2fs-compressed file still uses fixed-size data units, and 4865b118884SEric Biggersit is encrypted in a similar way to a file containing holes. 487e3b1078bSEric Biggers 4885b118884SEric BiggersAs mentioned in `Key hierarchy`_, the default encryption setting uses 4895b118884SEric Biggersper-file keys. In this case, the IV for each data unit is simply the 4905b118884SEric Biggersindex of the data unit in the file. However, users can select an 4915b118884SEric Biggersencryption setting that does not use per-file keys. For these, some 4925b118884SEric Biggerskind of file identifier is incorporated into the IVs as follows: 4935b118884SEric Biggers 4945b118884SEric Biggers- With `DIRECT_KEY policies`_, the data unit index is placed in bits 4955b118884SEric Biggers 0-63 of the IV, and the file's nonce is placed in bits 64-191. 4965b118884SEric Biggers 4975b118884SEric Biggers- With `IV_INO_LBLK_64 policies`_, the data unit index is placed in 4985b118884SEric Biggers bits 0-31 of the IV, and the file's inode number is placed in bits 4995b118884SEric Biggers 32-63. This setting is only allowed when data unit indices and 5005b118884SEric Biggers inode numbers fit in 32 bits. 5015b118884SEric Biggers 5025b118884SEric Biggers- With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed 5035b118884SEric Biggers and added to the data unit index. The resulting value is truncated 5045b118884SEric Biggers to 32 bits and placed in bits 0-31 of the IV. This setting is only 5055b118884SEric Biggers allowed when data unit indices and inode numbers fit in 32 bits. 5065b118884SEric Biggers 5075b118884SEric BiggersThe byte order of the IV is always little endian. 5085b118884SEric Biggers 5095b118884SEric BiggersIf the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an 5105b118884SEric BiggersESSIV layer is automatically included. In this case, before the IV is 5115b118884SEric Biggerspassed to AES-128-CBC, it is encrypted with AES-256 where the AES-256 5125b118884SEric Biggerskey is the SHA-256 hash of the file's contents encryption key. 5138094c3ceSEric Biggers 5148094c3ceSEric BiggersFilenames encryption 5158094c3ceSEric Biggers-------------------- 5168094c3ceSEric Biggers 5178094c3ceSEric BiggersFor filenames, each full filename is encrypted at once. Because of 5188094c3ceSEric Biggersthe requirements to retain support for efficient directory lookups and 5198094c3ceSEric Biggersfilenames of up to 255 bytes, the same IV is used for every filename 5208094c3ceSEric Biggersin a directory. 5218094c3ceSEric Biggers 522b103fb76SEric BiggersHowever, each encrypted directory still uses a unique key, or 523b103fb76SEric Biggersalternatively has the file's nonce (for `DIRECT_KEY policies`_) or 524b103fb76SEric Biggersinode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. 525b103fb76SEric BiggersThus, IV reuse is limited to within a single directory. 5268094c3ceSEric Biggers 527*2f944c66SEric BiggersWith CBC-CTS, the IV reuse means that when the plaintext filenames share a 5286b2a51ffSNathan Huckleberrycommon prefix at least as long as the cipher block size (16 bytes for AES), the 5296b2a51ffSNathan Huckleberrycorresponding encrypted filenames will also share a common prefix. This is 5306b2a51ffSNathan Huckleberryundesirable. Adiantum and HCTR2 do not have this weakness, as they are 5316b2a51ffSNathan Huckleberrywide-block encryption modes. 5328094c3ceSEric Biggers 5338094c3ceSEric BiggersAll supported filenames encryption modes accept any plaintext length 5348094c3ceSEric Biggers>= 16 bytes; cipher block alignment is not required. However, 5358094c3ceSEric Biggersfilenames shorter than 16 bytes are NUL-padded to 16 bytes before 5368094c3ceSEric Biggersbeing encrypted. In addition, to reduce leakage of filename lengths 5378094c3ceSEric Biggersvia their ciphertexts, all filenames are NUL-padded to the next 4, 8, 5388094c3ceSEric Biggers16, or 32-byte boundary (configurable). 32 is recommended since this 5398094c3ceSEric Biggersprovides the best confidentiality, at the cost of making directory 5408094c3ceSEric Biggersentries consume slightly more space. Note that since NUL (``\0``) is 5418094c3ceSEric Biggersnot otherwise a valid character in filenames, the padding will never 5428094c3ceSEric Biggersproduce duplicate plaintexts. 543f4f864c1SEric Biggers 544f4f864c1SEric BiggersSymbolic link targets are considered a type of filename and are 5458094c3ceSEric Biggersencrypted in the same way as filenames in directory entries, except 5468094c3ceSEric Biggersthat IV reuse is not a problem as each symlink has its own inode. 547f4f864c1SEric Biggers 548f4f864c1SEric BiggersUser API 549f4f864c1SEric Biggers======== 550f4f864c1SEric Biggers 551f4f864c1SEric BiggersSetting an encryption policy 552f4f864c1SEric Biggers---------------------------- 553f4f864c1SEric Biggers 554ba13f2c8SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY 555ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 556ba13f2c8SEric Biggers 557f4f864c1SEric BiggersThe FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an 558f4f864c1SEric Biggersempty directory or verifies that a directory or regular file already 55974e2f8d3SMauro Carvalho Chehabhas the specified encryption policy. It takes in a pointer to 56074e2f8d3SMauro Carvalho Chehabstruct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as 56174e2f8d3SMauro Carvalho Chehabfollows:: 562f4f864c1SEric Biggers 563ba13f2c8SEric Biggers #define FSCRYPT_POLICY_V1 0 5642336d0deSEric Biggers #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 565ba13f2c8SEric Biggers struct fscrypt_policy_v1 { 566f4f864c1SEric Biggers __u8 version; 567f4f864c1SEric Biggers __u8 contents_encryption_mode; 568f4f864c1SEric Biggers __u8 filenames_encryption_mode; 569f4f864c1SEric Biggers __u8 flags; 5702336d0deSEric Biggers __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; 571f4f864c1SEric Biggers }; 572ba13f2c8SEric Biggers #define fscrypt_policy fscrypt_policy_v1 573ba13f2c8SEric Biggers 574ba13f2c8SEric Biggers #define FSCRYPT_POLICY_V2 2 575ba13f2c8SEric Biggers #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 576ba13f2c8SEric Biggers struct fscrypt_policy_v2 { 577ba13f2c8SEric Biggers __u8 version; 578ba13f2c8SEric Biggers __u8 contents_encryption_mode; 579ba13f2c8SEric Biggers __u8 filenames_encryption_mode; 580ba13f2c8SEric Biggers __u8 flags; 5815b118884SEric Biggers __u8 log2_data_unit_size; 5825b118884SEric Biggers __u8 __reserved[3]; 583ba13f2c8SEric Biggers __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; 584ba13f2c8SEric Biggers }; 585f4f864c1SEric Biggers 586f4f864c1SEric BiggersThis structure must be initialized as follows: 587f4f864c1SEric Biggers 58874e2f8d3SMauro Carvalho Chehab- ``version`` must be FSCRYPT_POLICY_V1 (0) if 58974e2f8d3SMauro Carvalho Chehab struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if 59074e2f8d3SMauro Carvalho Chehab struct fscrypt_policy_v2 is used. (Note: we refer to the original 59174e2f8d3SMauro Carvalho Chehab policy version as "v1", though its version code is really 0.) 59274e2f8d3SMauro Carvalho Chehab For new encrypted directories, use v2 policies. 593f4f864c1SEric Biggers 594f4f864c1SEric Biggers- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must 5952336d0deSEric Biggers be set to constants from ``<linux/fscrypt.h>`` which identify the 5962336d0deSEric Biggers encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS 5972336d0deSEric Biggers (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS 598324718ddSEric Biggers (4) for ``filenames_encryption_mode``. For details, see `Encryption 599324718ddSEric Biggers modes and usage`_. 600324718ddSEric Biggers 601324718ddSEric Biggers v1 encryption policies only support three combinations of modes: 602324718ddSEric Biggers (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS), 603324718ddSEric Biggers (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and 604324718ddSEric Biggers (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM). v2 policies support 605324718ddSEric Biggers all combinations documented in `Supported modes`_. 606f4f864c1SEric Biggers 607b103fb76SEric Biggers- ``flags`` contains optional flags from ``<linux/fscrypt.h>``: 608b103fb76SEric Biggers 609b103fb76SEric Biggers - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when 610b103fb76SEric Biggers encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 611b103fb76SEric Biggers (0x3). 612b103fb76SEric Biggers - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_. 613b103fb76SEric Biggers - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64 614e3b1078bSEric Biggers policies`_. 615e3b1078bSEric Biggers - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32 616e3b1078bSEric Biggers policies`_. 617e3b1078bSEric Biggers 618e3b1078bSEric Biggers v1 encryption policies only support the PAD_* and DIRECT_KEY flags. 619e3b1078bSEric Biggers The other flags are only supported by v2 encryption policies. 620e3b1078bSEric Biggers 621e3b1078bSEric Biggers The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are 622e3b1078bSEric Biggers mutually exclusive. 623f4f864c1SEric Biggers 6245b118884SEric Biggers- ``log2_data_unit_size`` is the log2 of the data unit size in bytes, 6255b118884SEric Biggers or 0 to select the default data unit size. The data unit size is 6265b118884SEric Biggers the granularity of file contents encryption. For example, setting 6275b118884SEric Biggers ``log2_data_unit_size`` to 12 causes file contents be passed to the 6285b118884SEric Biggers underlying encryption algorithm (such as AES-256-XTS) in 4096-byte 6295b118884SEric Biggers data units, each with its own IV. 6305b118884SEric Biggers 6315b118884SEric Biggers Not all filesystems support setting ``log2_data_unit_size``. ext4 6325b118884SEric Biggers and f2fs support it since Linux v6.7. On filesystems that support 6335b118884SEric Biggers it, the supported nonzero values are 9 through the log2 of the 6345b118884SEric Biggers filesystem block size, inclusively. The default value of 0 selects 6355b118884SEric Biggers the filesystem block size. 6365b118884SEric Biggers 6375b118884SEric Biggers The main use case for ``log2_data_unit_size`` is for selecting a 6385b118884SEric Biggers data unit size smaller than the filesystem block size for 6395b118884SEric Biggers compatibility with inline encryption hardware that only supports 6405b118884SEric Biggers smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be 6415b118884SEric Biggers useful for checking which data unit sizes are supported by a 6425b118884SEric Biggers particular system's inline encryption hardware. 6435b118884SEric Biggers 6445b118884SEric Biggers Leave this field zeroed unless you are certain you need it. Using 6455b118884SEric Biggers an unnecessarily small data unit size reduces performance. 6465b118884SEric Biggers 647ba13f2c8SEric Biggers- For v2 encryption policies, ``__reserved`` must be zeroed. 648ba13f2c8SEric Biggers 649ba13f2c8SEric Biggers- For v1 encryption policies, ``master_key_descriptor`` specifies how 650ba13f2c8SEric Biggers to find the master key in a keyring; see `Adding keys`_. It is up 651ba13f2c8SEric Biggers to userspace to choose a unique ``master_key_descriptor`` for each 652ba13f2c8SEric Biggers master key. The e4crypt and fscrypt tools use the first 8 bytes of 653f4f864c1SEric Biggers ``SHA-512(SHA-512(master_key))``, but this particular scheme is not 654f4f864c1SEric Biggers required. Also, the master key need not be in the keyring yet when 655f4f864c1SEric Biggers FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added 656f4f864c1SEric Biggers before any files can be created in the encrypted directory. 657f4f864c1SEric Biggers 658ba13f2c8SEric Biggers For v2 encryption policies, ``master_key_descriptor`` has been 659ba13f2c8SEric Biggers replaced with ``master_key_identifier``, which is longer and cannot 660ba13f2c8SEric Biggers be arbitrarily chosen. Instead, the key must first be added using 661ba13f2c8SEric Biggers `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` 66274e2f8d3SMauro Carvalho Chehab the kernel returned in the struct fscrypt_add_key_arg must 66374e2f8d3SMauro Carvalho Chehab be used as the ``master_key_identifier`` in 66474e2f8d3SMauro Carvalho Chehab struct fscrypt_policy_v2. 665ba13f2c8SEric Biggers 666f4f864c1SEric BiggersIf the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY 667f4f864c1SEric Biggersverifies that the file is an empty directory. If so, the specified 668f4f864c1SEric Biggersencryption policy is assigned to the directory, turning it into an 669f4f864c1SEric Biggersencrypted directory. After that, and after providing the 670f4f864c1SEric Biggerscorresponding master key as described in `Adding keys`_, all regular 671f4f864c1SEric Biggersfiles, directories (recursively), and symlinks created in the 672f4f864c1SEric Biggersdirectory will be encrypted, inheriting the same encryption policy. 673f4f864c1SEric BiggersThe filenames in the directory's entries will be encrypted as well. 674f4f864c1SEric Biggers 675f4f864c1SEric BiggersAlternatively, if the file is already encrypted, then 676f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption 677f4f864c1SEric Biggerspolicy exactly matches the actual one. If they match, then the ioctl 678f4f864c1SEric Biggersreturns 0. Otherwise, it fails with EEXIST. This works on both 679f4f864c1SEric Biggersregular files and directories, including nonempty directories. 680f4f864c1SEric Biggers 681ba13f2c8SEric BiggersWhen a v2 encryption policy is assigned to a directory, it is also 682ba13f2c8SEric Biggersrequired that either the specified key has been added by the current 683ba13f2c8SEric Biggersuser or that the caller has CAP_FOWNER in the initial user namespace. 684ba13f2c8SEric Biggers(This is needed to prevent a user from encrypting their data with 685ba13f2c8SEric Biggersanother user's key.) The key must remain added while 686ba13f2c8SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new 687ba13f2c8SEric Biggersencrypted directory does not need to be accessed immediately, then the 688ba13f2c8SEric Biggerskey can be removed right away afterwards. 689ba13f2c8SEric Biggers 690f4f864c1SEric BiggersNote that the ext4 filesystem does not allow the root directory to be 691f4f864c1SEric Biggersencrypted, even if it is empty. Users who want to encrypt an entire 692f4f864c1SEric Biggersfilesystem with one key should consider using dm-crypt instead. 693f4f864c1SEric Biggers 694f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: 695f4f864c1SEric Biggers 696f4f864c1SEric Biggers- ``EACCES``: the file is not owned by the process's uid, nor does the 697f4f864c1SEric Biggers process have the CAP_FOWNER capability in a namespace with the file 698f4f864c1SEric Biggers owner's uid mapped 699f4f864c1SEric Biggers- ``EEXIST``: the file is already encrypted with an encryption policy 700f4f864c1SEric Biggers different from the one specified 701f4f864c1SEric Biggers- ``EINVAL``: an invalid encryption policy was specified (invalid 7026e1918cfSDaniel Rosenberg version, mode(s), or flags; or reserved bits were set); or a v1 7036e1918cfSDaniel Rosenberg encryption policy was specified but the directory has the casefold 7046e1918cfSDaniel Rosenberg flag enabled (casefolding is incompatible with v1 policies). 705ba13f2c8SEric Biggers- ``ENOKEY``: a v2 encryption policy was specified, but the key with 706ba13f2c8SEric Biggers the specified ``master_key_identifier`` has not been added, nor does 707ba13f2c8SEric Biggers the process have the CAP_FOWNER capability in the initial user 708ba13f2c8SEric Biggers namespace 709f4f864c1SEric Biggers- ``ENOTDIR``: the file is unencrypted and is a regular file, not a 710f4f864c1SEric Biggers directory 711f4f864c1SEric Biggers- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory 712f4f864c1SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 713f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 714643fa961SChandan Rajendra support for filesystems, or the filesystem superblock has not 715f4f864c1SEric Biggers had encryption enabled on it. (For example, to use encryption on an 716643fa961SChandan Rajendra ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the 717f4f864c1SEric Biggers kernel config, and the superblock must have had the "encrypt" 718f4f864c1SEric Biggers feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O 719f4f864c1SEric Biggers encrypt``.) 720f4f864c1SEric Biggers- ``EPERM``: this directory may not be encrypted, e.g. because it is 721f4f864c1SEric Biggers the root directory of an ext4 filesystem 722f4f864c1SEric Biggers- ``EROFS``: the filesystem is readonly 723f4f864c1SEric Biggers 724f4f864c1SEric BiggersGetting an encryption policy 725f4f864c1SEric Biggers---------------------------- 726f4f864c1SEric Biggers 727ba13f2c8SEric BiggersTwo ioctls are available to get a file's encryption policy: 728f4f864c1SEric Biggers 729ba13f2c8SEric Biggers- `FS_IOC_GET_ENCRYPTION_POLICY_EX`_ 730ba13f2c8SEric Biggers- `FS_IOC_GET_ENCRYPTION_POLICY`_ 731ba13f2c8SEric Biggers 732ba13f2c8SEric BiggersThe extended (_EX) version of the ioctl is more general and is 733ba13f2c8SEric Biggersrecommended to use when possible. However, on older kernels only the 734ba13f2c8SEric Biggersoriginal ioctl is available. Applications should try the extended 735ba13f2c8SEric Biggersversion, and if it fails with ENOTTY fall back to the original 736ba13f2c8SEric Biggersversion. 737ba13f2c8SEric Biggers 738ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY_EX 739ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 740ba13f2c8SEric Biggers 741ba13f2c8SEric BiggersThe FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption 742ba13f2c8SEric Biggerspolicy, if any, for a directory or regular file. No additional 743ba13f2c8SEric Biggerspermissions are required beyond the ability to open the file. It 74474e2f8d3SMauro Carvalho Chehabtakes in a pointer to struct fscrypt_get_policy_ex_arg, 745ba13f2c8SEric Biggersdefined as follows:: 746ba13f2c8SEric Biggers 747ba13f2c8SEric Biggers struct fscrypt_get_policy_ex_arg { 748ba13f2c8SEric Biggers __u64 policy_size; /* input/output */ 749ba13f2c8SEric Biggers union { 750ba13f2c8SEric Biggers __u8 version; 751ba13f2c8SEric Biggers struct fscrypt_policy_v1 v1; 752ba13f2c8SEric Biggers struct fscrypt_policy_v2 v2; 753ba13f2c8SEric Biggers } policy; /* output */ 754ba13f2c8SEric Biggers }; 755ba13f2c8SEric Biggers 756ba13f2c8SEric BiggersThe caller must initialize ``policy_size`` to the size available for 757ba13f2c8SEric Biggersthe policy struct, i.e. ``sizeof(arg.policy)``. 758ba13f2c8SEric Biggers 759ba13f2c8SEric BiggersOn success, the policy struct is returned in ``policy``, and its 760ba13f2c8SEric Biggersactual size is returned in ``policy_size``. ``policy.version`` should 761ba13f2c8SEric Biggersbe checked to determine the version of policy returned. Note that the 762ba13f2c8SEric Biggersversion code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1). 763ba13f2c8SEric Biggers 764ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors: 765f4f864c1SEric Biggers 766f4f864c1SEric Biggers- ``EINVAL``: the file is encrypted, but it uses an unrecognized 767ba13f2c8SEric Biggers encryption policy version 768f4f864c1SEric Biggers- ``ENODATA``: the file is not encrypted 769ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption, 770ba13f2c8SEric Biggers or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX 771ba13f2c8SEric Biggers (try FS_IOC_GET_ENCRYPTION_POLICY instead) 772f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 7730642ea24SChao Yu support for this filesystem, or the filesystem superblock has not 7740642ea24SChao Yu had encryption enabled on it 775ba13f2c8SEric Biggers- ``EOVERFLOW``: the file is encrypted and uses a recognized 776ba13f2c8SEric Biggers encryption policy version, but the policy struct does not fit into 777ba13f2c8SEric Biggers the provided buffer 778f4f864c1SEric Biggers 779f4f864c1SEric BiggersNote: if you only need to know whether a file is encrypted or not, on 780f4f864c1SEric Biggersmost filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl 781f4f864c1SEric Biggersand check for FS_ENCRYPT_FL, or to use the statx() system call and 782f4f864c1SEric Biggerscheck for STATX_ATTR_ENCRYPTED in stx_attributes. 783f4f864c1SEric Biggers 784ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY 785ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 786ba13f2c8SEric Biggers 787ba13f2c8SEric BiggersThe FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the 788ba13f2c8SEric Biggersencryption policy, if any, for a directory or regular file. However, 789ba13f2c8SEric Biggersunlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, 790ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY only supports the original policy 79174e2f8d3SMauro Carvalho Chehabversion. It takes in a pointer directly to struct fscrypt_policy_v1 79274e2f8d3SMauro Carvalho Chehabrather than struct fscrypt_get_policy_ex_arg. 793ba13f2c8SEric Biggers 794ba13f2c8SEric BiggersThe error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those 795ba13f2c8SEric Biggersfor FS_IOC_GET_ENCRYPTION_POLICY_EX, except that 796ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is 797ba13f2c8SEric Biggersencrypted using a newer encryption policy version. 798ba13f2c8SEric Biggers 799f4f864c1SEric BiggersGetting the per-filesystem salt 800f4f864c1SEric Biggers------------------------------- 801f4f864c1SEric Biggers 802f4f864c1SEric BiggersSome filesystems, such as ext4 and F2FS, also support the deprecated 803f4f864c1SEric Biggersioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly 804f4f864c1SEric Biggersgenerated 16-byte value stored in the filesystem superblock. This 805f4f864c1SEric Biggersvalue is intended to used as a salt when deriving an encryption key 806f4f864c1SEric Biggersfrom a passphrase or other low-entropy user credential. 807f4f864c1SEric Biggers 808f4f864c1SEric BiggersFS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to 809f4f864c1SEric Biggersgenerate and manage any needed salt(s) in userspace. 810f4f864c1SEric Biggers 811e98ad464SEric BiggersGetting a file's encryption nonce 812e98ad464SEric Biggers--------------------------------- 813e98ad464SEric Biggers 814e98ad464SEric BiggersSince Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported. 815e98ad464SEric BiggersOn encrypted files and directories it gets the inode's 16-byte nonce. 816e98ad464SEric BiggersOn unencrypted files and directories, it fails with ENODATA. 817e98ad464SEric Biggers 818e98ad464SEric BiggersThis ioctl can be useful for automated tests which verify that the 819e98ad464SEric Biggersencryption is being done correctly. It is not needed for normal use 820e98ad464SEric Biggersof fscrypt. 821e98ad464SEric Biggers 822f4f864c1SEric BiggersAdding keys 823f4f864c1SEric Biggers----------- 824f4f864c1SEric Biggers 825ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY 826ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~ 827ba13f2c8SEric Biggers 828ba13f2c8SEric BiggersThe FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to 829ba13f2c8SEric Biggersthe filesystem, making all files on the filesystem which were 830ba13f2c8SEric Biggersencrypted using that key appear "unlocked", i.e. in plaintext form. 831ba13f2c8SEric BiggersIt can be executed on any file or directory on the target filesystem, 832ba13f2c8SEric Biggersbut using the filesystem's root directory is recommended. It takes in 83374e2f8d3SMauro Carvalho Chehaba pointer to struct fscrypt_add_key_arg, defined as follows:: 834ba13f2c8SEric Biggers 835ba13f2c8SEric Biggers struct fscrypt_add_key_arg { 836ba13f2c8SEric Biggers struct fscrypt_key_specifier key_spec; 837ba13f2c8SEric Biggers __u32 raw_size; 83893edd392SEric Biggers __u32 key_id; 83993edd392SEric Biggers __u32 __reserved[8]; 840ba13f2c8SEric Biggers __u8 raw[]; 841ba13f2c8SEric Biggers }; 842ba13f2c8SEric Biggers 843ba13f2c8SEric Biggers #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1 844ba13f2c8SEric Biggers #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2 845ba13f2c8SEric Biggers 846ba13f2c8SEric Biggers struct fscrypt_key_specifier { 847ba13f2c8SEric Biggers __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */ 848ba13f2c8SEric Biggers __u32 __reserved; 849ba13f2c8SEric Biggers union { 850ba13f2c8SEric Biggers __u8 __reserved[32]; /* reserve some extra space */ 851ba13f2c8SEric Biggers __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; 852ba13f2c8SEric Biggers __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; 853ba13f2c8SEric Biggers } u; 854ba13f2c8SEric Biggers }; 855ba13f2c8SEric Biggers 85693edd392SEric Biggers struct fscrypt_provisioning_key_payload { 85793edd392SEric Biggers __u32 type; 85893edd392SEric Biggers __u32 __reserved; 85993edd392SEric Biggers __u8 raw[]; 86093edd392SEric Biggers }; 86193edd392SEric Biggers 86274e2f8d3SMauro Carvalho Chehabstruct fscrypt_add_key_arg must be zeroed, then initialized 863ba13f2c8SEric Biggersas follows: 864ba13f2c8SEric Biggers 865ba13f2c8SEric Biggers- If the key is being added for use by v1 encryption policies, then 866ba13f2c8SEric Biggers ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and 867ba13f2c8SEric Biggers ``key_spec.u.descriptor`` must contain the descriptor of the key 868ba13f2c8SEric Biggers being added, corresponding to the value in the 86974e2f8d3SMauro Carvalho Chehab ``master_key_descriptor`` field of struct fscrypt_policy_v1. 87074e2f8d3SMauro Carvalho Chehab To add this type of key, the calling process must have the 87174e2f8d3SMauro Carvalho Chehab CAP_SYS_ADMIN capability in the initial user namespace. 872ba13f2c8SEric Biggers 873ba13f2c8SEric Biggers Alternatively, if the key is being added for use by v2 encryption 874ba13f2c8SEric Biggers policies, then ``key_spec.type`` must contain 875ba13f2c8SEric Biggers FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is 876ba13f2c8SEric Biggers an *output* field which the kernel fills in with a cryptographic 877ba13f2c8SEric Biggers hash of the key. To add this type of key, the calling process does 878ba13f2c8SEric Biggers not need any privileges. However, the number of keys that can be 879ba13f2c8SEric Biggers added is limited by the user's quota for the keyrings service (see 880ba13f2c8SEric Biggers ``Documentation/security/keys/core.rst``). 881ba13f2c8SEric Biggers 882ba13f2c8SEric Biggers- ``raw_size`` must be the size of the ``raw`` key provided, in bytes. 88393edd392SEric Biggers Alternatively, if ``key_id`` is nonzero, this field must be 0, since 88493edd392SEric Biggers in that case the size is implied by the specified Linux keyring key. 88593edd392SEric Biggers 88693edd392SEric Biggers- ``key_id`` is 0 if the raw key is given directly in the ``raw`` 88793edd392SEric Biggers field. Otherwise ``key_id`` is the ID of a Linux keyring key of 88874e2f8d3SMauro Carvalho Chehab type "fscrypt-provisioning" whose payload is 88974e2f8d3SMauro Carvalho Chehab struct fscrypt_provisioning_key_payload whose ``raw`` field contains 89074e2f8d3SMauro Carvalho Chehab the raw key and whose ``type`` field matches ``key_spec.type``. 89174e2f8d3SMauro Carvalho Chehab Since ``raw`` is variable-length, the total size of this key's 89274e2f8d3SMauro Carvalho Chehab payload must be ``sizeof(struct fscrypt_provisioning_key_payload)`` 89374e2f8d3SMauro Carvalho Chehab plus the raw key size. The process must have Search permission on 89474e2f8d3SMauro Carvalho Chehab this key. 89593edd392SEric Biggers 89693edd392SEric Biggers Most users should leave this 0 and specify the raw key directly. 89793edd392SEric Biggers The support for specifying a Linux keyring key is intended mainly to 89893edd392SEric Biggers allow re-adding keys after a filesystem is unmounted and re-mounted, 89993edd392SEric Biggers without having to store the raw keys in userspace memory. 900ba13f2c8SEric Biggers 901ba13f2c8SEric Biggers- ``raw`` is a variable-length field which must contain the actual 90293edd392SEric Biggers key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is 90393edd392SEric Biggers nonzero, then this field is unused. 904ba13f2c8SEric Biggers 905ba13f2c8SEric BiggersFor v2 policy keys, the kernel keeps track of which user (identified 906ba13f2c8SEric Biggersby effective user ID) added the key, and only allows the key to be 907ba13f2c8SEric Biggersremoved by that user --- or by "root", if they use 908ba13f2c8SEric Biggers`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_. 909ba13f2c8SEric Biggers 910ba13f2c8SEric BiggersHowever, if another user has added the key, it may be desirable to 911ba13f2c8SEric Biggersprevent that other user from unexpectedly removing it. Therefore, 912ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key 913ba13f2c8SEric Biggers*again*, even if it's already added by other user(s). In this case, 914ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the 915ba13f2c8SEric Biggerscurrent user, rather than actually add the key again (but the raw key 916ba13f2c8SEric Biggersmust still be provided, as a proof of knowledge). 917ba13f2c8SEric Biggers 918ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to 919ba13f2c8SEric Biggersthe key was either added or already exists. 920ba13f2c8SEric Biggers 921ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors: 922ba13f2c8SEric Biggers 923ba13f2c8SEric Biggers- ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the 924ba13f2c8SEric Biggers caller does not have the CAP_SYS_ADMIN capability in the initial 92593edd392SEric Biggers user namespace; or the raw key was specified by Linux key ID but the 92693edd392SEric Biggers process lacks Search permission on the key. 927ba13f2c8SEric Biggers- ``EDQUOT``: the key quota for this user would be exceeded by adding 928ba13f2c8SEric Biggers the key 929ba13f2c8SEric Biggers- ``EINVAL``: invalid key size or key specifier type, or reserved bits 930ba13f2c8SEric Biggers were set 93193edd392SEric Biggers- ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the 93293edd392SEric Biggers key has the wrong type 93393edd392SEric Biggers- ``ENOKEY``: the raw key was specified by Linux key ID, but no key 93493edd392SEric Biggers exists with that ID 935ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 936ba13f2c8SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 937ba13f2c8SEric Biggers support for this filesystem, or the filesystem superblock has not 938ba13f2c8SEric Biggers had encryption enabled on it 939ba13f2c8SEric Biggers 940ba13f2c8SEric BiggersLegacy method 941ba13f2c8SEric Biggers~~~~~~~~~~~~~ 942ba13f2c8SEric Biggers 943ba13f2c8SEric BiggersFor v1 encryption policies, a master encryption key can also be 944ba13f2c8SEric Biggersprovided by adding it to a process-subscribed keyring, e.g. to a 945ba13f2c8SEric Biggerssession keyring, or to a user keyring if the user keyring is linked 946ba13f2c8SEric Biggersinto the session keyring. 947ba13f2c8SEric Biggers 948ba13f2c8SEric BiggersThis method is deprecated (and not supported for v2 encryption 949ba13f2c8SEric Biggerspolicies) for several reasons. First, it cannot be used in 950ba13f2c8SEric Biggerscombination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_), 951ba13f2c8SEric Biggersso for removing a key a workaround such as keyctl_unlink() in 952ba13f2c8SEric Biggerscombination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would 953ba13f2c8SEric Biggershave to be used. Second, it doesn't match the fact that the 954ba13f2c8SEric Biggerslocked/unlocked status of encrypted files (i.e. whether they appear to 955ba13f2c8SEric Biggersbe in plaintext form or in ciphertext form) is global. This mismatch 956ba13f2c8SEric Biggershas caused much confusion as well as real problems when processes 957ba13f2c8SEric Biggersrunning under different UIDs, such as a ``sudo`` command, need to 958ba13f2c8SEric Biggersaccess encrypted files. 959ba13f2c8SEric Biggers 960ba13f2c8SEric BiggersNevertheless, to add a key to one of the process-subscribed keyrings, 961ba13f2c8SEric Biggersthe add_key() system call can be used (see: 962f4f864c1SEric Biggers``Documentation/security/keys/core.rst``). The key type must be 963f4f864c1SEric Biggers"logon"; keys of this type are kept in kernel memory and cannot be 964f4f864c1SEric Biggersread back by userspace. The key description must be "fscrypt:" 965f4f864c1SEric Biggersfollowed by the 16-character lower case hex representation of the 966f4f864c1SEric Biggers``master_key_descriptor`` that was set in the encryption policy. The 967f4f864c1SEric Biggerskey payload must conform to the following structure:: 968f4f864c1SEric Biggers 9692336d0deSEric Biggers #define FSCRYPT_MAX_KEY_SIZE 64 970f4f864c1SEric Biggers 971f4f864c1SEric Biggers struct fscrypt_key { 972ba13f2c8SEric Biggers __u32 mode; 973ba13f2c8SEric Biggers __u8 raw[FSCRYPT_MAX_KEY_SIZE]; 974ba13f2c8SEric Biggers __u32 size; 975f4f864c1SEric Biggers }; 976f4f864c1SEric Biggers 977f4f864c1SEric Biggers``mode`` is ignored; just set it to 0. The actual key is provided in 978f4f864c1SEric Biggers``raw`` with ``size`` indicating its size in bytes. That is, the 979f4f864c1SEric Biggersbytes ``raw[0..size-1]`` (inclusive) are the actual key. 980f4f864c1SEric Biggers 981f4f864c1SEric BiggersThe key description prefix "fscrypt:" may alternatively be replaced 982f4f864c1SEric Biggerswith a filesystem-specific prefix such as "ext4:". However, the 983f4f864c1SEric Biggersfilesystem-specific prefixes are deprecated and should not be used in 984f4f864c1SEric Biggersnew programs. 985f4f864c1SEric Biggers 986ba13f2c8SEric BiggersRemoving keys 987ba13f2c8SEric Biggers------------- 988f4f864c1SEric Biggers 989ba13f2c8SEric BiggersTwo ioctls are available for removing a key that was added by 990ba13f2c8SEric Biggers`FS_IOC_ADD_ENCRYPTION_KEY`_: 991ba13f2c8SEric Biggers 992ba13f2c8SEric Biggers- `FS_IOC_REMOVE_ENCRYPTION_KEY`_ 993ba13f2c8SEric Biggers- `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_ 994ba13f2c8SEric Biggers 995ba13f2c8SEric BiggersThese two ioctls differ only in cases where v2 policy keys are added 996ba13f2c8SEric Biggersor removed by non-root users. 997ba13f2c8SEric Biggers 998ba13f2c8SEric BiggersThese ioctls don't work on keys that were added via the legacy 999ba13f2c8SEric Biggersprocess-subscribed keyrings mechanism. 1000ba13f2c8SEric Biggers 1001ba13f2c8SEric BiggersBefore using these ioctls, read the `Kernel memory compromise`_ 1002ba13f2c8SEric Biggerssection for a discussion of the security goals and limitations of 1003ba13f2c8SEric Biggersthese ioctls. 1004ba13f2c8SEric Biggers 1005ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY 1006ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1007ba13f2c8SEric Biggers 1008ba13f2c8SEric BiggersThe FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master 1009ba13f2c8SEric Biggersencryption key from the filesystem, and possibly removes the key 1010ba13f2c8SEric Biggersitself. It can be executed on any file or directory on the target 1011ba13f2c8SEric Biggersfilesystem, but using the filesystem's root directory is recommended. 101274e2f8d3SMauro Carvalho ChehabIt takes in a pointer to struct fscrypt_remove_key_arg, defined 101374e2f8d3SMauro Carvalho Chehabas follows:: 1014ba13f2c8SEric Biggers 1015ba13f2c8SEric Biggers struct fscrypt_remove_key_arg { 1016ba13f2c8SEric Biggers struct fscrypt_key_specifier key_spec; 1017ba13f2c8SEric Biggers #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001 1018ba13f2c8SEric Biggers #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002 1019ba13f2c8SEric Biggers __u32 removal_status_flags; /* output */ 1020ba13f2c8SEric Biggers __u32 __reserved[5]; 1021ba13f2c8SEric Biggers }; 1022ba13f2c8SEric Biggers 1023ba13f2c8SEric BiggersThis structure must be zeroed, then initialized as follows: 1024ba13f2c8SEric Biggers 1025ba13f2c8SEric Biggers- The key to remove is specified by ``key_spec``: 1026ba13f2c8SEric Biggers 1027ba13f2c8SEric Biggers - To remove a key used by v1 encryption policies, set 1028ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill 1029ba13f2c8SEric Biggers in ``key_spec.u.descriptor``. To remove this type of key, the 1030ba13f2c8SEric Biggers calling process must have the CAP_SYS_ADMIN capability in the 1031ba13f2c8SEric Biggers initial user namespace. 1032ba13f2c8SEric Biggers 1033ba13f2c8SEric Biggers - To remove a key used by v2 encryption policies, set 1034ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill 1035ba13f2c8SEric Biggers in ``key_spec.u.identifier``. 1036ba13f2c8SEric Biggers 1037ba13f2c8SEric BiggersFor v2 policy keys, this ioctl is usable by non-root users. However, 1038ba13f2c8SEric Biggersto make this possible, it actually just removes the current user's 1039ba13f2c8SEric Biggersclaim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY. 1040ba13f2c8SEric BiggersOnly after all claims are removed is the key really removed. 1041ba13f2c8SEric Biggers 1042ba13f2c8SEric BiggersFor example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000, 1043ba13f2c8SEric Biggersthen the key will be "claimed" by uid 1000, and 1044ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if 1045ba13f2c8SEric Biggersboth uids 1000 and 2000 added the key, then for each uid 1046ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only 1047ba13f2c8SEric Biggersonce *both* are removed is the key really removed. (Think of it like 1048ba13f2c8SEric Biggersunlinking a file that may have hard links.) 1049ba13f2c8SEric Biggers 1050ba13f2c8SEric BiggersIf FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also 1051ba13f2c8SEric Biggerstry to "lock" all files that had been unlocked with the key. It won't 1052ba13f2c8SEric Biggerslock files that are still in-use, so this ioctl is expected to be used 1053ba13f2c8SEric Biggersin cooperation with userspace ensuring that none of the files are 1054ba13f2c8SEric Biggersstill open. However, if necessary, this ioctl can be executed again 1055ba13f2c8SEric Biggerslater to retry locking any remaining files. 1056ba13f2c8SEric Biggers 1057ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed 1058ba13f2c8SEric Biggers(but may still have files remaining to be locked), the user's claim to 1059ba13f2c8SEric Biggersthe key was removed, or the key was already removed but had files 1060ba13f2c8SEric Biggersremaining to be the locked so the ioctl retried locking them. In any 1061ba13f2c8SEric Biggersof these cases, ``removal_status_flags`` is filled in with the 1062ba13f2c8SEric Biggersfollowing informational status flags: 1063ba13f2c8SEric Biggers 1064ba13f2c8SEric Biggers- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s) 1065ba13f2c8SEric Biggers are still in-use. Not guaranteed to be set in the case where only 1066ba13f2c8SEric Biggers the user's claim to the key was removed. 1067ba13f2c8SEric Biggers- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the 1068ba13f2c8SEric Biggers user's claim to the key was removed, not the key itself 1069ba13f2c8SEric Biggers 1070ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors: 1071ba13f2c8SEric Biggers 1072ba13f2c8SEric Biggers- ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type 1073ba13f2c8SEric Biggers was specified, but the caller does not have the CAP_SYS_ADMIN 1074ba13f2c8SEric Biggers capability in the initial user namespace 1075ba13f2c8SEric Biggers- ``EINVAL``: invalid key specifier type, or reserved bits were set 1076ba13f2c8SEric Biggers- ``ENOKEY``: the key object was not found at all, i.e. it was never 1077ba13f2c8SEric Biggers added in the first place or was already fully removed including all 1078ba13f2c8SEric Biggers files locked; or, the user does not have a claim to the key (but 1079ba13f2c8SEric Biggers someone else does). 1080ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 1081ba13f2c8SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 1082ba13f2c8SEric Biggers support for this filesystem, or the filesystem superblock has not 1083ba13f2c8SEric Biggers had encryption enabled on it 1084ba13f2c8SEric Biggers 1085ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS 1086ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1087ba13f2c8SEric Biggers 1088ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as 1089ba13f2c8SEric Biggers`FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the 1090ba13f2c8SEric BiggersALL_USERS version of the ioctl will remove all users' claims to the 1091ba13f2c8SEric Biggerskey, not just the current user's. I.e., the key itself will always be 1092ba13f2c8SEric Biggersremoved, no matter how many users have added it. This difference is 1093ba13f2c8SEric Biggersonly meaningful if non-root users are adding and removing keys. 1094ba13f2c8SEric Biggers 1095ba13f2c8SEric BiggersBecause of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires 1096ba13f2c8SEric Biggers"root", namely the CAP_SYS_ADMIN capability in the initial user 1097ba13f2c8SEric Biggersnamespace. Otherwise it will fail with EACCES. 1098ba13f2c8SEric Biggers 1099ba13f2c8SEric BiggersGetting key status 1100ba13f2c8SEric Biggers------------------ 1101ba13f2c8SEric Biggers 1102ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_KEY_STATUS 1103ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1104ba13f2c8SEric Biggers 1105ba13f2c8SEric BiggersThe FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a 1106ba13f2c8SEric Biggersmaster encryption key. It can be executed on any file or directory on 1107ba13f2c8SEric Biggersthe target filesystem, but using the filesystem's root directory is 110874e2f8d3SMauro Carvalho Chehabrecommended. It takes in a pointer to 110974e2f8d3SMauro Carvalho Chehabstruct fscrypt_get_key_status_arg, defined as follows:: 1110ba13f2c8SEric Biggers 1111ba13f2c8SEric Biggers struct fscrypt_get_key_status_arg { 1112ba13f2c8SEric Biggers /* input */ 1113ba13f2c8SEric Biggers struct fscrypt_key_specifier key_spec; 1114ba13f2c8SEric Biggers __u32 __reserved[6]; 1115ba13f2c8SEric Biggers 1116ba13f2c8SEric Biggers /* output */ 1117ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_ABSENT 1 1118ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_PRESENT 2 1119ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3 1120ba13f2c8SEric Biggers __u32 status; 1121ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001 1122ba13f2c8SEric Biggers __u32 status_flags; 1123ba13f2c8SEric Biggers __u32 user_count; 1124ba13f2c8SEric Biggers __u32 __out_reserved[13]; 1125ba13f2c8SEric Biggers }; 1126ba13f2c8SEric Biggers 1127ba13f2c8SEric BiggersThe caller must zero all input fields, then fill in ``key_spec``: 1128ba13f2c8SEric Biggers 1129ba13f2c8SEric Biggers - To get the status of a key for v1 encryption policies, set 1130ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill 1131ba13f2c8SEric Biggers in ``key_spec.u.descriptor``. 1132ba13f2c8SEric Biggers 1133ba13f2c8SEric Biggers - To get the status of a key for v2 encryption policies, set 1134ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill 1135ba13f2c8SEric Biggers in ``key_spec.u.identifier``. 1136ba13f2c8SEric Biggers 1137ba13f2c8SEric BiggersOn success, 0 is returned and the kernel fills in the output fields: 1138ba13f2c8SEric Biggers 1139ba13f2c8SEric Biggers- ``status`` indicates whether the key is absent, present, or 114015baf554SEric Biggers incompletely removed. Incompletely removed means that removal has 114115baf554SEric Biggers been initiated, but some files are still in use; i.e., 1142ba13f2c8SEric Biggers `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational 1143ba13f2c8SEric Biggers status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY. 1144ba13f2c8SEric Biggers 1145ba13f2c8SEric Biggers- ``status_flags`` can contain the following flags: 1146ba13f2c8SEric Biggers 1147ba13f2c8SEric Biggers - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key 1148ba13f2c8SEric Biggers has added by the current user. This is only set for keys 1149ba13f2c8SEric Biggers identified by ``identifier`` rather than by ``descriptor``. 1150ba13f2c8SEric Biggers 1151ba13f2c8SEric Biggers- ``user_count`` specifies the number of users who have added the key. 1152ba13f2c8SEric Biggers This is only set for keys identified by ``identifier`` rather than 1153ba13f2c8SEric Biggers by ``descriptor``. 1154ba13f2c8SEric Biggers 1155ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors: 1156ba13f2c8SEric Biggers 1157ba13f2c8SEric Biggers- ``EINVAL``: invalid key specifier type, or reserved bits were set 1158ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 1159ba13f2c8SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 1160ba13f2c8SEric Biggers support for this filesystem, or the filesystem superblock has not 1161ba13f2c8SEric Biggers had encryption enabled on it 1162ba13f2c8SEric Biggers 1163ba13f2c8SEric BiggersAmong other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful 1164ba13f2c8SEric Biggersfor determining whether the key for a given encrypted directory needs 1165ba13f2c8SEric Biggersto be added before prompting the user for the passphrase needed to 1166ba13f2c8SEric Biggersderive the key. 1167ba13f2c8SEric Biggers 1168ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in 1169ba13f2c8SEric Biggersthe filesystem-level keyring, i.e. the keyring managed by 1170ba13f2c8SEric Biggers`FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It 1171ba13f2c8SEric Biggerscannot get the status of a key that has only been added for use by v1 1172ba13f2c8SEric Biggersencryption policies using the legacy mechanism involving 1173ba13f2c8SEric Biggersprocess-subscribed keyrings. 1174f4f864c1SEric Biggers 1175f4f864c1SEric BiggersAccess semantics 1176f4f864c1SEric Biggers================ 1177f4f864c1SEric Biggers 1178f4f864c1SEric BiggersWith the key 1179f4f864c1SEric Biggers------------ 1180f4f864c1SEric Biggers 1181f4f864c1SEric BiggersWith the encryption key, encrypted regular files, directories, and 1182f4f864c1SEric Biggerssymlinks behave very similarly to their unencrypted counterparts --- 1183f4f864c1SEric Biggersafter all, the encryption is intended to be transparent. However, 1184f4f864c1SEric Biggersastute users may notice some differences in behavior: 1185f4f864c1SEric Biggers 1186f4f864c1SEric Biggers- Unencrypted files, or files encrypted with a different encryption 1187f4f864c1SEric Biggers policy (i.e. different key, modes, or flags), cannot be renamed or 1188f4f864c1SEric Biggers linked into an encrypted directory; see `Encryption policy 1189f5e55e77SEric Biggers enforcement`_. Attempts to do so will fail with EXDEV. However, 1190f4f864c1SEric Biggers encrypted files can be renamed within an encrypted directory, or 1191f4f864c1SEric Biggers into an unencrypted directory. 1192f4f864c1SEric Biggers 1193f5e55e77SEric Biggers Note: "moving" an unencrypted file into an encrypted directory, e.g. 1194f5e55e77SEric Biggers with the `mv` program, is implemented in userspace by a copy 1195f5e55e77SEric Biggers followed by a delete. Be aware that the original unencrypted data 1196f5e55e77SEric Biggers may remain recoverable from free space on the disk; prefer to keep 1197f5e55e77SEric Biggers all files encrypted from the very beginning. The `shred` program 1198f5e55e77SEric Biggers may be used to overwrite the source files but isn't guaranteed to be 1199f5e55e77SEric Biggers effective on all filesystems and storage devices. 1200f5e55e77SEric Biggers 1201cdaa1b19SEric Biggers- Direct I/O is supported on encrypted files only under some 1202cdaa1b19SEric Biggers circumstances. For details, see `Direct I/O support`_. 1203f4f864c1SEric Biggers 1204457b1e35SEric Biggers- The fallocate operations FALLOC_FL_COLLAPSE_RANGE and 1205457b1e35SEric Biggers FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will 1206457b1e35SEric Biggers fail with EOPNOTSUPP. 1207f4f864c1SEric Biggers 1208f4f864c1SEric Biggers- Online defragmentation of encrypted files is not supported. The 1209f4f864c1SEric Biggers EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with 1210f4f864c1SEric Biggers EOPNOTSUPP. 1211f4f864c1SEric Biggers 1212f4f864c1SEric Biggers- The ext4 filesystem does not support data journaling with encrypted 1213f4f864c1SEric Biggers regular files. It will fall back to ordered data mode instead. 1214f4f864c1SEric Biggers 1215f4f864c1SEric Biggers- DAX (Direct Access) is not supported on encrypted files. 1216f4f864c1SEric Biggers 12172f46a2bcSEric Biggers- The maximum length of an encrypted symlink is 2 bytes shorter than 12182f46a2bcSEric Biggers the maximum length of an unencrypted symlink. For example, on an 12192f46a2bcSEric Biggers EXT4 filesystem with a 4K block size, unencrypted symlinks can be up 12202f46a2bcSEric Biggers to 4095 bytes long, while encrypted symlinks can only be up to 4093 12212f46a2bcSEric Biggers bytes long (both lengths excluding the terminating null). 1222f4f864c1SEric Biggers 1223f4f864c1SEric BiggersNote that mmap *is* supported. This is possible because the pagecache 1224f4f864c1SEric Biggersfor an encrypted file contains the plaintext, not the ciphertext. 1225f4f864c1SEric Biggers 1226f4f864c1SEric BiggersWithout the key 1227f4f864c1SEric Biggers--------------- 1228f4f864c1SEric Biggers 1229f4f864c1SEric BiggersSome filesystem operations may be performed on encrypted regular 1230f4f864c1SEric Biggersfiles, directories, and symlinks even before their encryption key has 1231ba13f2c8SEric Biggersbeen added, or after their encryption key has been removed: 1232f4f864c1SEric Biggers 1233f4f864c1SEric Biggers- File metadata may be read, e.g. using stat(). 1234f4f864c1SEric Biggers 1235f4f864c1SEric Biggers- Directories may be listed, in which case the filenames will be 1236f4f864c1SEric Biggers listed in an encoded form derived from their ciphertext. The 1237f4f864c1SEric Biggers current encoding algorithm is described in `Filename hashing and 1238f4f864c1SEric Biggers encoding`_. The algorithm is subject to change, but it is 1239f4f864c1SEric Biggers guaranteed that the presented filenames will be no longer than 1240f4f864c1SEric Biggers NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and 1241f4f864c1SEric Biggers will uniquely identify directory entries. 1242f4f864c1SEric Biggers 1243f4f864c1SEric Biggers The ``.`` and ``..`` directory entries are special. They are always 1244f4f864c1SEric Biggers present and are not encrypted or encoded. 1245f4f864c1SEric Biggers 1246f4f864c1SEric Biggers- Files may be deleted. That is, nondirectory files may be deleted 1247f4f864c1SEric Biggers with unlink() as usual, and empty directories may be deleted with 1248f4f864c1SEric Biggers rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as 1249f4f864c1SEric Biggers expected. 1250f4f864c1SEric Biggers 1251f4f864c1SEric Biggers- Symlink targets may be read and followed, but they will be presented 1252f4f864c1SEric Biggers in encrypted form, similar to filenames in directories. Hence, they 1253f4f864c1SEric Biggers are unlikely to point to anywhere useful. 1254f4f864c1SEric Biggers 1255f4f864c1SEric BiggersWithout the key, regular files cannot be opened or truncated. 1256f4f864c1SEric BiggersAttempts to do so will fail with ENOKEY. This implies that any 1257f4f864c1SEric Biggersregular file operations that require a file descriptor, such as 1258f4f864c1SEric Biggersread(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. 1259f4f864c1SEric Biggers 1260f4f864c1SEric BiggersAlso without the key, files of any type (including directories) cannot 1261f4f864c1SEric Biggersbe created or linked into an encrypted directory, nor can a name in an 1262f4f864c1SEric Biggersencrypted directory be the source or target of a rename, nor can an 1263f4f864c1SEric BiggersO_TMPFILE temporary file be created in an encrypted directory. All 1264f4f864c1SEric Biggerssuch operations will fail with ENOKEY. 1265f4f864c1SEric Biggers 1266f4f864c1SEric BiggersIt is not currently possible to backup and restore encrypted files 1267f4f864c1SEric Biggerswithout the encryption key. This would require special APIs which 1268f4f864c1SEric Biggershave not yet been implemented. 1269f4f864c1SEric Biggers 1270f4f864c1SEric BiggersEncryption policy enforcement 1271f4f864c1SEric Biggers============================= 1272f4f864c1SEric Biggers 1273f4f864c1SEric BiggersAfter an encryption policy has been set on a directory, all regular 1274f4f864c1SEric Biggersfiles, directories, and symbolic links created in that directory 1275f4f864c1SEric Biggers(recursively) will inherit that encryption policy. Special files --- 1276f4f864c1SEric Biggersthat is, named pipes, device nodes, and UNIX domain sockets --- will 1277f4f864c1SEric Biggersnot be encrypted. 1278f4f864c1SEric Biggers 1279f4f864c1SEric BiggersExcept for those special files, it is forbidden to have unencrypted 1280f4f864c1SEric Biggersfiles, or files encrypted with a different encryption policy, in an 1281f4f864c1SEric Biggersencrypted directory tree. Attempts to link or rename such a file into 1282f5e55e77SEric Biggersan encrypted directory will fail with EXDEV. This is also enforced 1283f4f864c1SEric Biggersduring ->lookup() to provide limited protection against offline 1284f4f864c1SEric Biggersattacks that try to disable or downgrade encryption in known locations 1285f4f864c1SEric Biggerswhere applications may later write sensitive data. It is recommended 1286f4f864c1SEric Biggersthat systems implementing a form of "verified boot" take advantage of 1287f4f864c1SEric Biggersthis by validating all top-level encryption policies prior to access. 1288f4f864c1SEric Biggers 1289abb861faSEric BiggersInline encryption support 1290abb861faSEric Biggers========================= 1291abb861faSEric Biggers 1292abb861faSEric BiggersBy default, fscrypt uses the kernel crypto API for all cryptographic 1293abb861faSEric Biggersoperations (other than HKDF, which fscrypt partially implements 1294abb861faSEric Biggersitself). The kernel crypto API supports hardware crypto accelerators, 1295abb861faSEric Biggersbut only ones that work in the traditional way where all inputs and 1296abb861faSEric Biggersoutputs (e.g. plaintexts and ciphertexts) are in memory. fscrypt can 1297abb861faSEric Biggerstake advantage of such hardware, but the traditional acceleration 1298abb861faSEric Biggersmodel isn't particularly efficient and fscrypt hasn't been optimized 1299abb861faSEric Biggersfor it. 1300abb861faSEric Biggers 1301abb861faSEric BiggersInstead, many newer systems (especially mobile SoCs) have *inline 1302abb861faSEric Biggersencryption hardware* that can encrypt/decrypt data while it is on its 1303abb861faSEric Biggersway to/from the storage device. Linux supports inline encryption 1304abb861faSEric Biggersthrough a set of extensions to the block layer called *blk-crypto*. 1305abb861faSEric Biggersblk-crypto allows filesystems to attach encryption contexts to bios 1306abb861faSEric Biggers(I/O requests) to specify how the data will be encrypted or decrypted 1307abb861faSEric Biggersin-line. For more information about blk-crypto, see 1308abb861faSEric Biggers:ref:`Documentation/block/inline-encryption.rst <inline_encryption>`. 1309abb861faSEric Biggers 1310abb861faSEric BiggersOn supported filesystems (currently ext4 and f2fs), fscrypt can use 1311abb861faSEric Biggersblk-crypto instead of the kernel crypto API to encrypt/decrypt file 1312abb861faSEric Biggerscontents. To enable this, set CONFIG_FS_ENCRYPTION_INLINE_CRYPT=y in 1313abb861faSEric Biggersthe kernel configuration, and specify the "inlinecrypt" mount option 1314abb861faSEric Biggerswhen mounting the filesystem. 1315abb861faSEric Biggers 1316abb861faSEric BiggersNote that the "inlinecrypt" mount option just specifies to use inline 1317abb861faSEric Biggersencryption when possible; it doesn't force its use. fscrypt will 1318abb861faSEric Biggersstill fall back to using the kernel crypto API on files where the 1319abb861faSEric Biggersinline encryption hardware doesn't have the needed crypto capabilities 1320abb861faSEric Biggers(e.g. support for the needed encryption algorithm and data unit size) 1321abb861faSEric Biggersand where blk-crypto-fallback is unusable. (For blk-crypto-fallback 1322abb861faSEric Biggersto be usable, it must be enabled in the kernel configuration with 1323abb861faSEric BiggersCONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y.) 1324abb861faSEric Biggers 1325abb861faSEric BiggersCurrently fscrypt always uses the filesystem block size (which is 1326abb861faSEric Biggersusually 4096 bytes) as the data unit size. Therefore, it can only use 1327abb861faSEric Biggersinline encryption hardware that supports that data unit size. 1328abb861faSEric Biggers 1329abb861faSEric BiggersInline encryption doesn't affect the ciphertext or other aspects of 1330abb861faSEric Biggersthe on-disk format, so users may freely switch back and forth between 1331abb861faSEric Biggersusing "inlinecrypt" and not using "inlinecrypt". 1332abb861faSEric Biggers 1333cdaa1b19SEric BiggersDirect I/O support 1334cdaa1b19SEric Biggers================== 1335cdaa1b19SEric Biggers 1336cdaa1b19SEric BiggersFor direct I/O on an encrypted file to work, the following conditions 1337cdaa1b19SEric Biggersmust be met (in addition to the conditions for direct I/O on an 1338cdaa1b19SEric Biggersunencrypted file): 1339cdaa1b19SEric Biggers 1340cdaa1b19SEric Biggers* The file must be using inline encryption. Usually this means that 1341cdaa1b19SEric Biggers the filesystem must be mounted with ``-o inlinecrypt`` and inline 1342cdaa1b19SEric Biggers encryption hardware must be present. However, a software fallback 1343cdaa1b19SEric Biggers is also available. For details, see `Inline encryption support`_. 1344cdaa1b19SEric Biggers 1345cdaa1b19SEric Biggers* The I/O request must be fully aligned to the filesystem block size. 1346cdaa1b19SEric Biggers This means that the file position the I/O is targeting, the lengths 1347cdaa1b19SEric Biggers of all I/O segments, and the memory addresses of all I/O buffers 1348cdaa1b19SEric Biggers must be multiples of this value. Note that the filesystem block 1349cdaa1b19SEric Biggers size may be greater than the logical block size of the block device. 1350cdaa1b19SEric Biggers 1351cdaa1b19SEric BiggersIf either of the above conditions is not met, then direct I/O on the 1352cdaa1b19SEric Biggersencrypted file will fall back to buffered I/O. 1353cdaa1b19SEric Biggers 1354f4f864c1SEric BiggersImplementation details 1355f4f864c1SEric Biggers====================== 1356f4f864c1SEric Biggers 1357f4f864c1SEric BiggersEncryption context 1358f4f864c1SEric Biggers------------------ 1359f4f864c1SEric Biggers 136074e2f8d3SMauro Carvalho ChehabAn encryption policy is represented on-disk by 136174e2f8d3SMauro Carvalho Chehabstruct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to 136274e2f8d3SMauro Carvalho Chehabindividual filesystems to decide where to store it, but normally it 136374e2f8d3SMauro Carvalho Chehabwould be stored in a hidden extended attribute. It should *not* be 1364ba13f2c8SEric Biggersexposed by the xattr-related system calls such as getxattr() and 1365ba13f2c8SEric Biggerssetxattr() because of the special semantics of the encryption xattr. 1366ba13f2c8SEric Biggers(In particular, there would be much confusion if an encryption policy 1367ba13f2c8SEric Biggerswere to be added to or removed from anything other than an empty 1368ba13f2c8SEric Biggersdirectory.) These structs are defined as follows:: 1369f4f864c1SEric Biggers 13701d6217a4SEric Biggers #define FSCRYPT_FILE_NONCE_SIZE 16 1371f4f864c1SEric Biggers 1372ba13f2c8SEric Biggers #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 1373ba13f2c8SEric Biggers struct fscrypt_context_v1 { 1374ba13f2c8SEric Biggers u8 version; 1375f4f864c1SEric Biggers u8 contents_encryption_mode; 1376f4f864c1SEric Biggers u8 filenames_encryption_mode; 1377f4f864c1SEric Biggers u8 flags; 13782336d0deSEric Biggers u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; 13791d6217a4SEric Biggers u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; 1380f4f864c1SEric Biggers }; 1381f4f864c1SEric Biggers 1382ba13f2c8SEric Biggers #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 1383ba13f2c8SEric Biggers struct fscrypt_context_v2 { 1384ba13f2c8SEric Biggers u8 version; 1385ba13f2c8SEric Biggers u8 contents_encryption_mode; 1386ba13f2c8SEric Biggers u8 filenames_encryption_mode; 1387ba13f2c8SEric Biggers u8 flags; 138833318c0eSEric Biggers u8 log2_data_unit_size; 138933318c0eSEric Biggers u8 __reserved[3]; 1390ba13f2c8SEric Biggers u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; 13911d6217a4SEric Biggers u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; 1392ba13f2c8SEric Biggers }; 1393ba13f2c8SEric Biggers 1394ba13f2c8SEric BiggersThe context structs contain the same information as the corresponding 1395ba13f2c8SEric Biggerspolicy structs (see `Setting an encryption policy`_), except that the 1396ba13f2c8SEric Biggerscontext structs also contain a nonce. The nonce is randomly generated 1397ba13f2c8SEric Biggersby the kernel and is used as KDF input or as a tweak to cause 1398f592efe7SEric Biggersdifferent files to be encrypted differently; see `Per-file encryption 1399f592efe7SEric Biggerskeys`_ and `DIRECT_KEY policies`_. 1400f4f864c1SEric Biggers 1401f4f864c1SEric BiggersData path changes 1402f4f864c1SEric Biggers----------------- 1403f4f864c1SEric Biggers 1404abb861faSEric BiggersWhen inline encryption is used, filesystems just need to associate 1405abb861faSEric Biggersencryption contexts with bios to specify how the block layer or the 1406abb861faSEric Biggersinline encryption hardware will encrypt/decrypt the file contents. 1407abb861faSEric Biggers 1408abb861faSEric BiggersWhen inline encryption isn't used, filesystems must encrypt/decrypt 1409abb861faSEric Biggersthe file contents themselves, as described below: 1410abb861faSEric Biggers 141108830c8bSMatthew Wilcox (Oracle)For the read path (->read_folio()) of regular files, filesystems can 1412f4f864c1SEric Biggersread the ciphertext into the page cache and decrypt it in-place. The 141351e4e315SEric Biggersfolio lock must be held until decryption has finished, to prevent the 141451e4e315SEric Biggersfolio from becoming visible to userspace prematurely. 1415f4f864c1SEric Biggers 1416f4f864c1SEric BiggersFor the write path (->writepage()) of regular files, filesystems 1417f4f864c1SEric Biggerscannot encrypt data in-place in the page cache, since the cached 1418f4f864c1SEric Biggersplaintext must be preserved. Instead, filesystems must encrypt into a 1419f4f864c1SEric Biggerstemporary buffer or "bounce page", then write out the temporary 1420f4f864c1SEric Biggersbuffer. Some filesystems, such as UBIFS, already use temporary 1421f4f864c1SEric Biggersbuffers regardless of encryption. Other filesystems, such as ext4 and 1422f4f864c1SEric BiggersF2FS, have to allocate bounce pages specially for encryption. 1423f4f864c1SEric Biggers 1424f4f864c1SEric BiggersFilename hashing and encoding 1425f4f864c1SEric Biggers----------------------------- 1426f4f864c1SEric Biggers 1427f4f864c1SEric BiggersModern filesystems accelerate directory lookups by using indexed 1428f4f864c1SEric Biggersdirectories. An indexed directory is organized as a tree keyed by 1429f4f864c1SEric Biggersfilename hashes. When a ->lookup() is requested, the filesystem 1430f4f864c1SEric Biggersnormally hashes the filename being looked up so that it can quickly 1431f4f864c1SEric Biggersfind the corresponding directory entry, if any. 1432f4f864c1SEric Biggers 1433f4f864c1SEric BiggersWith encryption, lookups must be supported and efficient both with and 1434f4f864c1SEric Biggerswithout the encryption key. Clearly, it would not work to hash the 1435f4f864c1SEric Biggersplaintext filenames, since the plaintext filenames are unavailable 1436f4f864c1SEric Biggerswithout the key. (Hashing the plaintext filenames would also make it 1437f4f864c1SEric Biggersimpossible for the filesystem's fsck tool to optimize encrypted 1438f4f864c1SEric Biggersdirectories.) Instead, filesystems hash the ciphertext filenames, 1439f4f864c1SEric Biggersi.e. the bytes actually stored on-disk in the directory entries. When 1440f4f864c1SEric Biggersasked to do a ->lookup() with the key, the filesystem just encrypts 1441f4f864c1SEric Biggersthe user-supplied name to get the ciphertext. 1442f4f864c1SEric Biggers 1443f4f864c1SEric BiggersLookups without the key are more complicated. The raw ciphertext may 1444f4f864c1SEric Biggerscontain the ``\0`` and ``/`` characters, which are illegal in 1445ba47b515SEric Biggersfilenames. Therefore, readdir() must base64url-encode the ciphertext 1446ba47b515SEric Biggersfor presentation. For most filenames, this works fine; on ->lookup(), 1447ba47b515SEric Biggersthe filesystem just base64url-decodes the user-supplied name to get 1448ba47b515SEric Biggersback to the raw ciphertext. 1449f4f864c1SEric Biggers 1450ba47b515SEric BiggersHowever, for very long filenames, base64url encoding would cause the 1451f4f864c1SEric Biggersfilename length to exceed NAME_MAX. To prevent this, readdir() 1452f4f864c1SEric Biggersactually presents long filenames in an abbreviated form which encodes 1453f4f864c1SEric Biggersa strong "hash" of the ciphertext filename, along with the optional 1454f4f864c1SEric Biggersfilesystem-specific hash(es) needed for directory lookups. This 1455f4f864c1SEric Biggersallows the filesystem to still, with a high degree of confidence, map 1456f4f864c1SEric Biggersthe filename given in ->lookup() back to a particular directory entry 145774e2f8d3SMauro Carvalho Chehabthat was previously listed by readdir(). See 145874e2f8d3SMauro Carvalho Chehabstruct fscrypt_nokey_name in the source for more details. 1459f4f864c1SEric Biggers 1460f4f864c1SEric BiggersNote that the precise way that filenames are presented to userspace 1461f4f864c1SEric Biggerswithout the key is subject to change in the future. It is only meant 1462f4f864c1SEric Biggersas a way to temporarily present valid filenames so that commands like 1463f4f864c1SEric Biggers``rm -r`` work as expected on encrypted directories. 146405643363SEric Biggers 146505643363SEric BiggersTests 146605643363SEric Biggers===== 146705643363SEric Biggers 146805643363SEric BiggersTo test fscrypt, use xfstests, which is Linux's de facto standard 146905643363SEric Biggersfilesystem test suite. First, run all the tests in the "encrypt" 1470880253eaSSatya Tangiralagroup on the relevant filesystem(s). One can also run the tests 1471880253eaSSatya Tangiralawith the 'inlinecrypt' mount option to test the implementation for 1472880253eaSSatya Tangiralainline encryption support. For example, to test ext4 and 147305643363SEric Biggersf2fs encryption using `kvm-xfstests 147405643363SEric Biggers<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: 147505643363SEric Biggers 147605643363SEric Biggers kvm-xfstests -c ext4,f2fs -g encrypt 14775fee3609SSatya Tangirala kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt 147805643363SEric Biggers 147905643363SEric BiggersUBIFS encryption can also be tested this way, but it should be done in 148005643363SEric Biggersa separate command, and it takes some time for kvm-xfstests to set up 148105643363SEric Biggersemulated UBI volumes:: 148205643363SEric Biggers 148305643363SEric Biggers kvm-xfstests -c ubifs -g encrypt 148405643363SEric Biggers 148505643363SEric BiggersNo tests should fail. However, tests that use non-default encryption 148605643363SEric Biggersmodes (e.g. generic/549 and generic/550) will be skipped if the needed 148705643363SEric Biggersalgorithms were not built into the kernel's crypto API. Also, tests 148805643363SEric Biggersthat access the raw block device (e.g. generic/399, generic/548, 148905643363SEric Biggersgeneric/549, generic/550) will be skipped on UBIFS. 149005643363SEric Biggers 149105643363SEric BiggersBesides running the "encrypt" group tests, for ext4 and f2fs it's also 149205643363SEric Biggerspossible to run most xfstests with the "test_dummy_encryption" mount 149305643363SEric Biggersoption. This option causes all new files to be automatically 149405643363SEric Biggersencrypted with a dummy key, without having to make any API calls. 149505643363SEric BiggersThis tests the encrypted I/O paths more thoroughly. To do this with 149605643363SEric Biggerskvm-xfstests, use the "encrypt" filesystem configuration:: 149705643363SEric Biggers 149805643363SEric Biggers kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 14995fee3609SSatya Tangirala kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt 150005643363SEric Biggers 150105643363SEric BiggersBecause this runs many more tests than "-g encrypt" does, it takes 150205643363SEric Biggersmuch longer to run; so also consider using `gce-xfstests 150305643363SEric Biggers<https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_ 150405643363SEric Biggersinstead of kvm-xfstests:: 150505643363SEric Biggers 150605643363SEric Biggers gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 15075fee3609SSatya Tangirala gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt 1508