1f4f864c1SEric Biggers===================================== 2f4f864c1SEric BiggersFilesystem-level encryption (fscrypt) 3f4f864c1SEric Biggers===================================== 4f4f864c1SEric Biggers 5f4f864c1SEric BiggersIntroduction 6f4f864c1SEric Biggers============ 7f4f864c1SEric Biggers 8f4f864c1SEric Biggersfscrypt is a library which filesystems can hook into to support 9f4f864c1SEric Biggerstransparent encryption of files and directories. 10f4f864c1SEric Biggers 11f4f864c1SEric BiggersNote: "fscrypt" in this document refers to the kernel-level portion, 12f4f864c1SEric Biggersimplemented in ``fs/crypto/``, as opposed to the userspace tool 13f4f864c1SEric Biggers`fscrypt <https://github.com/google/fscrypt>`_. This document only 14f4f864c1SEric Biggerscovers the kernel-level portion. For command-line examples of how to 15f4f864c1SEric Biggersuse encryption, see the documentation for the userspace tool `fscrypt 16f4f864c1SEric Biggers<https://github.com/google/fscrypt>`_. Also, it is recommended to use 17f4f864c1SEric Biggersthe fscrypt userspace tool, or other existing userspace tools such as 18f4f864c1SEric Biggers`fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key 19f4f864c1SEric Biggersmanagement system 20f4f864c1SEric Biggers<https://source.android.com/security/encryption/file-based>`_, over 21f4f864c1SEric Biggersusing the kernel's API directly. Using existing tools reduces the 22f4f864c1SEric Biggerschance of introducing your own security bugs. (Nevertheless, for 23f4f864c1SEric Biggerscompleteness this documentation covers the kernel's API anyway.) 24f4f864c1SEric Biggers 25f4f864c1SEric BiggersUnlike dm-crypt, fscrypt operates at the filesystem level rather than 26f4f864c1SEric Biggersat the block device level. This allows it to encrypt different files 27f4f864c1SEric Biggerswith different keys and to have unencrypted files on the same 28f4f864c1SEric Biggersfilesystem. This is useful for multi-user systems where each user's 29f4f864c1SEric Biggersdata-at-rest needs to be cryptographically isolated from the others. 30f4f864c1SEric BiggersHowever, except for filenames, fscrypt does not encrypt filesystem 31f4f864c1SEric Biggersmetadata. 32f4f864c1SEric Biggers 33f4f864c1SEric BiggersUnlike eCryptfs, which is a stacked filesystem, fscrypt is integrated 34f4f864c1SEric Biggersdirectly into supported filesystems --- currently ext4, F2FS, and 35f4f864c1SEric BiggersUBIFS. This allows encrypted files to be read and written without 36f4f864c1SEric Biggerscaching both the decrypted and encrypted pages in the pagecache, 37f4f864c1SEric Biggersthereby nearly halving the memory used and bringing it in line with 38f4f864c1SEric Biggersunencrypted files. Similarly, half as many dentries and inodes are 39f4f864c1SEric Biggersneeded. eCryptfs also limits encrypted filenames to 143 bytes, 40f4f864c1SEric Biggerscausing application compatibility issues; fscrypt allows the full 255 41f4f864c1SEric Biggersbytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be 42f4f864c1SEric Biggersused by unprivileged users, with no need to mount anything. 43f4f864c1SEric Biggers 44f4f864c1SEric Biggersfscrypt does not support encrypting files in-place. Instead, it 45f4f864c1SEric Biggerssupports marking an empty directory as encrypted. Then, after 46f4f864c1SEric Biggersuserspace provides the key, all regular files, directories, and 47f4f864c1SEric Biggerssymbolic links created in that directory tree are transparently 48f4f864c1SEric Biggersencrypted. 49f4f864c1SEric Biggers 50f4f864c1SEric BiggersThreat model 51f4f864c1SEric Biggers============ 52f4f864c1SEric Biggers 53f4f864c1SEric BiggersOffline attacks 54f4f864c1SEric Biggers--------------- 55f4f864c1SEric Biggers 56f4f864c1SEric BiggersProvided that userspace chooses a strong encryption key, fscrypt 57f4f864c1SEric Biggersprotects the confidentiality of file contents and filenames in the 58f4f864c1SEric Biggersevent of a single point-in-time permanent offline compromise of the 59f4f864c1SEric Biggersblock device content. fscrypt does not protect the confidentiality of 60f4f864c1SEric Biggersnon-filename metadata, e.g. file sizes, file permissions, file 61f4f864c1SEric Biggerstimestamps, and extended attributes. Also, the existence and location 62f4f864c1SEric Biggersof holes (unallocated blocks which logically contain all zeroes) in 63f4f864c1SEric Biggersfiles is not protected. 64f4f864c1SEric Biggers 65f4f864c1SEric Biggersfscrypt is not guaranteed to protect confidentiality or authenticity 66f4f864c1SEric Biggersif an attacker is able to manipulate the filesystem offline prior to 67f4f864c1SEric Biggersan authorized user later accessing the filesystem. 68f4f864c1SEric Biggers 69f4f864c1SEric BiggersOnline attacks 70f4f864c1SEric Biggers-------------- 71f4f864c1SEric Biggers 72f4f864c1SEric Biggersfscrypt (and storage encryption in general) can only provide limited 73f4f864c1SEric Biggersprotection, if any at all, against online attacks. In detail: 74f4f864c1SEric Biggers 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 80f4f864c1SEric BiggersCryptographic API algorithms are. If a vulnerable algorithm is used, 81f4f864c1SEric Biggerssuch as a table-based implementation of AES, it may be possible for an 82f4f864c1SEric Biggersattacker to mount a side channel attack against the online system. 83f4f864c1SEric BiggersSide channel attacks may also be mounted against applications 84f4f864c1SEric Biggersconsuming 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 179f4f864c1SEric Biggersgreater of the key length needed by the contents and filenames 180f4f864c1SEric Biggersencryption modes being used. For example, if AES-256-XTS is used for 181f4f864c1SEric Biggerscontents encryption, the master key must be 64 bytes (512 bits). Note 182f4f864c1SEric Biggersthat the XTS mode is defined to require a key twice as long as that 183f4f864c1SEric Biggersrequired by the underlying block cipher. 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 237f4f864c1SEric BiggersPer-file keys 238f4f864c1SEric 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 2598094c3ceSEric BiggersIncluding the inode number in the IVs was considered. However, it was 2608094c3ceSEric Biggersrejected as it would have prevented ext4 filesystems from being 2618094c3ceSEric Biggersresized, and by itself still wouldn't have been sufficient to prevent 2628094c3ceSEric Biggersthe same key from being directly reused for both XTS and CTS-CBC. 2638094c3ceSEric Biggers 264ba13f2c8SEric BiggersDIRECT_KEY and per-mode keys 265ba13f2c8SEric Biggers---------------------------- 266ba13f2c8SEric Biggers 267ba13f2c8SEric BiggersThe Adiantum encryption mode (see `Encryption modes and usage`_) is 268ba13f2c8SEric Biggerssuitable for both contents and filenames encryption, and it accepts 269ba13f2c8SEric Biggerslong IVs --- long enough to hold both an 8-byte logical block number 270ba13f2c8SEric Biggersand a 16-byte per-file nonce. Also, the overhead of each Adiantum key 271ba13f2c8SEric Biggersis greater than that of an AES-256-XTS key. 272ba13f2c8SEric Biggers 273ba13f2c8SEric BiggersTherefore, to improve performance and save memory, for Adiantum a 274ba13f2c8SEric Biggers"direct key" configuration is supported. When the user has enabled 275ba13f2c8SEric Biggersthis by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy, 276ba13f2c8SEric Biggersper-file keys are not used. Instead, whenever any data (contents or 277ba13f2c8SEric Biggersfilenames) is encrypted, the file's 16-byte nonce is included in the 278ba13f2c8SEric BiggersIV. Moreover: 279ba13f2c8SEric Biggers 280ba13f2c8SEric Biggers- For v1 encryption policies, the encryption is done directly with the 281ba13f2c8SEric Biggers master key. Because of this, users **must not** use the same master 282ba13f2c8SEric Biggers key for any other purpose, even for other v1 policies. 283ba13f2c8SEric Biggers 284ba13f2c8SEric Biggers- For v2 encryption policies, the encryption is done with a per-mode 285ba13f2c8SEric Biggers key derived using the KDF. Users may use the same master key for 286ba13f2c8SEric Biggers other v2 encryption policies. 287ba13f2c8SEric Biggers 288ba13f2c8SEric BiggersKey identifiers 289ba13f2c8SEric Biggers--------------- 290ba13f2c8SEric Biggers 291ba13f2c8SEric BiggersFor master keys used for v2 encryption policies, a unique 16-byte "key 292ba13f2c8SEric Biggersidentifier" is also derived using the KDF. This value is stored in 293ba13f2c8SEric Biggersthe clear, since it is needed to reliably identify the key itself. 294ba13f2c8SEric Biggers 295f4f864c1SEric BiggersEncryption modes and usage 296f4f864c1SEric Biggers========================== 297f4f864c1SEric Biggers 298f4f864c1SEric Biggersfscrypt allows one encryption mode to be specified for file contents 299f4f864c1SEric Biggersand one encryption mode to be specified for filenames. Different 300f4f864c1SEric Biggersdirectory trees are permitted to use different encryption modes. 301f4f864c1SEric BiggersCurrently, the following pairs of encryption modes are supported: 302f4f864c1SEric Biggers 303f4f864c1SEric Biggers- AES-256-XTS for contents and AES-256-CTS-CBC for filenames 304f4f864c1SEric Biggers- AES-128-CBC for contents and AES-128-CTS-CBC for filenames 3058094c3ceSEric Biggers- Adiantum for both contents and filenames 306f4f864c1SEric Biggers 3078094c3ceSEric BiggersIf unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. 3088094c3ceSEric Biggers 309f4f864c1SEric BiggersAES-128-CBC was added only for low-powered embedded devices with 310adbd9b4dSEric Biggerscrypto accelerators such as CAAM or CESA that do not support XTS. To 311adbd9b4dSEric Biggersuse AES-128-CBC, CONFIG_CRYPTO_SHA256 (or another SHA-256 312adbd9b4dSEric Biggersimplementation) must be enabled so that ESSIV can be used. 313f4f864c1SEric Biggers 3148094c3ceSEric BiggersAdiantum is a (primarily) stream cipher-based mode that is fast even 3158094c3ceSEric Biggerson CPUs without dedicated crypto instructions. It's also a true 3168094c3ceSEric Biggerswide-block mode, unlike XTS. It can also eliminate the need to derive 3178094c3ceSEric Biggersper-file keys. However, it depends on the security of two primitives, 3188094c3ceSEric BiggersXChaCha12 and AES-256, rather than just one. See the paper 3198094c3ceSEric Biggers"Adiantum: length-preserving encryption for entry-level processors" 3208094c3ceSEric Biggers(https://eprint.iacr.org/2018/720.pdf) for more details. To use 3218094c3ceSEric BiggersAdiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast 3228094c3ceSEric Biggersimplementations of ChaCha and NHPoly1305 should be enabled, e.g. 3238094c3ceSEric BiggersCONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. 3248094c3ceSEric Biggers 325f4f864c1SEric BiggersNew encryption modes can be added relatively easily, without changes 326f4f864c1SEric Biggersto individual filesystems. However, authenticated encryption (AE) 327f4f864c1SEric Biggersmodes are not currently supported because of the difficulty of dealing 328f4f864c1SEric Biggerswith ciphertext expansion. 329f4f864c1SEric Biggers 3308094c3ceSEric BiggersContents encryption 3318094c3ceSEric Biggers------------------- 3328094c3ceSEric Biggers 333f4f864c1SEric BiggersFor file contents, each filesystem block is encrypted independently. 334f4f864c1SEric BiggersCurrently, only the case where the filesystem block size is equal to 3358094c3ceSEric Biggersthe system's page size (usually 4096 bytes) is supported. 336f4f864c1SEric Biggers 3378094c3ceSEric BiggersEach block's IV is set to the logical block number within the file as 3388094c3ceSEric Biggersa little endian number, except that: 339f4f864c1SEric Biggers 3408094c3ceSEric Biggers- With CBC mode encryption, ESSIV is also used. Specifically, each IV 3418094c3ceSEric Biggers is encrypted with AES-256 where the AES-256 key is the SHA-256 hash 3428094c3ceSEric Biggers of the file's data encryption key. 3438094c3ceSEric Biggers 3442336d0deSEric Biggers- In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY 3452336d0deSEric Biggers set in the fscrypt_policy), the file's nonce is also appended to the 3462336d0deSEric Biggers IV. Currently this is only allowed with the Adiantum encryption 3472336d0deSEric Biggers mode. 3488094c3ceSEric Biggers 3498094c3ceSEric BiggersFilenames encryption 3508094c3ceSEric Biggers-------------------- 3518094c3ceSEric Biggers 3528094c3ceSEric BiggersFor filenames, each full filename is encrypted at once. Because of 3538094c3ceSEric Biggersthe requirements to retain support for efficient directory lookups and 3548094c3ceSEric Biggersfilenames of up to 255 bytes, the same IV is used for every filename 3558094c3ceSEric Biggersin a directory. 3568094c3ceSEric Biggers 3578094c3ceSEric BiggersHowever, each encrypted directory still uses a unique key; or 3588094c3ceSEric Biggersalternatively (for the "direct key" configuration) has the file's 3598094c3ceSEric Biggersnonce included in the IVs. Thus, IV reuse is limited to within a 3608094c3ceSEric Biggerssingle directory. 3618094c3ceSEric Biggers 3628094c3ceSEric BiggersWith CTS-CBC, the IV reuse means that when the plaintext filenames 3638094c3ceSEric Biggersshare a common prefix at least as long as the cipher block size (16 3648094c3ceSEric Biggersbytes for AES), the corresponding encrypted filenames will also share 3658094c3ceSEric Biggersa common prefix. This is undesirable. Adiantum does not have this 3668094c3ceSEric Biggersweakness, as it is a wide-block encryption mode. 3678094c3ceSEric Biggers 3688094c3ceSEric BiggersAll supported filenames encryption modes accept any plaintext length 3698094c3ceSEric Biggers>= 16 bytes; cipher block alignment is not required. However, 3708094c3ceSEric Biggersfilenames shorter than 16 bytes are NUL-padded to 16 bytes before 3718094c3ceSEric Biggersbeing encrypted. In addition, to reduce leakage of filename lengths 3728094c3ceSEric Biggersvia their ciphertexts, all filenames are NUL-padded to the next 4, 8, 3738094c3ceSEric Biggers16, or 32-byte boundary (configurable). 32 is recommended since this 3748094c3ceSEric Biggersprovides the best confidentiality, at the cost of making directory 3758094c3ceSEric Biggersentries consume slightly more space. Note that since NUL (``\0``) is 3768094c3ceSEric Biggersnot otherwise a valid character in filenames, the padding will never 3778094c3ceSEric Biggersproduce duplicate plaintexts. 378f4f864c1SEric Biggers 379f4f864c1SEric BiggersSymbolic link targets are considered a type of filename and are 3808094c3ceSEric Biggersencrypted in the same way as filenames in directory entries, except 3818094c3ceSEric Biggersthat IV reuse is not a problem as each symlink has its own inode. 382f4f864c1SEric Biggers 383f4f864c1SEric BiggersUser API 384f4f864c1SEric Biggers======== 385f4f864c1SEric Biggers 386f4f864c1SEric BiggersSetting an encryption policy 387f4f864c1SEric Biggers---------------------------- 388f4f864c1SEric Biggers 389ba13f2c8SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY 390ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 391ba13f2c8SEric Biggers 392f4f864c1SEric BiggersThe FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an 393f4f864c1SEric Biggersempty directory or verifies that a directory or regular file already 394f4f864c1SEric Biggershas the specified encryption policy. It takes in a pointer to a 395ba13f2c8SEric Biggers:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct 396ba13f2c8SEric Biggersfscrypt_policy_v2`, defined as follows:: 397f4f864c1SEric Biggers 398ba13f2c8SEric Biggers #define FSCRYPT_POLICY_V1 0 3992336d0deSEric Biggers #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 400ba13f2c8SEric Biggers struct fscrypt_policy_v1 { 401f4f864c1SEric Biggers __u8 version; 402f4f864c1SEric Biggers __u8 contents_encryption_mode; 403f4f864c1SEric Biggers __u8 filenames_encryption_mode; 404f4f864c1SEric Biggers __u8 flags; 4052336d0deSEric Biggers __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; 406f4f864c1SEric Biggers }; 407ba13f2c8SEric Biggers #define fscrypt_policy fscrypt_policy_v1 408ba13f2c8SEric Biggers 409ba13f2c8SEric Biggers #define FSCRYPT_POLICY_V2 2 410ba13f2c8SEric Biggers #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 411ba13f2c8SEric Biggers struct fscrypt_policy_v2 { 412ba13f2c8SEric Biggers __u8 version; 413ba13f2c8SEric Biggers __u8 contents_encryption_mode; 414ba13f2c8SEric Biggers __u8 filenames_encryption_mode; 415ba13f2c8SEric Biggers __u8 flags; 416ba13f2c8SEric Biggers __u8 __reserved[4]; 417ba13f2c8SEric Biggers __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; 418ba13f2c8SEric Biggers }; 419f4f864c1SEric Biggers 420f4f864c1SEric BiggersThis structure must be initialized as follows: 421f4f864c1SEric Biggers 422ba13f2c8SEric Biggers- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is 423ba13f2c8SEric Biggers :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct 424ba13f2c8SEric Biggers is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original 425ba13f2c8SEric Biggers policy version as "v1", though its version code is really 0.) For 426ba13f2c8SEric Biggers new encrypted directories, use v2 policies. 427f4f864c1SEric Biggers 428f4f864c1SEric Biggers- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must 4292336d0deSEric Biggers be set to constants from ``<linux/fscrypt.h>`` which identify the 4302336d0deSEric Biggers encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS 4312336d0deSEric Biggers (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS 4322336d0deSEric Biggers (4) for ``filenames_encryption_mode``. 433f4f864c1SEric Biggers 4342336d0deSEric Biggers- ``flags`` must contain a value from ``<linux/fscrypt.h>`` which 435f4f864c1SEric Biggers identifies the amount of NUL-padding to use when encrypting 436ba13f2c8SEric Biggers filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3). 437ba13f2c8SEric Biggers Additionally, if the encryption modes are both 4382336d0deSEric Biggers FSCRYPT_MODE_ADIANTUM, this can contain 439ba13f2c8SEric Biggers FSCRYPT_POLICY_FLAG_DIRECT_KEY; see `DIRECT_KEY and per-mode keys`_. 440f4f864c1SEric Biggers 441ba13f2c8SEric Biggers- For v2 encryption policies, ``__reserved`` must be zeroed. 442ba13f2c8SEric Biggers 443ba13f2c8SEric Biggers- For v1 encryption policies, ``master_key_descriptor`` specifies how 444ba13f2c8SEric Biggers to find the master key in a keyring; see `Adding keys`_. It is up 445ba13f2c8SEric Biggers to userspace to choose a unique ``master_key_descriptor`` for each 446ba13f2c8SEric Biggers master key. The e4crypt and fscrypt tools use the first 8 bytes of 447f4f864c1SEric Biggers ``SHA-512(SHA-512(master_key))``, but this particular scheme is not 448f4f864c1SEric Biggers required. Also, the master key need not be in the keyring yet when 449f4f864c1SEric Biggers FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added 450f4f864c1SEric Biggers before any files can be created in the encrypted directory. 451f4f864c1SEric Biggers 452ba13f2c8SEric Biggers For v2 encryption policies, ``master_key_descriptor`` has been 453ba13f2c8SEric Biggers replaced with ``master_key_identifier``, which is longer and cannot 454ba13f2c8SEric Biggers be arbitrarily chosen. Instead, the key must first be added using 455ba13f2c8SEric Biggers `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` 456ba13f2c8SEric Biggers the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must 457ba13f2c8SEric Biggers be used as the ``master_key_identifier`` in the :c:type:`struct 458ba13f2c8SEric Biggers fscrypt_policy_v2`. 459ba13f2c8SEric Biggers 460f4f864c1SEric BiggersIf the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY 461f4f864c1SEric Biggersverifies that the file is an empty directory. If so, the specified 462f4f864c1SEric Biggersencryption policy is assigned to the directory, turning it into an 463f4f864c1SEric Biggersencrypted directory. After that, and after providing the 464f4f864c1SEric Biggerscorresponding master key as described in `Adding keys`_, all regular 465f4f864c1SEric Biggersfiles, directories (recursively), and symlinks created in the 466f4f864c1SEric Biggersdirectory will be encrypted, inheriting the same encryption policy. 467f4f864c1SEric BiggersThe filenames in the directory's entries will be encrypted as well. 468f4f864c1SEric Biggers 469f4f864c1SEric BiggersAlternatively, if the file is already encrypted, then 470f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption 471f4f864c1SEric Biggerspolicy exactly matches the actual one. If they match, then the ioctl 472f4f864c1SEric Biggersreturns 0. Otherwise, it fails with EEXIST. This works on both 473f4f864c1SEric Biggersregular files and directories, including nonempty directories. 474f4f864c1SEric Biggers 475ba13f2c8SEric BiggersWhen a v2 encryption policy is assigned to a directory, it is also 476ba13f2c8SEric Biggersrequired that either the specified key has been added by the current 477ba13f2c8SEric Biggersuser or that the caller has CAP_FOWNER in the initial user namespace. 478ba13f2c8SEric Biggers(This is needed to prevent a user from encrypting their data with 479ba13f2c8SEric Biggersanother user's key.) The key must remain added while 480ba13f2c8SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new 481ba13f2c8SEric Biggersencrypted directory does not need to be accessed immediately, then the 482ba13f2c8SEric Biggerskey can be removed right away afterwards. 483ba13f2c8SEric Biggers 484f4f864c1SEric BiggersNote that the ext4 filesystem does not allow the root directory to be 485f4f864c1SEric Biggersencrypted, even if it is empty. Users who want to encrypt an entire 486f4f864c1SEric Biggersfilesystem with one key should consider using dm-crypt instead. 487f4f864c1SEric Biggers 488f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: 489f4f864c1SEric Biggers 490f4f864c1SEric Biggers- ``EACCES``: the file is not owned by the process's uid, nor does the 491f4f864c1SEric Biggers process have the CAP_FOWNER capability in a namespace with the file 492f4f864c1SEric Biggers owner's uid mapped 493f4f864c1SEric Biggers- ``EEXIST``: the file is already encrypted with an encryption policy 494f4f864c1SEric Biggers different from the one specified 495f4f864c1SEric Biggers- ``EINVAL``: an invalid encryption policy was specified (invalid 496ba13f2c8SEric Biggers version, mode(s), or flags; or reserved bits were set) 497ba13f2c8SEric Biggers- ``ENOKEY``: a v2 encryption policy was specified, but the key with 498ba13f2c8SEric Biggers the specified ``master_key_identifier`` has not been added, nor does 499ba13f2c8SEric Biggers the process have the CAP_FOWNER capability in the initial user 500ba13f2c8SEric Biggers namespace 501f4f864c1SEric Biggers- ``ENOTDIR``: the file is unencrypted and is a regular file, not a 502f4f864c1SEric Biggers directory 503f4f864c1SEric Biggers- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory 504f4f864c1SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 505f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 506643fa961SChandan Rajendra support for filesystems, or the filesystem superblock has not 507f4f864c1SEric Biggers had encryption enabled on it. (For example, to use encryption on an 508643fa961SChandan Rajendra ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the 509f4f864c1SEric Biggers kernel config, and the superblock must have had the "encrypt" 510f4f864c1SEric Biggers feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O 511f4f864c1SEric Biggers encrypt``.) 512f4f864c1SEric Biggers- ``EPERM``: this directory may not be encrypted, e.g. because it is 513f4f864c1SEric Biggers the root directory of an ext4 filesystem 514f4f864c1SEric Biggers- ``EROFS``: the filesystem is readonly 515f4f864c1SEric Biggers 516f4f864c1SEric BiggersGetting an encryption policy 517f4f864c1SEric Biggers---------------------------- 518f4f864c1SEric Biggers 519ba13f2c8SEric BiggersTwo ioctls are available to get a file's encryption policy: 520f4f864c1SEric Biggers 521ba13f2c8SEric Biggers- `FS_IOC_GET_ENCRYPTION_POLICY_EX`_ 522ba13f2c8SEric Biggers- `FS_IOC_GET_ENCRYPTION_POLICY`_ 523ba13f2c8SEric Biggers 524ba13f2c8SEric BiggersThe extended (_EX) version of the ioctl is more general and is 525ba13f2c8SEric Biggersrecommended to use when possible. However, on older kernels only the 526ba13f2c8SEric Biggersoriginal ioctl is available. Applications should try the extended 527ba13f2c8SEric Biggersversion, and if it fails with ENOTTY fall back to the original 528ba13f2c8SEric Biggersversion. 529ba13f2c8SEric Biggers 530ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY_EX 531ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 532ba13f2c8SEric Biggers 533ba13f2c8SEric BiggersThe FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption 534ba13f2c8SEric Biggerspolicy, if any, for a directory or regular file. No additional 535ba13f2c8SEric Biggerspermissions are required beyond the ability to open the file. It 536ba13f2c8SEric Biggerstakes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`, 537ba13f2c8SEric Biggersdefined as follows:: 538ba13f2c8SEric Biggers 539ba13f2c8SEric Biggers struct fscrypt_get_policy_ex_arg { 540ba13f2c8SEric Biggers __u64 policy_size; /* input/output */ 541ba13f2c8SEric Biggers union { 542ba13f2c8SEric Biggers __u8 version; 543ba13f2c8SEric Biggers struct fscrypt_policy_v1 v1; 544ba13f2c8SEric Biggers struct fscrypt_policy_v2 v2; 545ba13f2c8SEric Biggers } policy; /* output */ 546ba13f2c8SEric Biggers }; 547ba13f2c8SEric Biggers 548ba13f2c8SEric BiggersThe caller must initialize ``policy_size`` to the size available for 549ba13f2c8SEric Biggersthe policy struct, i.e. ``sizeof(arg.policy)``. 550ba13f2c8SEric Biggers 551ba13f2c8SEric BiggersOn success, the policy struct is returned in ``policy``, and its 552ba13f2c8SEric Biggersactual size is returned in ``policy_size``. ``policy.version`` should 553ba13f2c8SEric Biggersbe checked to determine the version of policy returned. Note that the 554ba13f2c8SEric Biggersversion code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1). 555ba13f2c8SEric Biggers 556ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors: 557f4f864c1SEric Biggers 558f4f864c1SEric Biggers- ``EINVAL``: the file is encrypted, but it uses an unrecognized 559ba13f2c8SEric Biggers encryption policy version 560f4f864c1SEric Biggers- ``ENODATA``: the file is not encrypted 561ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption, 562ba13f2c8SEric Biggers or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX 563ba13f2c8SEric Biggers (try FS_IOC_GET_ENCRYPTION_POLICY instead) 564f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 565*0642ea24SChao Yu support for this filesystem, or the filesystem superblock has not 566*0642ea24SChao Yu had encryption enabled on it 567ba13f2c8SEric Biggers- ``EOVERFLOW``: the file is encrypted and uses a recognized 568ba13f2c8SEric Biggers encryption policy version, but the policy struct does not fit into 569ba13f2c8SEric Biggers the provided buffer 570f4f864c1SEric Biggers 571f4f864c1SEric BiggersNote: if you only need to know whether a file is encrypted or not, on 572f4f864c1SEric Biggersmost filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl 573f4f864c1SEric Biggersand check for FS_ENCRYPT_FL, or to use the statx() system call and 574f4f864c1SEric Biggerscheck for STATX_ATTR_ENCRYPTED in stx_attributes. 575f4f864c1SEric Biggers 576ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY 577ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 578ba13f2c8SEric Biggers 579ba13f2c8SEric BiggersThe FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the 580ba13f2c8SEric Biggersencryption policy, if any, for a directory or regular file. However, 581ba13f2c8SEric Biggersunlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, 582ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY only supports the original policy 583ba13f2c8SEric Biggersversion. It takes in a pointer directly to a :c:type:`struct 584ba13f2c8SEric Biggersfscrypt_policy_v1` rather than a :c:type:`struct 585ba13f2c8SEric Biggersfscrypt_get_policy_ex_arg`. 586ba13f2c8SEric Biggers 587ba13f2c8SEric BiggersThe error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those 588ba13f2c8SEric Biggersfor FS_IOC_GET_ENCRYPTION_POLICY_EX, except that 589ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is 590ba13f2c8SEric Biggersencrypted using a newer encryption policy version. 591ba13f2c8SEric Biggers 592f4f864c1SEric BiggersGetting the per-filesystem salt 593f4f864c1SEric Biggers------------------------------- 594f4f864c1SEric Biggers 595f4f864c1SEric BiggersSome filesystems, such as ext4 and F2FS, also support the deprecated 596f4f864c1SEric Biggersioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly 597f4f864c1SEric Biggersgenerated 16-byte value stored in the filesystem superblock. This 598f4f864c1SEric Biggersvalue is intended to used as a salt when deriving an encryption key 599f4f864c1SEric Biggersfrom a passphrase or other low-entropy user credential. 600f4f864c1SEric Biggers 601f4f864c1SEric BiggersFS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to 602f4f864c1SEric Biggersgenerate and manage any needed salt(s) in userspace. 603f4f864c1SEric Biggers 604f4f864c1SEric BiggersAdding keys 605f4f864c1SEric Biggers----------- 606f4f864c1SEric Biggers 607ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY 608ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~ 609ba13f2c8SEric Biggers 610ba13f2c8SEric BiggersThe FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to 611ba13f2c8SEric Biggersthe filesystem, making all files on the filesystem which were 612ba13f2c8SEric Biggersencrypted using that key appear "unlocked", i.e. in plaintext form. 613ba13f2c8SEric BiggersIt can be executed on any file or directory on the target filesystem, 614ba13f2c8SEric Biggersbut using the filesystem's root directory is recommended. It takes in 615ba13f2c8SEric Biggersa pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as 616ba13f2c8SEric Biggersfollows:: 617ba13f2c8SEric Biggers 618ba13f2c8SEric Biggers struct fscrypt_add_key_arg { 619ba13f2c8SEric Biggers struct fscrypt_key_specifier key_spec; 620ba13f2c8SEric Biggers __u32 raw_size; 621ba13f2c8SEric Biggers __u32 __reserved[9]; 622ba13f2c8SEric Biggers __u8 raw[]; 623ba13f2c8SEric Biggers }; 624ba13f2c8SEric Biggers 625ba13f2c8SEric Biggers #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1 626ba13f2c8SEric Biggers #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2 627ba13f2c8SEric Biggers 628ba13f2c8SEric Biggers struct fscrypt_key_specifier { 629ba13f2c8SEric Biggers __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */ 630ba13f2c8SEric Biggers __u32 __reserved; 631ba13f2c8SEric Biggers union { 632ba13f2c8SEric Biggers __u8 __reserved[32]; /* reserve some extra space */ 633ba13f2c8SEric Biggers __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; 634ba13f2c8SEric Biggers __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; 635ba13f2c8SEric Biggers } u; 636ba13f2c8SEric Biggers }; 637ba13f2c8SEric Biggers 638ba13f2c8SEric Biggers:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized 639ba13f2c8SEric Biggersas follows: 640ba13f2c8SEric Biggers 641ba13f2c8SEric Biggers- If the key is being added for use by v1 encryption policies, then 642ba13f2c8SEric Biggers ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and 643ba13f2c8SEric Biggers ``key_spec.u.descriptor`` must contain the descriptor of the key 644ba13f2c8SEric Biggers being added, corresponding to the value in the 645ba13f2c8SEric Biggers ``master_key_descriptor`` field of :c:type:`struct 646ba13f2c8SEric Biggers fscrypt_policy_v1`. To add this type of key, the calling process 647ba13f2c8SEric Biggers must have the CAP_SYS_ADMIN capability in the initial user 648ba13f2c8SEric Biggers namespace. 649ba13f2c8SEric Biggers 650ba13f2c8SEric Biggers Alternatively, if the key is being added for use by v2 encryption 651ba13f2c8SEric Biggers policies, then ``key_spec.type`` must contain 652ba13f2c8SEric Biggers FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is 653ba13f2c8SEric Biggers an *output* field which the kernel fills in with a cryptographic 654ba13f2c8SEric Biggers hash of the key. To add this type of key, the calling process does 655ba13f2c8SEric Biggers not need any privileges. However, the number of keys that can be 656ba13f2c8SEric Biggers added is limited by the user's quota for the keyrings service (see 657ba13f2c8SEric Biggers ``Documentation/security/keys/core.rst``). 658ba13f2c8SEric Biggers 659ba13f2c8SEric Biggers- ``raw_size`` must be the size of the ``raw`` key provided, in bytes. 660ba13f2c8SEric Biggers 661ba13f2c8SEric Biggers- ``raw`` is a variable-length field which must contain the actual 662ba13f2c8SEric Biggers key, ``raw_size`` bytes long. 663ba13f2c8SEric Biggers 664ba13f2c8SEric BiggersFor v2 policy keys, the kernel keeps track of which user (identified 665ba13f2c8SEric Biggersby effective user ID) added the key, and only allows the key to be 666ba13f2c8SEric Biggersremoved by that user --- or by "root", if they use 667ba13f2c8SEric Biggers`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_. 668ba13f2c8SEric Biggers 669ba13f2c8SEric BiggersHowever, if another user has added the key, it may be desirable to 670ba13f2c8SEric Biggersprevent that other user from unexpectedly removing it. Therefore, 671ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key 672ba13f2c8SEric Biggers*again*, even if it's already added by other user(s). In this case, 673ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the 674ba13f2c8SEric Biggerscurrent user, rather than actually add the key again (but the raw key 675ba13f2c8SEric Biggersmust still be provided, as a proof of knowledge). 676ba13f2c8SEric Biggers 677ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to 678ba13f2c8SEric Biggersthe key was either added or already exists. 679ba13f2c8SEric Biggers 680ba13f2c8SEric BiggersFS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors: 681ba13f2c8SEric Biggers 682ba13f2c8SEric Biggers- ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the 683ba13f2c8SEric Biggers caller does not have the CAP_SYS_ADMIN capability in the initial 684ba13f2c8SEric Biggers user namespace 685ba13f2c8SEric Biggers- ``EDQUOT``: the key quota for this user would be exceeded by adding 686ba13f2c8SEric Biggers the key 687ba13f2c8SEric Biggers- ``EINVAL``: invalid key size or key specifier type, or reserved bits 688ba13f2c8SEric Biggers were set 689ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 690ba13f2c8SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 691ba13f2c8SEric Biggers support for this filesystem, or the filesystem superblock has not 692ba13f2c8SEric Biggers had encryption enabled on it 693ba13f2c8SEric Biggers 694ba13f2c8SEric BiggersLegacy method 695ba13f2c8SEric Biggers~~~~~~~~~~~~~ 696ba13f2c8SEric Biggers 697ba13f2c8SEric BiggersFor v1 encryption policies, a master encryption key can also be 698ba13f2c8SEric Biggersprovided by adding it to a process-subscribed keyring, e.g. to a 699ba13f2c8SEric Biggerssession keyring, or to a user keyring if the user keyring is linked 700ba13f2c8SEric Biggersinto the session keyring. 701ba13f2c8SEric Biggers 702ba13f2c8SEric BiggersThis method is deprecated (and not supported for v2 encryption 703ba13f2c8SEric Biggerspolicies) for several reasons. First, it cannot be used in 704ba13f2c8SEric Biggerscombination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_), 705ba13f2c8SEric Biggersso for removing a key a workaround such as keyctl_unlink() in 706ba13f2c8SEric Biggerscombination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would 707ba13f2c8SEric Biggershave to be used. Second, it doesn't match the fact that the 708ba13f2c8SEric Biggerslocked/unlocked status of encrypted files (i.e. whether they appear to 709ba13f2c8SEric Biggersbe in plaintext form or in ciphertext form) is global. This mismatch 710ba13f2c8SEric Biggershas caused much confusion as well as real problems when processes 711ba13f2c8SEric Biggersrunning under different UIDs, such as a ``sudo`` command, need to 712ba13f2c8SEric Biggersaccess encrypted files. 713ba13f2c8SEric Biggers 714ba13f2c8SEric BiggersNevertheless, to add a key to one of the process-subscribed keyrings, 715ba13f2c8SEric Biggersthe add_key() system call can be used (see: 716f4f864c1SEric Biggers``Documentation/security/keys/core.rst``). The key type must be 717f4f864c1SEric Biggers"logon"; keys of this type are kept in kernel memory and cannot be 718f4f864c1SEric Biggersread back by userspace. The key description must be "fscrypt:" 719f4f864c1SEric Biggersfollowed by the 16-character lower case hex representation of the 720f4f864c1SEric Biggers``master_key_descriptor`` that was set in the encryption policy. The 721f4f864c1SEric Biggerskey payload must conform to the following structure:: 722f4f864c1SEric Biggers 7232336d0deSEric Biggers #define FSCRYPT_MAX_KEY_SIZE 64 724f4f864c1SEric Biggers 725f4f864c1SEric Biggers struct fscrypt_key { 726ba13f2c8SEric Biggers __u32 mode; 727ba13f2c8SEric Biggers __u8 raw[FSCRYPT_MAX_KEY_SIZE]; 728ba13f2c8SEric Biggers __u32 size; 729f4f864c1SEric Biggers }; 730f4f864c1SEric Biggers 731f4f864c1SEric Biggers``mode`` is ignored; just set it to 0. The actual key is provided in 732f4f864c1SEric Biggers``raw`` with ``size`` indicating its size in bytes. That is, the 733f4f864c1SEric Biggersbytes ``raw[0..size-1]`` (inclusive) are the actual key. 734f4f864c1SEric Biggers 735f4f864c1SEric BiggersThe key description prefix "fscrypt:" may alternatively be replaced 736f4f864c1SEric Biggerswith a filesystem-specific prefix such as "ext4:". However, the 737f4f864c1SEric Biggersfilesystem-specific prefixes are deprecated and should not be used in 738f4f864c1SEric Biggersnew programs. 739f4f864c1SEric Biggers 740ba13f2c8SEric BiggersRemoving keys 741ba13f2c8SEric Biggers------------- 742f4f864c1SEric Biggers 743ba13f2c8SEric BiggersTwo ioctls are available for removing a key that was added by 744ba13f2c8SEric Biggers`FS_IOC_ADD_ENCRYPTION_KEY`_: 745ba13f2c8SEric Biggers 746ba13f2c8SEric Biggers- `FS_IOC_REMOVE_ENCRYPTION_KEY`_ 747ba13f2c8SEric Biggers- `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_ 748ba13f2c8SEric Biggers 749ba13f2c8SEric BiggersThese two ioctls differ only in cases where v2 policy keys are added 750ba13f2c8SEric Biggersor removed by non-root users. 751ba13f2c8SEric Biggers 752ba13f2c8SEric BiggersThese ioctls don't work on keys that were added via the legacy 753ba13f2c8SEric Biggersprocess-subscribed keyrings mechanism. 754ba13f2c8SEric Biggers 755ba13f2c8SEric BiggersBefore using these ioctls, read the `Kernel memory compromise`_ 756ba13f2c8SEric Biggerssection for a discussion of the security goals and limitations of 757ba13f2c8SEric Biggersthese ioctls. 758ba13f2c8SEric Biggers 759ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY 760ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 761ba13f2c8SEric Biggers 762ba13f2c8SEric BiggersThe FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master 763ba13f2c8SEric Biggersencryption key from the filesystem, and possibly removes the key 764ba13f2c8SEric Biggersitself. It can be executed on any file or directory on the target 765ba13f2c8SEric Biggersfilesystem, but using the filesystem's root directory is recommended. 766ba13f2c8SEric BiggersIt takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`, 767ba13f2c8SEric Biggersdefined as follows:: 768ba13f2c8SEric Biggers 769ba13f2c8SEric Biggers struct fscrypt_remove_key_arg { 770ba13f2c8SEric Biggers struct fscrypt_key_specifier key_spec; 771ba13f2c8SEric Biggers #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001 772ba13f2c8SEric Biggers #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002 773ba13f2c8SEric Biggers __u32 removal_status_flags; /* output */ 774ba13f2c8SEric Biggers __u32 __reserved[5]; 775ba13f2c8SEric Biggers }; 776ba13f2c8SEric Biggers 777ba13f2c8SEric BiggersThis structure must be zeroed, then initialized as follows: 778ba13f2c8SEric Biggers 779ba13f2c8SEric Biggers- The key to remove is specified by ``key_spec``: 780ba13f2c8SEric Biggers 781ba13f2c8SEric Biggers - To remove a key used by v1 encryption policies, set 782ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill 783ba13f2c8SEric Biggers in ``key_spec.u.descriptor``. To remove this type of key, the 784ba13f2c8SEric Biggers calling process must have the CAP_SYS_ADMIN capability in the 785ba13f2c8SEric Biggers initial user namespace. 786ba13f2c8SEric Biggers 787ba13f2c8SEric Biggers - To remove a key used by v2 encryption policies, set 788ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill 789ba13f2c8SEric Biggers in ``key_spec.u.identifier``. 790ba13f2c8SEric Biggers 791ba13f2c8SEric BiggersFor v2 policy keys, this ioctl is usable by non-root users. However, 792ba13f2c8SEric Biggersto make this possible, it actually just removes the current user's 793ba13f2c8SEric Biggersclaim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY. 794ba13f2c8SEric BiggersOnly after all claims are removed is the key really removed. 795ba13f2c8SEric Biggers 796ba13f2c8SEric BiggersFor example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000, 797ba13f2c8SEric Biggersthen the key will be "claimed" by uid 1000, and 798ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if 799ba13f2c8SEric Biggersboth uids 1000 and 2000 added the key, then for each uid 800ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only 801ba13f2c8SEric Biggersonce *both* are removed is the key really removed. (Think of it like 802ba13f2c8SEric Biggersunlinking a file that may have hard links.) 803ba13f2c8SEric Biggers 804ba13f2c8SEric BiggersIf FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also 805ba13f2c8SEric Biggerstry to "lock" all files that had been unlocked with the key. It won't 806ba13f2c8SEric Biggerslock files that are still in-use, so this ioctl is expected to be used 807ba13f2c8SEric Biggersin cooperation with userspace ensuring that none of the files are 808ba13f2c8SEric Biggersstill open. However, if necessary, this ioctl can be executed again 809ba13f2c8SEric Biggerslater to retry locking any remaining files. 810ba13f2c8SEric Biggers 811ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed 812ba13f2c8SEric Biggers(but may still have files remaining to be locked), the user's claim to 813ba13f2c8SEric Biggersthe key was removed, or the key was already removed but had files 814ba13f2c8SEric Biggersremaining to be the locked so the ioctl retried locking them. In any 815ba13f2c8SEric Biggersof these cases, ``removal_status_flags`` is filled in with the 816ba13f2c8SEric Biggersfollowing informational status flags: 817ba13f2c8SEric Biggers 818ba13f2c8SEric Biggers- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s) 819ba13f2c8SEric Biggers are still in-use. Not guaranteed to be set in the case where only 820ba13f2c8SEric Biggers the user's claim to the key was removed. 821ba13f2c8SEric Biggers- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the 822ba13f2c8SEric Biggers user's claim to the key was removed, not the key itself 823ba13f2c8SEric Biggers 824ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors: 825ba13f2c8SEric Biggers 826ba13f2c8SEric Biggers- ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type 827ba13f2c8SEric Biggers was specified, but the caller does not have the CAP_SYS_ADMIN 828ba13f2c8SEric Biggers capability in the initial user namespace 829ba13f2c8SEric Biggers- ``EINVAL``: invalid key specifier type, or reserved bits were set 830ba13f2c8SEric Biggers- ``ENOKEY``: the key object was not found at all, i.e. it was never 831ba13f2c8SEric Biggers added in the first place or was already fully removed including all 832ba13f2c8SEric Biggers files locked; or, the user does not have a claim to the key (but 833ba13f2c8SEric Biggers someone else does). 834ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 835ba13f2c8SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 836ba13f2c8SEric Biggers support for this filesystem, or the filesystem superblock has not 837ba13f2c8SEric Biggers had encryption enabled on it 838ba13f2c8SEric Biggers 839ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS 840ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 841ba13f2c8SEric Biggers 842ba13f2c8SEric BiggersFS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as 843ba13f2c8SEric Biggers`FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the 844ba13f2c8SEric BiggersALL_USERS version of the ioctl will remove all users' claims to the 845ba13f2c8SEric Biggerskey, not just the current user's. I.e., the key itself will always be 846ba13f2c8SEric Biggersremoved, no matter how many users have added it. This difference is 847ba13f2c8SEric Biggersonly meaningful if non-root users are adding and removing keys. 848ba13f2c8SEric Biggers 849ba13f2c8SEric BiggersBecause of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires 850ba13f2c8SEric Biggers"root", namely the CAP_SYS_ADMIN capability in the initial user 851ba13f2c8SEric Biggersnamespace. Otherwise it will fail with EACCES. 852ba13f2c8SEric Biggers 853ba13f2c8SEric BiggersGetting key status 854ba13f2c8SEric Biggers------------------ 855ba13f2c8SEric Biggers 856ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_KEY_STATUS 857ba13f2c8SEric Biggers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 858ba13f2c8SEric Biggers 859ba13f2c8SEric BiggersThe FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a 860ba13f2c8SEric Biggersmaster encryption key. It can be executed on any file or directory on 861ba13f2c8SEric Biggersthe target filesystem, but using the filesystem's root directory is 862ba13f2c8SEric Biggersrecommended. It takes in a pointer to a :c:type:`struct 863ba13f2c8SEric Biggersfscrypt_get_key_status_arg`, defined as follows:: 864ba13f2c8SEric Biggers 865ba13f2c8SEric Biggers struct fscrypt_get_key_status_arg { 866ba13f2c8SEric Biggers /* input */ 867ba13f2c8SEric Biggers struct fscrypt_key_specifier key_spec; 868ba13f2c8SEric Biggers __u32 __reserved[6]; 869ba13f2c8SEric Biggers 870ba13f2c8SEric Biggers /* output */ 871ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_ABSENT 1 872ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_PRESENT 2 873ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3 874ba13f2c8SEric Biggers __u32 status; 875ba13f2c8SEric Biggers #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001 876ba13f2c8SEric Biggers __u32 status_flags; 877ba13f2c8SEric Biggers __u32 user_count; 878ba13f2c8SEric Biggers __u32 __out_reserved[13]; 879ba13f2c8SEric Biggers }; 880ba13f2c8SEric Biggers 881ba13f2c8SEric BiggersThe caller must zero all input fields, then fill in ``key_spec``: 882ba13f2c8SEric Biggers 883ba13f2c8SEric Biggers - To get the status of a key for v1 encryption policies, set 884ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill 885ba13f2c8SEric Biggers in ``key_spec.u.descriptor``. 886ba13f2c8SEric Biggers 887ba13f2c8SEric Biggers - To get the status of a key for v2 encryption policies, set 888ba13f2c8SEric Biggers ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill 889ba13f2c8SEric Biggers in ``key_spec.u.identifier``. 890ba13f2c8SEric Biggers 891ba13f2c8SEric BiggersOn success, 0 is returned and the kernel fills in the output fields: 892ba13f2c8SEric Biggers 893ba13f2c8SEric Biggers- ``status`` indicates whether the key is absent, present, or 894ba13f2c8SEric Biggers incompletely removed. Incompletely removed means that the master 895ba13f2c8SEric Biggers secret has been removed, but some files are still in use; i.e., 896ba13f2c8SEric Biggers `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational 897ba13f2c8SEric Biggers status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY. 898ba13f2c8SEric Biggers 899ba13f2c8SEric Biggers- ``status_flags`` can contain the following flags: 900ba13f2c8SEric Biggers 901ba13f2c8SEric Biggers - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key 902ba13f2c8SEric Biggers has added by the current user. This is only set for keys 903ba13f2c8SEric Biggers identified by ``identifier`` rather than by ``descriptor``. 904ba13f2c8SEric Biggers 905ba13f2c8SEric Biggers- ``user_count`` specifies the number of users who have added the key. 906ba13f2c8SEric Biggers This is only set for keys identified by ``identifier`` rather than 907ba13f2c8SEric Biggers by ``descriptor``. 908ba13f2c8SEric Biggers 909ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors: 910ba13f2c8SEric Biggers 911ba13f2c8SEric Biggers- ``EINVAL``: invalid key specifier type, or reserved bits were set 912ba13f2c8SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 913ba13f2c8SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 914ba13f2c8SEric Biggers support for this filesystem, or the filesystem superblock has not 915ba13f2c8SEric Biggers had encryption enabled on it 916ba13f2c8SEric Biggers 917ba13f2c8SEric BiggersAmong other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful 918ba13f2c8SEric Biggersfor determining whether the key for a given encrypted directory needs 919ba13f2c8SEric Biggersto be added before prompting the user for the passphrase needed to 920ba13f2c8SEric Biggersderive the key. 921ba13f2c8SEric Biggers 922ba13f2c8SEric BiggersFS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in 923ba13f2c8SEric Biggersthe filesystem-level keyring, i.e. the keyring managed by 924ba13f2c8SEric Biggers`FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It 925ba13f2c8SEric Biggerscannot get the status of a key that has only been added for use by v1 926ba13f2c8SEric Biggersencryption policies using the legacy mechanism involving 927ba13f2c8SEric Biggersprocess-subscribed keyrings. 928f4f864c1SEric Biggers 929f4f864c1SEric BiggersAccess semantics 930f4f864c1SEric Biggers================ 931f4f864c1SEric Biggers 932f4f864c1SEric BiggersWith the key 933f4f864c1SEric Biggers------------ 934f4f864c1SEric Biggers 935f4f864c1SEric BiggersWith the encryption key, encrypted regular files, directories, and 936f4f864c1SEric Biggerssymlinks behave very similarly to their unencrypted counterparts --- 937f4f864c1SEric Biggersafter all, the encryption is intended to be transparent. However, 938f4f864c1SEric Biggersastute users may notice some differences in behavior: 939f4f864c1SEric Biggers 940f4f864c1SEric Biggers- Unencrypted files, or files encrypted with a different encryption 941f4f864c1SEric Biggers policy (i.e. different key, modes, or flags), cannot be renamed or 942f4f864c1SEric Biggers linked into an encrypted directory; see `Encryption policy 943f5e55e77SEric Biggers enforcement`_. Attempts to do so will fail with EXDEV. However, 944f4f864c1SEric Biggers encrypted files can be renamed within an encrypted directory, or 945f4f864c1SEric Biggers into an unencrypted directory. 946f4f864c1SEric Biggers 947f5e55e77SEric Biggers Note: "moving" an unencrypted file into an encrypted directory, e.g. 948f5e55e77SEric Biggers with the `mv` program, is implemented in userspace by a copy 949f5e55e77SEric Biggers followed by a delete. Be aware that the original unencrypted data 950f5e55e77SEric Biggers may remain recoverable from free space on the disk; prefer to keep 951f5e55e77SEric Biggers all files encrypted from the very beginning. The `shred` program 952f5e55e77SEric Biggers may be used to overwrite the source files but isn't guaranteed to be 953f5e55e77SEric Biggers effective on all filesystems and storage devices. 954f5e55e77SEric Biggers 955f4f864c1SEric Biggers- Direct I/O is not supported on encrypted files. Attempts to use 956f4f864c1SEric Biggers direct I/O on such files will fall back to buffered I/O. 957f4f864c1SEric Biggers 958f4f864c1SEric Biggers- The fallocate operations FALLOC_FL_COLLAPSE_RANGE, 959f4f864c1SEric Biggers FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported 960f4f864c1SEric Biggers on encrypted files and will fail with EOPNOTSUPP. 961f4f864c1SEric Biggers 962f4f864c1SEric Biggers- Online defragmentation of encrypted files is not supported. The 963f4f864c1SEric Biggers EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with 964f4f864c1SEric Biggers EOPNOTSUPP. 965f4f864c1SEric Biggers 966f4f864c1SEric Biggers- The ext4 filesystem does not support data journaling with encrypted 967f4f864c1SEric Biggers regular files. It will fall back to ordered data mode instead. 968f4f864c1SEric Biggers 969f4f864c1SEric Biggers- DAX (Direct Access) is not supported on encrypted files. 970f4f864c1SEric Biggers 971f4f864c1SEric Biggers- The st_size of an encrypted symlink will not necessarily give the 972f4f864c1SEric Biggers length of the symlink target as required by POSIX. It will actually 9732f46a2bcSEric Biggers give the length of the ciphertext, which will be slightly longer 9742f46a2bcSEric Biggers than the plaintext due to NUL-padding and an extra 2-byte overhead. 9752f46a2bcSEric Biggers 9762f46a2bcSEric Biggers- The maximum length of an encrypted symlink is 2 bytes shorter than 9772f46a2bcSEric Biggers the maximum length of an unencrypted symlink. For example, on an 9782f46a2bcSEric Biggers EXT4 filesystem with a 4K block size, unencrypted symlinks can be up 9792f46a2bcSEric Biggers to 4095 bytes long, while encrypted symlinks can only be up to 4093 9802f46a2bcSEric Biggers bytes long (both lengths excluding the terminating null). 981f4f864c1SEric Biggers 982f4f864c1SEric BiggersNote that mmap *is* supported. This is possible because the pagecache 983f4f864c1SEric Biggersfor an encrypted file contains the plaintext, not the ciphertext. 984f4f864c1SEric Biggers 985f4f864c1SEric BiggersWithout the key 986f4f864c1SEric Biggers--------------- 987f4f864c1SEric Biggers 988f4f864c1SEric BiggersSome filesystem operations may be performed on encrypted regular 989f4f864c1SEric Biggersfiles, directories, and symlinks even before their encryption key has 990ba13f2c8SEric Biggersbeen added, or after their encryption key has been removed: 991f4f864c1SEric Biggers 992f4f864c1SEric Biggers- File metadata may be read, e.g. using stat(). 993f4f864c1SEric Biggers 994f4f864c1SEric Biggers- Directories may be listed, in which case the filenames will be 995f4f864c1SEric Biggers listed in an encoded form derived from their ciphertext. The 996f4f864c1SEric Biggers current encoding algorithm is described in `Filename hashing and 997f4f864c1SEric Biggers encoding`_. The algorithm is subject to change, but it is 998f4f864c1SEric Biggers guaranteed that the presented filenames will be no longer than 999f4f864c1SEric Biggers NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and 1000f4f864c1SEric Biggers will uniquely identify directory entries. 1001f4f864c1SEric Biggers 1002f4f864c1SEric Biggers The ``.`` and ``..`` directory entries are special. They are always 1003f4f864c1SEric Biggers present and are not encrypted or encoded. 1004f4f864c1SEric Biggers 1005f4f864c1SEric Biggers- Files may be deleted. That is, nondirectory files may be deleted 1006f4f864c1SEric Biggers with unlink() as usual, and empty directories may be deleted with 1007f4f864c1SEric Biggers rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as 1008f4f864c1SEric Biggers expected. 1009f4f864c1SEric Biggers 1010f4f864c1SEric Biggers- Symlink targets may be read and followed, but they will be presented 1011f4f864c1SEric Biggers in encrypted form, similar to filenames in directories. Hence, they 1012f4f864c1SEric Biggers are unlikely to point to anywhere useful. 1013f4f864c1SEric Biggers 1014f4f864c1SEric BiggersWithout the key, regular files cannot be opened or truncated. 1015f4f864c1SEric BiggersAttempts to do so will fail with ENOKEY. This implies that any 1016f4f864c1SEric Biggersregular file operations that require a file descriptor, such as 1017f4f864c1SEric Biggersread(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. 1018f4f864c1SEric Biggers 1019f4f864c1SEric BiggersAlso without the key, files of any type (including directories) cannot 1020f4f864c1SEric Biggersbe created or linked into an encrypted directory, nor can a name in an 1021f4f864c1SEric Biggersencrypted directory be the source or target of a rename, nor can an 1022f4f864c1SEric BiggersO_TMPFILE temporary file be created in an encrypted directory. All 1023f4f864c1SEric Biggerssuch operations will fail with ENOKEY. 1024f4f864c1SEric Biggers 1025f4f864c1SEric BiggersIt is not currently possible to backup and restore encrypted files 1026f4f864c1SEric Biggerswithout the encryption key. This would require special APIs which 1027f4f864c1SEric Biggershave not yet been implemented. 1028f4f864c1SEric Biggers 1029f4f864c1SEric BiggersEncryption policy enforcement 1030f4f864c1SEric Biggers============================= 1031f4f864c1SEric Biggers 1032f4f864c1SEric BiggersAfter an encryption policy has been set on a directory, all regular 1033f4f864c1SEric Biggersfiles, directories, and symbolic links created in that directory 1034f4f864c1SEric Biggers(recursively) will inherit that encryption policy. Special files --- 1035f4f864c1SEric Biggersthat is, named pipes, device nodes, and UNIX domain sockets --- will 1036f4f864c1SEric Biggersnot be encrypted. 1037f4f864c1SEric Biggers 1038f4f864c1SEric BiggersExcept for those special files, it is forbidden to have unencrypted 1039f4f864c1SEric Biggersfiles, or files encrypted with a different encryption policy, in an 1040f4f864c1SEric Biggersencrypted directory tree. Attempts to link or rename such a file into 1041f5e55e77SEric Biggersan encrypted directory will fail with EXDEV. This is also enforced 1042f4f864c1SEric Biggersduring ->lookup() to provide limited protection against offline 1043f4f864c1SEric Biggersattacks that try to disable or downgrade encryption in known locations 1044f4f864c1SEric Biggerswhere applications may later write sensitive data. It is recommended 1045f4f864c1SEric Biggersthat systems implementing a form of "verified boot" take advantage of 1046f4f864c1SEric Biggersthis by validating all top-level encryption policies prior to access. 1047f4f864c1SEric Biggers 1048f4f864c1SEric BiggersImplementation details 1049f4f864c1SEric Biggers====================== 1050f4f864c1SEric Biggers 1051f4f864c1SEric BiggersEncryption context 1052f4f864c1SEric Biggers------------------ 1053f4f864c1SEric Biggers 1054f4f864c1SEric BiggersAn encryption policy is represented on-disk by a :c:type:`struct 1055ba13f2c8SEric Biggersfscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is 1056ba13f2c8SEric Biggersup to individual filesystems to decide where to store it, but normally 1057ba13f2c8SEric Biggersit would be stored in a hidden extended attribute. It should *not* be 1058ba13f2c8SEric Biggersexposed by the xattr-related system calls such as getxattr() and 1059ba13f2c8SEric Biggerssetxattr() because of the special semantics of the encryption xattr. 1060ba13f2c8SEric Biggers(In particular, there would be much confusion if an encryption policy 1061ba13f2c8SEric Biggerswere to be added to or removed from anything other than an empty 1062ba13f2c8SEric Biggersdirectory.) These structs are defined as follows:: 1063f4f864c1SEric Biggers 1064f4f864c1SEric Biggers #define FS_KEY_DERIVATION_NONCE_SIZE 16 1065f4f864c1SEric Biggers 1066ba13f2c8SEric Biggers #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 1067ba13f2c8SEric Biggers struct fscrypt_context_v1 { 1068ba13f2c8SEric Biggers u8 version; 1069f4f864c1SEric Biggers u8 contents_encryption_mode; 1070f4f864c1SEric Biggers u8 filenames_encryption_mode; 1071f4f864c1SEric Biggers u8 flags; 10722336d0deSEric Biggers u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; 1073f4f864c1SEric Biggers u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; 1074f4f864c1SEric Biggers }; 1075f4f864c1SEric Biggers 1076ba13f2c8SEric Biggers #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 1077ba13f2c8SEric Biggers struct fscrypt_context_v2 { 1078ba13f2c8SEric Biggers u8 version; 1079ba13f2c8SEric Biggers u8 contents_encryption_mode; 1080ba13f2c8SEric Biggers u8 filenames_encryption_mode; 1081ba13f2c8SEric Biggers u8 flags; 1082ba13f2c8SEric Biggers u8 __reserved[4]; 1083ba13f2c8SEric Biggers u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; 1084ba13f2c8SEric Biggers u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; 1085ba13f2c8SEric Biggers }; 1086ba13f2c8SEric Biggers 1087ba13f2c8SEric BiggersThe context structs contain the same information as the corresponding 1088ba13f2c8SEric Biggerspolicy structs (see `Setting an encryption policy`_), except that the 1089ba13f2c8SEric Biggerscontext structs also contain a nonce. The nonce is randomly generated 1090ba13f2c8SEric Biggersby the kernel and is used as KDF input or as a tweak to cause 1091ba13f2c8SEric Biggersdifferent files to be encrypted differently; see `Per-file keys`_ and 1092ba13f2c8SEric Biggers`DIRECT_KEY and per-mode keys`_. 1093f4f864c1SEric Biggers 1094f4f864c1SEric BiggersData path changes 1095f4f864c1SEric Biggers----------------- 1096f4f864c1SEric Biggers 1097f4f864c1SEric BiggersFor the read path (->readpage()) of regular files, filesystems can 1098f4f864c1SEric Biggersread the ciphertext into the page cache and decrypt it in-place. The 1099f4f864c1SEric Biggerspage lock must be held until decryption has finished, to prevent the 1100f4f864c1SEric Biggerspage from becoming visible to userspace prematurely. 1101f4f864c1SEric Biggers 1102f4f864c1SEric BiggersFor the write path (->writepage()) of regular files, filesystems 1103f4f864c1SEric Biggerscannot encrypt data in-place in the page cache, since the cached 1104f4f864c1SEric Biggersplaintext must be preserved. Instead, filesystems must encrypt into a 1105f4f864c1SEric Biggerstemporary buffer or "bounce page", then write out the temporary 1106f4f864c1SEric Biggersbuffer. Some filesystems, such as UBIFS, already use temporary 1107f4f864c1SEric Biggersbuffers regardless of encryption. Other filesystems, such as ext4 and 1108f4f864c1SEric BiggersF2FS, have to allocate bounce pages specially for encryption. 1109f4f864c1SEric Biggers 1110f4f864c1SEric BiggersFilename hashing and encoding 1111f4f864c1SEric Biggers----------------------------- 1112f4f864c1SEric Biggers 1113f4f864c1SEric BiggersModern filesystems accelerate directory lookups by using indexed 1114f4f864c1SEric Biggersdirectories. An indexed directory is organized as a tree keyed by 1115f4f864c1SEric Biggersfilename hashes. When a ->lookup() is requested, the filesystem 1116f4f864c1SEric Biggersnormally hashes the filename being looked up so that it can quickly 1117f4f864c1SEric Biggersfind the corresponding directory entry, if any. 1118f4f864c1SEric Biggers 1119f4f864c1SEric BiggersWith encryption, lookups must be supported and efficient both with and 1120f4f864c1SEric Biggerswithout the encryption key. Clearly, it would not work to hash the 1121f4f864c1SEric Biggersplaintext filenames, since the plaintext filenames are unavailable 1122f4f864c1SEric Biggerswithout the key. (Hashing the plaintext filenames would also make it 1123f4f864c1SEric Biggersimpossible for the filesystem's fsck tool to optimize encrypted 1124f4f864c1SEric Biggersdirectories.) Instead, filesystems hash the ciphertext filenames, 1125f4f864c1SEric Biggersi.e. the bytes actually stored on-disk in the directory entries. When 1126f4f864c1SEric Biggersasked to do a ->lookup() with the key, the filesystem just encrypts 1127f4f864c1SEric Biggersthe user-supplied name to get the ciphertext. 1128f4f864c1SEric Biggers 1129f4f864c1SEric BiggersLookups without the key are more complicated. The raw ciphertext may 1130f4f864c1SEric Biggerscontain the ``\0`` and ``/`` characters, which are illegal in 1131f4f864c1SEric Biggersfilenames. Therefore, readdir() must base64-encode the ciphertext for 1132f4f864c1SEric Biggerspresentation. For most filenames, this works fine; on ->lookup(), the 1133f4f864c1SEric Biggersfilesystem just base64-decodes the user-supplied name to get back to 1134f4f864c1SEric Biggersthe raw ciphertext. 1135f4f864c1SEric Biggers 1136f4f864c1SEric BiggersHowever, for very long filenames, base64 encoding would cause the 1137f4f864c1SEric Biggersfilename length to exceed NAME_MAX. To prevent this, readdir() 1138f4f864c1SEric Biggersactually presents long filenames in an abbreviated form which encodes 1139f4f864c1SEric Biggersa strong "hash" of the ciphertext filename, along with the optional 1140f4f864c1SEric Biggersfilesystem-specific hash(es) needed for directory lookups. This 1141f4f864c1SEric Biggersallows the filesystem to still, with a high degree of confidence, map 1142f4f864c1SEric Biggersthe filename given in ->lookup() back to a particular directory entry 1143f4f864c1SEric Biggersthat was previously listed by readdir(). See :c:type:`struct 1144f4f864c1SEric Biggersfscrypt_digested_name` in the source for more details. 1145f4f864c1SEric Biggers 1146f4f864c1SEric BiggersNote that the precise way that filenames are presented to userspace 1147f4f864c1SEric Biggerswithout the key is subject to change in the future. It is only meant 1148f4f864c1SEric Biggersas a way to temporarily present valid filenames so that commands like 1149f4f864c1SEric Biggers``rm -r`` work as expected on encrypted directories. 115005643363SEric Biggers 115105643363SEric BiggersTests 115205643363SEric Biggers===== 115305643363SEric Biggers 115405643363SEric BiggersTo test fscrypt, use xfstests, which is Linux's de facto standard 115505643363SEric Biggersfilesystem test suite. First, run all the tests in the "encrypt" 115605643363SEric Biggersgroup on the relevant filesystem(s). For example, to test ext4 and 115705643363SEric Biggersf2fs encryption using `kvm-xfstests 115805643363SEric Biggers<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: 115905643363SEric Biggers 116005643363SEric Biggers kvm-xfstests -c ext4,f2fs -g encrypt 116105643363SEric Biggers 116205643363SEric BiggersUBIFS encryption can also be tested this way, but it should be done in 116305643363SEric Biggersa separate command, and it takes some time for kvm-xfstests to set up 116405643363SEric Biggersemulated UBI volumes:: 116505643363SEric Biggers 116605643363SEric Biggers kvm-xfstests -c ubifs -g encrypt 116705643363SEric Biggers 116805643363SEric BiggersNo tests should fail. However, tests that use non-default encryption 116905643363SEric Biggersmodes (e.g. generic/549 and generic/550) will be skipped if the needed 117005643363SEric Biggersalgorithms were not built into the kernel's crypto API. Also, tests 117105643363SEric Biggersthat access the raw block device (e.g. generic/399, generic/548, 117205643363SEric Biggersgeneric/549, generic/550) will be skipped on UBIFS. 117305643363SEric Biggers 117405643363SEric BiggersBesides running the "encrypt" group tests, for ext4 and f2fs it's also 117505643363SEric Biggerspossible to run most xfstests with the "test_dummy_encryption" mount 117605643363SEric Biggersoption. This option causes all new files to be automatically 117705643363SEric Biggersencrypted with a dummy key, without having to make any API calls. 117805643363SEric BiggersThis tests the encrypted I/O paths more thoroughly. To do this with 117905643363SEric Biggerskvm-xfstests, use the "encrypt" filesystem configuration:: 118005643363SEric Biggers 118105643363SEric Biggers kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 118205643363SEric Biggers 118305643363SEric BiggersBecause this runs many more tests than "-g encrypt" does, it takes 118405643363SEric Biggersmuch longer to run; so also consider using `gce-xfstests 118505643363SEric Biggers<https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_ 118605643363SEric Biggersinstead of kvm-xfstests:: 118705643363SEric Biggers 118805643363SEric Biggers gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 1189