Linux/Documentation/filesystems/fscrypt.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 ===================================== 1 ===================================== 2 Filesystem-level encryption (fscrypt) 2 Filesystem-level encryption (fscrypt) 3 ===================================== 3 ===================================== 4 4 5 Introduction 5 Introduction 6 ============ 6 ============ 7 7 8 fscrypt is a library which filesystems can hoo 8 fscrypt is a library which filesystems can hook into to support 9 transparent encryption of files and directorie 9 transparent encryption of files and directories. 10 10 11 Note: "fscrypt" in this document refers to the 11 Note: "fscrypt" in this document refers to the kernel-level portion, 12 implemented in ``fs/crypto/``, as opposed to t 12 implemented in ``fs/crypto/``, as opposed to the userspace tool 13 `fscrypt <https://github.com/google/fscrypt>`_ 13 `fscrypt <https://github.com/google/fscrypt>`_. This document only 14 covers the kernel-level portion. For command- 14 covers the kernel-level portion. For command-line examples of how to 15 use encryption, see the documentation for the 15 use encryption, see the documentation for the userspace tool `fscrypt 16 <https://github.com/google/fscrypt>`_. Also, 16 <https://github.com/google/fscrypt>`_. Also, it is recommended to use 17 the fscrypt userspace tool, or other existing 17 the fscrypt userspace tool, or other existing userspace tools such as 18 `fscryptctl <https://github.com/google/fscrypt 18 `fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key 19 management system 19 management system 20 <https://source.android.com/security/encryptio 20 <https://source.android.com/security/encryption/file-based>`_, over 21 using the kernel's API directly. Using existi 21 using the kernel's API directly. Using existing tools reduces the 22 chance of introducing your own security bugs. 22 chance of introducing your own security bugs. (Nevertheless, for 23 completeness this documentation covers the ker 23 completeness this documentation covers the kernel's API anyway.) 24 24 25 Unlike dm-crypt, fscrypt operates at the files 25 Unlike dm-crypt, fscrypt operates at the filesystem level rather than 26 at the block device level. This allows it to 26 at the block device level. This allows it to encrypt different files 27 with different keys and to have unencrypted fi 27 with different keys and to have unencrypted files on the same 28 filesystem. This is useful for multi-user sys 28 filesystem. This is useful for multi-user systems where each user's 29 data-at-rest needs to be cryptographically iso 29 data-at-rest needs to be cryptographically isolated from the others. 30 However, except for filenames, fscrypt does no 30 However, except for filenames, fscrypt does not encrypt filesystem 31 metadata. 31 metadata. 32 32 33 Unlike eCryptfs, which is a stacked filesystem 33 Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated 34 directly into supported filesystems --- curren !! 34 directly into supported filesystems --- currently ext4, F2FS, and 35 and CephFS. This allows encrypted files to be !! 35 UBIFS. This allows encrypted files to be read and written without 36 without caching both the decrypted and encrypt !! 36 caching both the decrypted and encrypted pages in the pagecache, 37 pagecache, thereby nearly halving the memory u !! 37 thereby nearly halving the memory used and bringing it in line with 38 line with unencrypted files. Similarly, half !! 38 unencrypted files. Similarly, half as many dentries and inodes are 39 inodes are needed. eCryptfs also limits encry !! 39 needed. eCryptfs also limits encrypted filenames to 143 bytes, 40 bytes, causing application compatibility issue !! 40 causing application compatibility issues; fscrypt allows the full 255 41 full 255 bytes (NAME_MAX). Finally, unlike eC !! 41 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be 42 can be used by unprivileged users, with no nee !! 42 used by unprivileged users, with no need to mount anything. 43 43 44 fscrypt does not support encrypting files in-p 44 fscrypt does not support encrypting files in-place. Instead, it 45 supports marking an empty directory as encrypt 45 supports marking an empty directory as encrypted. Then, after 46 userspace provides the key, all regular files, 46 userspace provides the key, all regular files, directories, and 47 symbolic links created in that directory tree 47 symbolic links created in that directory tree are transparently 48 encrypted. 48 encrypted. 49 49 50 Threat model 50 Threat model 51 ============ 51 ============ 52 52 53 Offline attacks 53 Offline attacks 54 --------------- 54 --------------- 55 55 56 Provided that userspace chooses a strong encry 56 Provided that userspace chooses a strong encryption key, fscrypt 57 protects the confidentiality of file contents 57 protects the confidentiality of file contents and filenames in the 58 event of a single point-in-time permanent offl 58 event of a single point-in-time permanent offline compromise of the 59 block device content. fscrypt does not protec 59 block device content. fscrypt does not protect the confidentiality of 60 non-filename metadata, e.g. file sizes, file p 60 non-filename metadata, e.g. file sizes, file permissions, file 61 timestamps, and extended attributes. Also, th 61 timestamps, and extended attributes. Also, the existence and location 62 of holes (unallocated blocks which logically c 62 of holes (unallocated blocks which logically contain all zeroes) in 63 files is not protected. 63 files is not protected. 64 64 65 fscrypt is not guaranteed to protect confident 65 fscrypt is not guaranteed to protect confidentiality or authenticity 66 if an attacker is able to manipulate the files 66 if an attacker is able to manipulate the filesystem offline prior to 67 an authorized user later accessing the filesys 67 an authorized user later accessing the filesystem. 68 68 69 Online attacks 69 Online attacks 70 -------------- 70 -------------- 71 71 72 fscrypt (and storage encryption in general) ca 72 fscrypt (and storage encryption in general) can only provide limited 73 protection, if any at all, against online atta 73 protection, if any at all, against online attacks. In detail: 74 74 75 Side-channel attacks << 76 ~~~~~~~~~~~~~~~~~~~~ << 77 << 78 fscrypt is only resistant to side-channel atta 75 fscrypt is only resistant to side-channel attacks, such as timing or 79 electromagnetic attacks, to the extent that th 76 electromagnetic attacks, to the extent that the underlying Linux 80 Cryptographic API algorithms or inline encrypt !! 77 Cryptographic API algorithms are. If a vulnerable algorithm is used, 81 vulnerable algorithm is used, such as a table- !! 78 such as a table-based implementation of AES, it may be possible for an 82 AES, it may be possible for an attacker to mou !! 79 attacker to mount a side channel attack against the online system. 83 against the online system. Side channel attac !! 80 Side channel attacks may also be mounted against applications 84 against applications consuming decrypted data. !! 81 consuming decrypted data. 85 !! 82 86 Unauthorized file access !! 83 After an encryption key has been provided, fscrypt is not designed to 87 ~~~~~~~~~~~~~~~~~~~~~~~~ !! 84 hide the plaintext file contents or filenames from other users on the 88 !! 85 same system, regardless of the visibility of the keyring key. 89 After an encryption key has been added, fscryp !! 86 Instead, existing access control mechanisms such as file mode bits, 90 plaintext file contents or filenames from othe !! 87 POSIX ACLs, LSMs, or mount namespaces should be used for this purpose. 91 system. Instead, existing access control mech !! 88 Also note that as long as the encryption keys are *anywhere* in 92 bits, POSIX ACLs, LSMs, or namespaces should b !! 89 memory, an online attacker can necessarily compromise them by mounting 93 !! 90 a physical attack or by exploiting any kernel security vulnerability 94 (For the reasoning behind this, understand tha !! 91 which provides an arbitrary memory read primitive. 95 added, the confidentiality of the data, from t !! 92 96 system itself, is *not* protected by the mathe !! 93 While it is ostensibly possible to "evict" keys from the system, 97 encryption but rather only by the correctness !! 94 recently accessed encrypted files will remain accessible at least 98 Therefore, any encryption-specific access cont !! 95 until the filesystem is unmounted or the VFS caches are dropped, e.g. 99 be enforced by kernel *code* and therefore wou !! 96 using ``echo 2 > /proc/sys/vm/drop_caches``. Even after that, if the 100 with the wide variety of access control mechan !! 97 RAM is compromised before being powered off, it will likely still be 101 !! 98 possible to recover portions of the plaintext file contents, if not 102 Kernel memory compromise !! 99 some of the encryption keys as well. (Since Linux v4.12, all 103 ~~~~~~~~~~~~~~~~~~~~~~~~ !! 100 in-kernel keys related to fscrypt are sanitized before being freed. 104 !! 101 However, userspace would need to do its part as well.) 105 An attacker who compromises the system enough !! 102 106 memory, e.g. by mounting a physical attack or !! 103 Currently, fscrypt does not prevent a user from maliciously providing 107 security vulnerability, can compromise all enc !! 104 an incorrect key for another user's existing encrypted files. A 108 currently in use. !! 105 protection against this is planned. 109 << 110 However, fscrypt allows encryption keys to be << 111 which may protect them from later compromise. << 112 << 113 In more detail, the FS_IOC_REMOVE_ENCRYPTION_K << 114 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) << 115 encryption key from kernel memory. If it does << 116 evict all cached inodes which had been "unlock << 117 thereby wiping their per-file keys and making << 118 "locked", i.e. in ciphertext or encrypted form << 119 << 120 However, these ioctls have some limitations: << 121 << 122 - Per-file keys for in-use files will *not* be << 123 Therefore, for maximum effect, userspace sho << 124 encrypted files and directories before remov << 125 well as kill any processes whose working dir << 126 encrypted directory. << 127 << 128 - The kernel cannot magically wipe copies of t << 129 userspace might have as well. Therefore, us << 130 copies of the master key(s) it makes as well << 131 be done immediately after FS_IOC_ADD_ENCRYPT << 132 for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally << 133 to all higher levels in the key hierarchy. << 134 follow other security precautions such as ml << 135 containing keys to prevent it from being swa << 136 << 137 - In general, decrypted contents and filenames << 138 caches are freed but not wiped. Therefore, << 139 recoverable from freed memory, even after th << 140 were wiped. To partially solve this, you ca << 141 CONFIG_PAGE_POISONING=y in your kernel confi << 142 to your kernel command line. However, this << 143 << 144 - Secret keys might still exist in CPU registe << 145 accelerator hardware (if used by the crypto << 146 the algorithms), or in other places not expl << 147 << 148 Limitations of v1 policies << 149 ~~~~~~~~~~~~~~~~~~~~~~~~~~ << 150 << 151 v1 encryption policies have some weaknesses wi << 152 attacks: << 153 << 154 - There is no verification that the provided m << 155 Therefore, a malicious user can temporarily << 156 with another user's encrypted files to which << 157 access. Because of filesystem caching, the << 158 used by the other user's accesses to those f << 159 user has the correct key in their own keyrin << 160 meaning of "read-only access". << 161 << 162 - A compromise of a per-file key also compromi << 163 which it was derived. << 164 << 165 - Non-root users cannot securely remove encryp << 166 << 167 All the above problems are fixed with v2 encry << 168 this reason among others, it is recommended to << 169 policies on all new encrypted directories. << 170 106 171 Key hierarchy 107 Key hierarchy 172 ============= 108 ============= 173 109 174 Master Keys 110 Master Keys 175 ----------- 111 ----------- 176 112 177 Each encrypted directory tree is protected by 113 Each encrypted directory tree is protected by a *master key*. Master 178 keys can be up to 64 bytes long, and must be a 114 keys can be up to 64 bytes long, and must be at least as long as the 179 greater of the security strength of the conten !! 115 greater of the key length needed by the contents and filenames 180 encryption modes being used. For example, if !! 116 encryption modes being used. For example, if AES-256-XTS is used for 181 used, the master key must be at least 256 bits !! 117 contents encryption, the master key must be 64 bytes (512 bits). Note 182 stricter requirement applies if the key is use !! 118 that the XTS mode is defined to require a key twice as long as that 183 policy and AES-256-XTS is used; such keys must !! 119 required by the underlying block cipher. 184 120 185 To "unlock" an encrypted directory tree, users 121 To "unlock" an encrypted directory tree, userspace must provide the 186 appropriate master key. There can be any numb 122 appropriate master key. There can be any number of master keys, each 187 of which protects any number of directory tree 123 of which protects any number of directory trees on any number of 188 filesystems. 124 filesystems. 189 125 190 Master keys must be real cryptographic keys, i !! 126 Userspace should generate master keys either using a cryptographically 191 from random bytestrings of the same length. T !! 127 secure random number generator, or by using a KDF (Key Derivation 192 **must not** directly use a password as a mast !! 128 Function). Note that whenever a KDF is used to "stretch" a 193 shorter key, or repeat a shorter key. Securit !! 129 lower-entropy secret such as a passphrase, it is critical that a KDF 194 if userspace makes any such error, as the cryp !! 130 designed for this purpose be used, such as scrypt, PBKDF2, or Argon2. 195 analysis would no longer apply. << 196 << 197 Instead, users should generate master keys eit << 198 cryptographically secure random number generat << 199 (Key Derivation Function). The kernel does no << 200 therefore, if userspace derives the key from a << 201 as a passphrase, it is critical that a KDF des << 202 be used, such as scrypt, PBKDF2, or Argon2. << 203 << 204 Key derivation function << 205 ----------------------- << 206 << 207 With one exception, fscrypt never uses the mas << 208 encryption directly. Instead, they are only u << 209 (Key Derivation Function) to derive the actual << 210 << 211 The KDF used for a particular master key diffe << 212 the key is used for v1 encryption policies or << 213 policies. Users **must not** use the same key << 214 encryption policies. (No real-world attack is << 215 specific case of key reuse, but its security c << 216 since the cryptographic proofs and analysis wo << 217 << 218 For v1 encryption policies, the KDF only suppo << 219 encryption keys. It works by encrypting the m << 220 AES-128-ECB, using the file's 16-byte nonce as << 221 resulting ciphertext is used as the derived ke << 222 longer than needed, then it is truncated to th << 223 << 224 For v2 encryption policies, the KDF is HKDF-SH << 225 passed as the "input keying material", no salt << 226 "application-specific information string" is u << 227 key to be derived. For example, when a per-fi << 228 derived, the application-specific information << 229 nonce prefixed with "fscrypt\\0" and a context << 230 context bytes are used for other types of deri << 231 << 232 HKDF-SHA512 is preferred to the original AES-1 << 233 HKDF is more flexible, is nonreversible, and e << 234 entropy from the master key. HKDF is also sta << 235 used by other software, whereas the AES-128-EC << 236 131 237 Per-file encryption keys !! 132 Per-file keys 238 ------------------------ !! 133 ------------- 239 134 240 Since each master key can protect many files, 135 Since each master key can protect many files, it is necessary to 241 "tweak" the encryption of each file so that th 136 "tweak" the encryption of each file so that the same plaintext in two 242 files doesn't map to the same ciphertext, or v 137 files doesn't map to the same ciphertext, or vice versa. In most 243 cases, fscrypt does this by deriving per-file 138 cases, fscrypt does this by deriving per-file keys. When a new 244 encrypted inode (regular file, directory, or s 139 encrypted inode (regular file, directory, or symlink) is created, 245 fscrypt randomly generates a 16-byte nonce and 140 fscrypt randomly generates a 16-byte nonce and stores it in the 246 inode's encryption xattr. Then, it uses a KDF !! 141 inode's encryption xattr. Then, it uses a KDF (Key Derivation 247 derivation function`_) to derive the file's ke !! 142 Function) to derive the file's key from the master key and nonce. 248 and nonce. !! 143 >> 144 The Adiantum encryption mode (see `Encryption modes and usage`_) is >> 145 special, since it accepts longer IVs and is suitable for both contents >> 146 and filenames encryption. For it, a "direct key" option is offered >> 147 where the file's nonce is included in the IVs and the master key is >> 148 used for encryption directly. This improves performance; however, >> 149 users must not use the same master key for any other encryption mode. >> 150 >> 151 Below, the KDF and design considerations are described in more detail. >> 152 >> 153 The current KDF works by encrypting the master key with AES-128-ECB, >> 154 using the file's nonce as the AES key. The output is used as the >> 155 derived key. If the output is longer than needed, then it is >> 156 truncated to the needed length. >> 157 >> 158 Note: this KDF meets the primary security requirement, which is to >> 159 produce unique derived keys that preserve the entropy of the master >> 160 key, assuming that the master key is already a good pseudorandom key. >> 161 However, it is nonstandard and has some problems such as being >> 162 reversible, so it is generally considered to be a mistake! It may be >> 163 replaced with HKDF or another more standard KDF in the future. 249 164 250 Key derivation was chosen over key wrapping be 165 Key derivation was chosen over key wrapping because wrapped keys would 251 require larger xattrs which would be less like 166 require larger xattrs which would be less likely to fit in-line in the 252 filesystem's inode table, and there didn't app 167 filesystem's inode table, and there didn't appear to be any 253 significant advantages to key wrapping. In pa 168 significant advantages to key wrapping. In particular, currently 254 there is no requirement to support unlocking a 169 there is no requirement to support unlocking a file with multiple 255 alternative master keys or to support rotating 170 alternative master keys or to support rotating master keys. Instead, 256 the master keys may be wrapped in userspace, e 171 the master keys may be wrapped in userspace, e.g. as is done by the 257 `fscrypt <https://github.com/google/fscrypt>`_ 172 `fscrypt <https://github.com/google/fscrypt>`_ tool. 258 173 259 DIRECT_KEY policies !! 174 Including the inode number in the IVs was considered. However, it was 260 ------------------- !! 175 rejected as it would have prevented ext4 filesystems from being 261 !! 176 resized, and by itself still wouldn't have been sufficient to prevent 262 The Adiantum encryption mode (see `Encryption !! 177 the same key from being directly reused for both XTS and CTS-CBC. 263 suitable for both contents and filenames encry << 264 long IVs --- long enough to hold both an 8-byt << 265 16-byte per-file nonce. Also, the overhead of << 266 greater than that of an AES-256-XTS key. << 267 << 268 Therefore, to improve performance and save mem << 269 "direct key" configuration is supported. When << 270 this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY << 271 per-file encryption keys are not used. Instea << 272 (contents or filenames) is encrypted, the file << 273 included in the IV. Moreover: << 274 << 275 - For v1 encryption policies, the encryption i << 276 master key. Because of this, users **must n << 277 key for any other purpose, even for other v1 << 278 << 279 - For v2 encryption policies, the encryption i << 280 key derived using the KDF. Users may use th << 281 other v2 encryption policies. << 282 << 283 IV_INO_LBLK_64 policies << 284 ----------------------- << 285 << 286 When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set << 287 the encryption keys are derived from the maste << 288 number, and filesystem UUID. This normally re << 289 protected by the same master key sharing a sin << 290 key and a single filenames encryption key. To << 291 files' data differently, inode numbers are inc << 292 Consequently, shrinking the filesystem may not << 293 << 294 This format is optimized for use with inline e << 295 compliant with the UFS standard, which support << 296 I/O request and may have only a small number o << 297 << 298 IV_INO_LBLK_32 policies << 299 ----------------------- << 300 << 301 IV_INO_LBLK_32 policies work like IV_INO_LBLK_ << 302 IV_INO_LBLK_32, the inode number is hashed wit << 303 SipHash key is derived from the master key) an << 304 unit index mod 2^32 to produce a 32-bit IV. << 305 << 306 This format is optimized for use with inline e << 307 compliant with the eMMC v5.2 standard, which s << 308 per I/O request and may have only a small numb << 309 format results in some level of IV reuse, so i << 310 when necessary due to hardware limitations. << 311 << 312 Key identifiers << 313 --------------- << 314 << 315 For master keys used for v2 encryption policie << 316 identifier" is also derived using the KDF. Th << 317 the clear, since it is needed to reliably iden << 318 << 319 Dirhash keys << 320 ------------ << 321 << 322 For directories that are indexed using a secre << 323 plaintext filenames, the KDF is also used to d << 324 SipHash-2-4 key per directory in order to hash << 325 just like deriving a per-file encryption key, << 326 KDF context is used. Currently, only casefold << 327 encrypted directories use this style of hashin << 328 178 329 Encryption modes and usage 179 Encryption modes and usage 330 ========================== 180 ========================== 331 181 332 fscrypt allows one encryption mode to be speci 182 fscrypt allows one encryption mode to be specified for file contents 333 and one encryption mode to be specified for fi 183 and one encryption mode to be specified for filenames. Different 334 directory trees are permitted to use different 184 directory trees are permitted to use different encryption modes. 335 << 336 Supported modes << 337 --------------- << 338 << 339 Currently, the following pairs of encryption m 185 Currently, the following pairs of encryption modes are supported: 340 186 341 - AES-256-XTS for contents and AES-256-CBC-CTS !! 187 - AES-256-XTS for contents and AES-256-CTS-CBC for filenames 342 - AES-256-XTS for contents and AES-256-HCTR2 f !! 188 - AES-128-CBC for contents and AES-128-CTS-CBC for filenames 343 - Adiantum for both contents and filenames 189 - Adiantum for both contents and filenames 344 - AES-128-CBC-ESSIV for contents and AES-128-C << 345 - SM4-XTS for contents and SM4-CBC-CTS for fil << 346 190 347 Note: in the API, "CBC" means CBC-ESSIV, and " !! 191 If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. 348 So, for example, FSCRYPT_MODE_AES_256_CTS mean << 349 192 350 Authenticated encryption modes are not current !! 193 AES-128-CBC was added only for low-powered embedded devices with 351 the difficulty of dealing with ciphertext expa !! 194 crypto accelerators such as CAAM or CESA that do not support XTS. To 352 contents encryption uses a block cipher in `XT !! 195 use AES-128-CBC, CONFIG_CRYPTO_SHA256 (or another SHA-256 353 <https://en.wikipedia.org/wiki/Disk_encryption !! 196 implementation) must be enabled so that ESSIV can be used. 354 `CBC-ESSIV mode !! 197 355 <https://en.wikipedia.org/wiki/Disk_encryption !! 198 Adiantum is a (primarily) stream cipher-based mode that is fast even 356 or a wide-block cipher. Filenames encryption !! 199 on CPUs without dedicated crypto instructions. It's also a true 357 block cipher in `CBC-CTS mode !! 200 wide-block mode, unlike XTS. It can also eliminate the need to derive 358 <https://en.wikipedia.org/wiki/Ciphertext_stea !! 201 per-file keys. However, it depends on the security of two primitives, 359 cipher. !! 202 XChaCha12 and AES-256, rather than just one. See the paper 360 !! 203 "Adiantum: length-preserving encryption for entry-level processors" 361 The (AES-256-XTS, AES-256-CBC-CTS) pair is the !! 204 (https://eprint.iacr.org/2018/720.pdf) for more details. To use 362 It is also the only option that is *guaranteed !! 205 Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast 363 if the kernel supports fscrypt at all; see `Ke !! 206 implementations of ChaCha and NHPoly1305 should be enabled, e.g. 364 !! 207 CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. 365 The (AES-256-XTS, AES-256-HCTR2) pair is also !! 208 366 upgrades the filenames encryption to use a wid !! 209 New encryption modes can be added relatively easily, without changes 367 *wide-block cipher*, also called a tweakable s !! 210 to individual filesystems. However, authenticated encryption (AE) 368 permutation, has the property that changing on !! 211 modes are not currently supported because of the difficulty of dealing 369 entire result.) As described in `Filenames en !! 212 with ciphertext expansion. 370 cipher is the ideal mode for the problem domai << 371 "least bad" choice among the alternatives. Fo << 372 HCTR2, see `the HCTR2 paper <https://eprint.ia << 373 << 374 Adiantum is recommended on systems where AES i << 375 of hardware acceleration for AES. Adiantum is << 376 that uses XChaCha12 and AES-256 as its underly << 377 the work is done by XChaCha12, which is much f << 378 acceleration is unavailable. For more informa << 379 `the Adiantum paper <https://eprint.iacr.org/2 << 380 << 381 The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair << 382 systems whose only form of AES acceleration is << 383 accelerator such as CAAM or CESA that does not << 384 << 385 The remaining mode pairs are the "national pri << 386 << 387 - (SM4-XTS, SM4-CBC-CTS) << 388 << 389 Generally speaking, these ciphers aren't "bad" << 390 receive limited security review compared to th << 391 AES and ChaCha. They also don't bring much ne << 392 suggested to only use these ciphers where thei << 393 << 394 Kernel config options << 395 --------------------- << 396 << 397 Enabling fscrypt support (CONFIG_FS_ENCRYPTION << 398 only the basic support from the crypto API nee << 399 and AES-256-CBC-CTS encryption. For optimal p << 400 strongly recommended to also enable any availa << 401 kconfig options that provide acceleration for << 402 wish to use. Support for any "non-default" en << 403 requires extra kconfig options as well. << 404 << 405 Below, some relevant options are listed by enc << 406 acceleration options not listed below may be a << 407 platform; refer to the kconfig menus. File co << 408 also be configured to use inline encryption ha << 409 kernel crypto API (see `Inline encryption supp << 410 the file contents mode doesn't need to support << 411 API, but the filenames mode still does. << 412 << 413 - AES-256-XTS and AES-256-CBC-CTS << 414 - Recommended: << 415 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BL << 416 - x86: CONFIG_CRYPTO_AES_NI_INTEL << 417 << 418 - AES-256-HCTR2 << 419 - Mandatory: << 420 - CONFIG_CRYPTO_HCTR2 << 421 - Recommended: << 422 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BL << 423 - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_C << 424 - x86: CONFIG_CRYPTO_AES_NI_INTEL << 425 - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI << 426 << 427 - Adiantum << 428 - Mandatory: << 429 - CONFIG_CRYPTO_ADIANTUM << 430 - Recommended: << 431 - arm32: CONFIG_CRYPTO_CHACHA20_NEON << 432 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON << 433 - arm64: CONFIG_CRYPTO_CHACHA20_NEON << 434 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON << 435 - x86: CONFIG_CRYPTO_CHACHA20_X86_64 << 436 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 << 437 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 << 438 << 439 - AES-128-CBC-ESSIV and AES-128-CBC-CTS: << 440 - Mandatory: << 441 - CONFIG_CRYPTO_ESSIV << 442 - CONFIG_CRYPTO_SHA256 or another SHA- << 443 - Recommended: << 444 - AES-CBC acceleration << 445 << 446 fscrypt also uses HMAC-SHA512 for key derivati << 447 acceleration is recommended: << 448 << 449 - SHA-512 << 450 - Recommended: << 451 - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE << 452 - x86: CONFIG_CRYPTO_SHA512_SSSE3 << 453 213 454 Contents encryption 214 Contents encryption 455 ------------------- 215 ------------------- 456 216 457 For contents encryption, each file's contents !! 217 For file contents, each filesystem block is encrypted independently. 458 units". Each data unit is encrypted independe !! 218 Currently, only the case where the filesystem block size is equal to 459 data unit incorporates the zero-based index of !! 219 the system's page size (usually 4096 bytes) is supported. 460 the file. This ensures that each data unit wi !! 220 461 differently, which is essential to prevent lea !! 221 Each block's IV is set to the logical block number within the file as 462 !! 222 a little endian number, except that: 463 Note: the encryption depending on the offset i !! 223 464 operations like "collapse range" and "insert r !! 224 - With CBC mode encryption, ESSIV is also used. Specifically, each IV 465 extent mapping of files are not supported on e !! 225 is encrypted with AES-256 where the AES-256 key is the SHA-256 hash 466 !! 226 of the file's data encryption key. 467 There are two cases for the sizes of the data !! 227 468 !! 228 - In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in 469 * Fixed-size data units. This is how all file !! 229 the fscrypt_policy), the file's nonce is also appended to the IV. 470 work. A file's data units are all the same !! 230 Currently this is only allowed with the Adiantum encryption mode. 471 is zero-padded if needed. By default, the d << 472 to the filesystem block size. On some files << 473 a sub-block data unit size via the ``log2_da << 474 the encryption policy; see `FS_IOC_SET_ENCRY << 475 << 476 * Variable-size data units. This is what UBIF << 477 data node" is treated as a crypto data unit. << 478 length, possibly compressed data, zero-padde << 479 boundary. Users cannot select a sub-block d << 480 << 481 In the case of compression + encryption, the c << 482 encrypted. UBIFS compression works as describ << 483 compression works a bit differently; it compre << 484 filesystem blocks into a smaller number of fil << 485 Therefore a f2fs-compressed file still uses fi << 486 it is encrypted in a similar way to a file con << 487 << 488 As mentioned in `Key hierarchy`_, the default << 489 per-file keys. In this case, the IV for each << 490 index of the data unit in the file. However, << 491 encryption setting that does not use per-file << 492 kind of file identifier is incorporated into t << 493 << 494 - With `DIRECT_KEY policies`_, the data unit i << 495 0-63 of the IV, and the file's nonce is plac << 496 << 497 - With `IV_INO_LBLK_64 policies`_, the data un << 498 bits 0-31 of the IV, and the file's inode nu << 499 32-63. This setting is only allowed when da << 500 inode numbers fit in 32 bits. << 501 << 502 - With `IV_INO_LBLK_32 policies`_, the file's << 503 and added to the data unit index. The resul << 504 to 32 bits and placed in bits 0-31 of the IV << 505 allowed when data unit indices and inode num << 506 << 507 The byte order of the IV is always little endi << 508 << 509 If the user selects FSCRYPT_MODE_AES_128_CBC f << 510 ESSIV layer is automatically included. In thi << 511 passed to AES-128-CBC, it is encrypted with AE << 512 key is the SHA-256 hash of the file's contents << 513 231 514 Filenames encryption 232 Filenames encryption 515 -------------------- 233 -------------------- 516 234 517 For filenames, each full filename is encrypted 235 For filenames, each full filename is encrypted at once. Because of 518 the requirements to retain support for efficie 236 the requirements to retain support for efficient directory lookups and 519 filenames of up to 255 bytes, the same IV is u 237 filenames of up to 255 bytes, the same IV is used for every filename 520 in a directory. 238 in a directory. 521 239 522 However, each encrypted directory still uses a !! 240 However, each encrypted directory still uses a unique key; or 523 alternatively has the file's nonce (for `DIREC !! 241 alternatively (for the "direct key" configuration) has the file's 524 inode number (for `IV_INO_LBLK_64 policies`_) !! 242 nonce included in the IVs. Thus, IV reuse is limited to within a 525 Thus, IV reuse is limited to within a single d !! 243 single directory. 526 !! 244 527 With CBC-CTS, the IV reuse means that when the !! 245 With CTS-CBC, the IV reuse means that when the plaintext filenames 528 common prefix at least as long as the cipher b !! 246 share a common prefix at least as long as the cipher block size (16 529 corresponding encrypted filenames will also sh !! 247 bytes for AES), the corresponding encrypted filenames will also share 530 undesirable. Adiantum and HCTR2 do not have t !! 248 a common prefix. This is undesirable. Adiantum does not have this 531 wide-block encryption modes. !! 249 weakness, as it is a wide-block encryption mode. 532 250 533 All supported filenames encryption modes accep 251 All supported filenames encryption modes accept any plaintext length 534 >= 16 bytes; cipher block alignment is not req 252 >= 16 bytes; cipher block alignment is not required. However, 535 filenames shorter than 16 bytes are NUL-padded 253 filenames shorter than 16 bytes are NUL-padded to 16 bytes before 536 being encrypted. In addition, to reduce leaka 254 being encrypted. In addition, to reduce leakage of filename lengths 537 via their ciphertexts, all filenames are NUL-p 255 via their ciphertexts, all filenames are NUL-padded to the next 4, 8, 538 16, or 32-byte boundary (configurable). 32 is 256 16, or 32-byte boundary (configurable). 32 is recommended since this 539 provides the best confidentiality, at the cost 257 provides the best confidentiality, at the cost of making directory 540 entries consume slightly more space. Note tha 258 entries consume slightly more space. Note that since NUL (``\0``) is 541 not otherwise a valid character in filenames, 259 not otherwise a valid character in filenames, the padding will never 542 produce duplicate plaintexts. 260 produce duplicate plaintexts. 543 261 544 Symbolic link targets are considered a type of 262 Symbolic link targets are considered a type of filename and are 545 encrypted in the same way as filenames in dire 263 encrypted in the same way as filenames in directory entries, except 546 that IV reuse is not a problem as each symlink 264 that IV reuse is not a problem as each symlink has its own inode. 547 265 548 User API 266 User API 549 ======== 267 ======== 550 268 551 Setting an encryption policy 269 Setting an encryption policy 552 ---------------------------- 270 ---------------------------- 553 271 554 FS_IOC_SET_ENCRYPTION_POLICY << 555 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ << 556 << 557 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an 272 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an 558 empty directory or verifies that a directory o 273 empty directory or verifies that a directory or regular file already 559 has the specified encryption policy. It takes !! 274 has the specified encryption policy. It takes in a pointer to a 560 struct fscrypt_policy_v1 or struct fscrypt_pol !! 275 :c:type:`struct fscrypt_policy`, defined as follows:: 561 follows:: !! 276 562 !! 277 #define FS_KEY_DESCRIPTOR_SIZE 8 563 #define FSCRYPT_POLICY_V1 0 << 564 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 << 565 struct fscrypt_policy_v1 { << 566 __u8 version; << 567 __u8 contents_encryption_mode; << 568 __u8 filenames_encryption_mode; << 569 __u8 flags; << 570 __u8 master_key_descriptor[FSCRYPT << 571 }; << 572 #define fscrypt_policy fscrypt_policy_v1 << 573 278 574 #define FSCRYPT_POLICY_V2 2 !! 279 struct fscrypt_policy { 575 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 << 576 struct fscrypt_policy_v2 { << 577 __u8 version; 280 __u8 version; 578 __u8 contents_encryption_mode; 281 __u8 contents_encryption_mode; 579 __u8 filenames_encryption_mode; 282 __u8 filenames_encryption_mode; 580 __u8 flags; 283 __u8 flags; 581 __u8 log2_data_unit_size; !! 284 __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; 582 __u8 __reserved[3]; << 583 __u8 master_key_identifier[FSCRYPT << 584 }; 285 }; 585 286 586 This structure must be initialized as follows: 287 This structure must be initialized as follows: 587 288 588 - ``version`` must be FSCRYPT_POLICY_V1 (0) if !! 289 - ``version`` must be 0. 589 struct fscrypt_policy_v1 is used or FSCRYPT_ << 590 struct fscrypt_policy_v2 is used. (Note: we << 591 policy version as "v1", though its version c << 592 For new encrypted directories, use v2 polici << 593 290 594 - ``contents_encryption_mode`` and ``filenames 291 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must 595 be set to constants from ``<linux/fscrypt.h> !! 292 be set to constants from ``<linux/fs.h>`` which identify the 596 encryption modes to use. If unsure, use FSC !! 293 encryption modes to use. If unsure, use 597 (1) for ``contents_encryption_mode`` and FSC !! 294 FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` 598 (4) for ``filenames_encryption_mode``. For !! 295 and FS_ENCRYPTION_MODE_AES_256_CTS (4) for 599 modes and usage`_. !! 296 ``filenames_encryption_mode``. 600 !! 297 601 v1 encryption policies only support three co !! 298 - ``flags`` must contain a value from ``<linux/fs.h>`` which 602 (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_ !! 299 identifies the amount of NUL-padding to use when encrypting 603 (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_ !! 300 filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3). 604 (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTU !! 301 In addition, if the chosen encryption modes are both 605 all combinations documented in `Supported mo !! 302 FS_ENCRYPTION_MODE_ADIANTUM, this can contain 606 !! 303 FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be 607 - ``flags`` contains optional flags from ``<li !! 304 used directly, without key derivation. 608 !! 305 609 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of !! 306 - ``master_key_descriptor`` specifies how to find the master key in 610 encrypting filenames. If unsure, use FSCR !! 307 the keyring; see `Adding keys`_. It is up to userspace to choose a 611 (0x3). !! 308 unique ``master_key_descriptor`` for each master key. The e4crypt 612 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIREC !! 309 and fscrypt tools use the first 8 bytes of 613 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `I << 614 policies`_. << 615 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `I << 616 policies`_. << 617 << 618 v1 encryption policies only support the PAD_ << 619 The other flags are only supported by v2 enc << 620 << 621 The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_L << 622 mutually exclusive. << 623 << 624 - ``log2_data_unit_size`` is the log2 of the d << 625 or 0 to select the default data unit size. << 626 the granularity of file contents encryption. << 627 ``log2_data_unit_size`` to 12 causes file co << 628 underlying encryption algorithm (such as AES << 629 data units, each with its own IV. << 630 << 631 Not all filesystems support setting ``log2_d << 632 and f2fs support it since Linux v6.7. On fi << 633 it, the supported nonzero values are 9 throu << 634 filesystem block size, inclusively. The def << 635 the filesystem block size. << 636 << 637 The main use case for ``log2_data_unit_size` << 638 data unit size smaller than the filesystem b << 639 compatibility with inline encryption hardwar << 640 smaller data unit sizes. ``/sys/block/$disk << 641 useful for checking which data unit sizes ar << 642 particular system's inline encryption hardwa << 643 << 644 Leave this field zeroed unless you are certa << 645 an unnecessarily small data unit size reduce << 646 << 647 - For v2 encryption policies, ``__reserved`` m << 648 << 649 - For v1 encryption policies, ``master_key_des << 650 to find the master key in a keyring; see `Ad << 651 to userspace to choose a unique ``master_key << 652 master key. The e4crypt and fscrypt tools u << 653 ``SHA-512(SHA-512(master_key))``, but this p 310 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not 654 required. Also, the master key need not be 311 required. Also, the master key need not be in the keyring yet when 655 FS_IOC_SET_ENCRYPTION_POLICY is executed. H 312 FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added 656 before any files can be created in the encry 313 before any files can be created in the encrypted directory. 657 314 658 For v2 encryption policies, ``master_key_des << 659 replaced with ``master_key_identifier``, whi << 660 be arbitrarily chosen. Instead, the key mus << 661 `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``k << 662 the kernel returned in the struct fscrypt_ad << 663 be used as the ``master_key_identifier`` in << 664 struct fscrypt_policy_v2. << 665 << 666 If the file is not yet encrypted, then FS_IOC_ 315 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY 667 verifies that the file is an empty directory. 316 verifies that the file is an empty directory. If so, the specified 668 encryption policy is assigned to the directory 317 encryption policy is assigned to the directory, turning it into an 669 encrypted directory. After that, and after pr 318 encrypted directory. After that, and after providing the 670 corresponding master key as described in `Addi 319 corresponding master key as described in `Adding keys`_, all regular 671 files, directories (recursively), and symlinks 320 files, directories (recursively), and symlinks created in the 672 directory will be encrypted, inheriting the sa 321 directory will be encrypted, inheriting the same encryption policy. 673 The filenames in the directory's entries will 322 The filenames in the directory's entries will be encrypted as well. 674 323 675 Alternatively, if the file is already encrypte 324 Alternatively, if the file is already encrypted, then 676 FS_IOC_SET_ENCRYPTION_POLICY validates that th 325 FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption 677 policy exactly matches the actual one. If the 326 policy exactly matches the actual one. If they match, then the ioctl 678 returns 0. Otherwise, it fails with EEXIST. 327 returns 0. Otherwise, it fails with EEXIST. This works on both 679 regular files and directories, including nonem 328 regular files and directories, including nonempty directories. 680 329 681 When a v2 encryption policy is assigned to a d << 682 required that either the specified key has bee << 683 user or that the caller has CAP_FOWNER in the << 684 (This is needed to prevent a user from encrypt << 685 another user's key.) The key must remain adde << 686 FS_IOC_SET_ENCRYPTION_POLICY is executing. Ho << 687 encrypted directory does not need to be access << 688 key can be removed right away afterwards. << 689 << 690 Note that the ext4 filesystem does not allow t 330 Note that the ext4 filesystem does not allow the root directory to be 691 encrypted, even if it is empty. Users who wan 331 encrypted, even if it is empty. Users who want to encrypt an entire 692 filesystem with one key should consider using 332 filesystem with one key should consider using dm-crypt instead. 693 333 694 FS_IOC_SET_ENCRYPTION_POLICY can fail with the 334 FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: 695 335 696 - ``EACCES``: the file is not owned by the pro 336 - ``EACCES``: the file is not owned by the process's uid, nor does the 697 process have the CAP_FOWNER capability in a 337 process have the CAP_FOWNER capability in a namespace with the file 698 owner's uid mapped 338 owner's uid mapped 699 - ``EEXIST``: the file is already encrypted wi 339 - ``EEXIST``: the file is already encrypted with an encryption policy 700 different from the one specified 340 different from the one specified 701 - ``EINVAL``: an invalid encryption policy was 341 - ``EINVAL``: an invalid encryption policy was specified (invalid 702 version, mode(s), or flags; or reserved bits !! 342 version, mode(s), or flags) 703 encryption policy was specified but the dire << 704 flag enabled (casefolding is incompatible wi << 705 - ``ENOKEY``: a v2 encryption policy was speci << 706 the specified ``master_key_identifier`` has << 707 the process have the CAP_FOWNER capability i << 708 namespace << 709 - ``ENOTDIR``: the file is unencrypted and is 343 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a 710 directory 344 directory 711 - ``ENOTEMPTY``: the file is unencrypted and i 345 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory 712 - ``ENOTTY``: this type of filesystem does not 346 - ``ENOTTY``: this type of filesystem does not implement encryption 713 - ``EOPNOTSUPP``: the kernel was not configure 347 - ``EOPNOTSUPP``: the kernel was not configured with encryption 714 support for filesystems, or the filesystem s 348 support for filesystems, or the filesystem superblock has not 715 had encryption enabled on it. (For example, 349 had encryption enabled on it. (For example, to use encryption on an 716 ext4 filesystem, CONFIG_FS_ENCRYPTION must b 350 ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the 717 kernel config, and the superblock must have 351 kernel config, and the superblock must have had the "encrypt" 718 feature flag enabled using ``tune2fs -O encr 352 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O 719 encrypt``.) 353 encrypt``.) 720 - ``EPERM``: this directory may not be encrypt 354 - ``EPERM``: this directory may not be encrypted, e.g. because it is 721 the root directory of an ext4 filesystem 355 the root directory of an ext4 filesystem 722 - ``EROFS``: the filesystem is readonly 356 - ``EROFS``: the filesystem is readonly 723 357 724 Getting an encryption policy 358 Getting an encryption policy 725 ---------------------------- 359 ---------------------------- 726 360 727 Two ioctls are available to get a file's encry !! 361 The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct 728 !! 362 fscrypt_policy`, if any, for a directory or regular file. See above 729 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_ !! 363 for the struct definition. No additional permissions are required 730 - `FS_IOC_GET_ENCRYPTION_POLICY`_ !! 364 beyond the ability to open the file. 731 << 732 The extended (_EX) version of the ioctl is mor << 733 recommended to use when possible. However, on << 734 original ioctl is available. Applications sho << 735 version, and if it fails with ENOTTY fall back << 736 version. << 737 << 738 FS_IOC_GET_ENCRYPTION_POLICY_EX << 739 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ << 740 << 741 The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retr << 742 policy, if any, for a directory or regular fil << 743 permissions are required beyond the ability to << 744 takes in a pointer to struct fscrypt_get_polic << 745 defined as follows:: << 746 << 747 struct fscrypt_get_policy_ex_arg { << 748 __u64 policy_size; /* input/output << 749 union { << 750 __u8 version; << 751 struct fscrypt_policy_v1 v << 752 struct fscrypt_policy_v2 v << 753 } policy; /* output */ << 754 }; << 755 << 756 The caller must initialize ``policy_size`` to << 757 the policy struct, i.e. ``sizeof(arg.policy)`` << 758 << 759 On success, the policy struct is returned in ` << 760 actual size is returned in ``policy_size``. ` << 761 be checked to determine the version of policy << 762 version code for the "v1" policy is actually 0 << 763 365 764 FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with !! 366 FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors: 765 367 766 - ``EINVAL``: the file is encrypted, but it us 368 - ``EINVAL``: the file is encrypted, but it uses an unrecognized 767 encryption policy version !! 369 encryption context format 768 - ``ENODATA``: the file is not encrypted 370 - ``ENODATA``: the file is not encrypted 769 - ``ENOTTY``: this type of filesystem does not !! 371 - ``ENOTTY``: this type of filesystem does not implement encryption 770 or this kernel is too old to support FS_IOC_ << 771 (try FS_IOC_GET_ENCRYPTION_POLICY instead) << 772 - ``EOPNOTSUPP``: the kernel was not configure 372 - ``EOPNOTSUPP``: the kernel was not configured with encryption 773 support for this filesystem, or the filesyst !! 373 support for this filesystem 774 had encryption enabled on it << 775 - ``EOVERFLOW``: the file is encrypted and use << 776 encryption policy version, but the policy st << 777 the provided buffer << 778 374 779 Note: if you only need to know whether a file 375 Note: if you only need to know whether a file is encrypted or not, on 780 most filesystems it is also possible to use th 376 most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl 781 and check for FS_ENCRYPT_FL, or to use the sta 377 and check for FS_ENCRYPT_FL, or to use the statx() system call and 782 check for STATX_ATTR_ENCRYPTED in stx_attribut 378 check for STATX_ATTR_ENCRYPTED in stx_attributes. 783 379 784 FS_IOC_GET_ENCRYPTION_POLICY << 785 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ << 786 << 787 The FS_IOC_GET_ENCRYPTION_POLICY ioctl can als << 788 encryption policy, if any, for a directory or << 789 unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, << 790 FS_IOC_GET_ENCRYPTION_POLICY only supports the << 791 version. It takes in a pointer directly to st << 792 rather than struct fscrypt_get_policy_ex_arg. << 793 << 794 The error codes for FS_IOC_GET_ENCRYPTION_POLI << 795 for FS_IOC_GET_ENCRYPTION_POLICY_EX, except th << 796 FS_IOC_GET_ENCRYPTION_POLICY also returns ``EI << 797 encrypted using a newer encryption policy vers << 798 << 799 Getting the per-filesystem salt 380 Getting the per-filesystem salt 800 ------------------------------- 381 ------------------------------- 801 382 802 Some filesystems, such as ext4 and F2FS, also 383 Some filesystems, such as ext4 and F2FS, also support the deprecated 803 ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioct 384 ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly 804 generated 16-byte value stored in the filesyst 385 generated 16-byte value stored in the filesystem superblock. This 805 value is intended to used as a salt when deriv 386 value is intended to used as a salt when deriving an encryption key 806 from a passphrase or other low-entropy user cr 387 from a passphrase or other low-entropy user credential. 807 388 808 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. I 389 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to 809 generate and manage any needed salt(s) in user 390 generate and manage any needed salt(s) in userspace. 810 391 811 Getting a file's encryption nonce << 812 --------------------------------- << 813 << 814 Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPT << 815 On encrypted files and directories it gets the << 816 On unencrypted files and directories, it fails << 817 << 818 This ioctl can be useful for automated tests w << 819 encryption is being done correctly. It is not << 820 of fscrypt. << 821 << 822 Adding keys 392 Adding keys 823 ----------- 393 ----------- 824 394 825 FS_IOC_ADD_ENCRYPTION_KEY !! 395 To provide a master key, userspace must add it to an appropriate 826 ~~~~~~~~~~~~~~~~~~~~~~~~~ !! 396 keyring using the add_key() system call (see: 827 << 828 The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a mas << 829 the filesystem, making all files on the filesy << 830 encrypted using that key appear "unlocked", i. << 831 It can be executed on any file or directory on << 832 but using the filesystem's root directory is r << 833 a pointer to struct fscrypt_add_key_arg, defin << 834 << 835 struct fscrypt_add_key_arg { << 836 struct fscrypt_key_specifier key_s << 837 __u32 raw_size; << 838 __u32 key_id; << 839 __u32 __reserved[8]; << 840 __u8 raw[]; << 841 }; << 842 << 843 #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR << 844 #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER << 845 << 846 struct fscrypt_key_specifier { << 847 __u32 type; /* one of FSCRYPT_ << 848 __u32 __reserved; << 849 union { << 850 __u8 __reserved[32]; /* re << 851 __u8 descriptor[FSCRYPT_KE << 852 __u8 identifier[FSCRYPT_KE << 853 } u; << 854 }; << 855 << 856 struct fscrypt_provisioning_key_payload { << 857 __u32 type; << 858 __u32 __reserved; << 859 __u8 raw[]; << 860 }; << 861 << 862 struct fscrypt_add_key_arg must be zeroed, the << 863 as follows: << 864 << 865 - If the key is being added for use by v1 encr << 866 ``key_spec.type`` must contain FSCRYPT_KEY_S << 867 ``key_spec.u.descriptor`` must contain the d << 868 being added, corresponding to the value in t << 869 ``master_key_descriptor`` field of struct fs << 870 To add this type of key, the calling process << 871 CAP_SYS_ADMIN capability in the initial user << 872 << 873 Alternatively, if the key is being added for << 874 policies, then ``key_spec.type`` must contai << 875 FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_ << 876 an *output* field which the kernel fills in << 877 hash of the key. To add this type of key, t << 878 not need any privileges. However, the numbe << 879 added is limited by the user's quota for the << 880 ``Documentation/security/keys/core.rst``). << 881 << 882 - ``raw_size`` must be the size of the ``raw`` << 883 Alternatively, if ``key_id`` is nonzero, thi << 884 in that case the size is implied by the spec << 885 << 886 - ``key_id`` is 0 if the raw key is given dire << 887 field. Otherwise ``key_id`` is the ID of a << 888 type "fscrypt-provisioning" whose payload is << 889 struct fscrypt_provisioning_key_payload whos << 890 the raw key and whose ``type`` field matches << 891 Since ``raw`` is variable-length, the total << 892 payload must be ``sizeof(struct fscrypt_prov << 893 plus the raw key size. The process must hav << 894 this key. << 895 << 896 Most users should leave this 0 and specify t << 897 The support for specifying a Linux keyring k << 898 allow re-adding keys after a filesystem is u << 899 without having to store the raw keys in user << 900 << 901 - ``raw`` is a variable-length field which mus << 902 key, ``raw_size`` bytes long. Alternatively << 903 nonzero, then this field is unused. << 904 << 905 For v2 policy keys, the kernel keeps track of << 906 by effective user ID) added the key, and only << 907 removed by that user --- or by "root", if they << 908 `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_. << 909 << 910 However, if another user has added the key, it << 911 prevent that other user from unexpectedly remo << 912 FS_IOC_ADD_ENCRYPTION_KEY may also be used to << 913 *again*, even if it's already added by other u << 914 FS_IOC_ADD_ENCRYPTION_KEY will just install a << 915 current user, rather than actually add the key << 916 must still be provided, as a proof of knowledg << 917 << 918 FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either << 919 the key was either added or already exists. << 920 << 921 FS_IOC_ADD_ENCRYPTION_KEY can fail with the fo << 922 << 923 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR << 924 caller does not have the CAP_SYS_ADMIN capab << 925 user namespace; or the raw key was specified << 926 process lacks Search permission on the key. << 927 - ``EDQUOT``: the key quota for this user woul << 928 the key << 929 - ``EINVAL``: invalid key size or key specifie << 930 were set << 931 - ``EKEYREJECTED``: the raw key was specified << 932 key has the wrong type << 933 - ``ENOKEY``: the raw key was specified by Lin << 934 exists with that ID << 935 - ``ENOTTY``: this type of filesystem does not << 936 - ``EOPNOTSUPP``: the kernel was not configure << 937 support for this filesystem, or the filesyst << 938 had encryption enabled on it << 939 << 940 Legacy method << 941 ~~~~~~~~~~~~~ << 942 << 943 For v1 encryption policies, a master encryptio << 944 provided by adding it to a process-subscribed << 945 session keyring, or to a user keyring if the u << 946 into the session keyring. << 947 << 948 This method is deprecated (and not supported f << 949 policies) for several reasons. First, it cann << 950 combination with FS_IOC_REMOVE_ENCRYPTION_KEY << 951 so for removing a key a workaround such as key << 952 combination with ``sync; echo 2 > /proc/sys/vm << 953 have to be used. Second, it doesn't match the << 954 locked/unlocked status of encrypted files (i.e << 955 be in plaintext form or in ciphertext form) is << 956 has caused much confusion as well as real prob << 957 running under different UIDs, such as a ``sudo << 958 access encrypted files. << 959 << 960 Nevertheless, to add a key to one of the proce << 961 the add_key() system call can be used (see: << 962 ``Documentation/security/keys/core.rst``). Th 397 ``Documentation/security/keys/core.rst``). The key type must be 963 "logon"; keys of this type are kept in kernel 398 "logon"; keys of this type are kept in kernel memory and cannot be 964 read back by userspace. The key description m 399 read back by userspace. The key description must be "fscrypt:" 965 followed by the 16-character lower case hex re 400 followed by the 16-character lower case hex representation of the 966 ``master_key_descriptor`` that was set in the 401 ``master_key_descriptor`` that was set in the encryption policy. The 967 key payload must conform to the following stru 402 key payload must conform to the following structure:: 968 403 969 #define FSCRYPT_MAX_KEY_SIZE 64 !! 404 #define FS_MAX_KEY_SIZE 64 970 405 971 struct fscrypt_key { 406 struct fscrypt_key { 972 __u32 mode; !! 407 u32 mode; 973 __u8 raw[FSCRYPT_MAX_KEY_SIZE]; !! 408 u8 raw[FS_MAX_KEY_SIZE]; 974 __u32 size; !! 409 u32 size; 975 }; 410 }; 976 411 977 ``mode`` is ignored; just set it to 0. The ac 412 ``mode`` is ignored; just set it to 0. The actual key is provided in 978 ``raw`` with ``size`` indicating its size in b 413 ``raw`` with ``size`` indicating its size in bytes. That is, the 979 bytes ``raw[0..size-1]`` (inclusive) are the a 414 bytes ``raw[0..size-1]`` (inclusive) are the actual key. 980 415 981 The key description prefix "fscrypt:" may alte 416 The key description prefix "fscrypt:" may alternatively be replaced 982 with a filesystem-specific prefix such as "ext 417 with a filesystem-specific prefix such as "ext4:". However, the 983 filesystem-specific prefixes are deprecated an 418 filesystem-specific prefixes are deprecated and should not be used in 984 new programs. 419 new programs. 985 420 986 Removing keys !! 421 There are several different types of keyrings in which encryption keys 987 ------------- !! 422 may be placed, such as a session keyring, a user session keyring, or a 988 !! 423 user keyring. Each key must be placed in a keyring that is "attached" 989 Two ioctls are available for removing a key th !! 424 to all processes that might need to access files encrypted with it, in 990 `FS_IOC_ADD_ENCRYPTION_KEY`_: !! 425 the sense that request_key() will find the key. Generally, if only 991 !! 426 processes belonging to a specific user need to access a given 992 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_ !! 427 encrypted directory and no session keyring has been installed, then 993 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_ !! 428 that directory's key should be placed in that user's user session 994 !! 429 keyring or user keyring. Otherwise, a session keyring should be 995 These two ioctls differ only in cases where v2 !! 430 installed if needed, and the key should be linked into that session 996 or removed by non-root users. !! 431 keyring, or in a keyring linked into that session keyring. 997 !! 432 998 These ioctls don't work on keys that were adde !! 433 Note: introducing the complex visibility semantics of keyrings here 999 process-subscribed keyrings mechanism. !! 434 was arguably a mistake --- especially given that by design, after any 1000 !! 435 process successfully opens an encrypted file (thereby setting up the 1001 Before using these ioctls, read the `Kernel m !! 436 per-file key), possessing the keyring key is not actually required for 1002 section for a discussion of the security goal !! 437 any process to read/write the file until its in-memory inode is 1003 these ioctls. !! 438 evicted. In the future there probably should be a way to provide keys 1004 !! 439 directly to the filesystem instead, which would make the intended 1005 FS_IOC_REMOVE_ENCRYPTION_KEY !! 440 semantics clearer. 1006 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ << 1007 << 1008 The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl remove << 1009 encryption key from the filesystem, and possi << 1010 itself. It can be executed on any file or di << 1011 filesystem, but using the filesystem's root d << 1012 It takes in a pointer to struct fscrypt_remov << 1013 as follows:: << 1014 << 1015 struct fscrypt_remove_key_arg { << 1016 struct fscrypt_key_specifier key_ << 1017 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_F << 1018 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_O << 1019 __u32 removal_status_flags; / << 1020 __u32 __reserved[5]; << 1021 }; << 1022 << 1023 This structure must be zeroed, then initializ << 1024 << 1025 - The key to remove is specified by ``key_spe << 1026 << 1027 - To remove a key used by v1 encryption p << 1028 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T << 1029 in ``key_spec.u.descriptor``. To remov << 1030 calling process must have the CAP_SYS_A << 1031 initial user namespace. << 1032 << 1033 - To remove a key used by v2 encryption p << 1034 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T << 1035 in ``key_spec.u.identifier``. << 1036 << 1037 For v2 policy keys, this ioctl is usable by n << 1038 to make this possible, it actually just remov << 1039 claim to the key, undoing a single call to FS << 1040 Only after all claims are removed is the key << 1041 << 1042 For example, if FS_IOC_ADD_ENCRYPTION_KEY was << 1043 then the key will be "claimed" by uid 1000, a << 1044 FS_IOC_REMOVE_ENCRYPTION_KEY will only succee << 1045 both uids 1000 and 2000 added the key, then f << 1046 FS_IOC_REMOVE_ENCRYPTION_KEY will only remove << 1047 once *both* are removed is the key really rem << 1048 unlinking a file that may have hard links.) << 1049 << 1050 If FS_IOC_REMOVE_ENCRYPTION_KEY really remove << 1051 try to "lock" all files that had been unlocke << 1052 lock files that are still in-use, so this ioc << 1053 in cooperation with userspace ensuring that n << 1054 still open. However, if necessary, this ioct << 1055 later to retry locking any remaining files. << 1056 << 1057 FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if eit << 1058 (but may still have files remaining to be loc << 1059 the key was removed, or the key was already r << 1060 remaining to be the locked so the ioctl retri << 1061 of these cases, ``removal_status_flags`` is f << 1062 following informational status flags: << 1063 << 1064 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUS << 1065 are still in-use. Not guaranteed to be set << 1066 the user's claim to the key was removed. << 1067 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USE << 1068 user's claim to the key was removed, not th << 1069 << 1070 FS_IOC_REMOVE_ENCRYPTION_KEY can fail with th << 1071 << 1072 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCR << 1073 was specified, but the caller does not have << 1074 capability in the initial user namespace << 1075 - ``EINVAL``: invalid key specifier type, or << 1076 - ``ENOKEY``: the key object was not found at << 1077 added in the first place or was already ful << 1078 files locked; or, the user does not have a << 1079 someone else does). << 1080 - ``ENOTTY``: this type of filesystem does no << 1081 - ``EOPNOTSUPP``: the kernel was not configur << 1082 support for this filesystem, or the filesys << 1083 had encryption enabled on it << 1084 << 1085 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS << 1086 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ << 1087 << 1088 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exa << 1089 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that << 1090 ALL_USERS version of the ioctl will remove al << 1091 key, not just the current user's. I.e., the << 1092 removed, no matter how many users have added << 1093 only meaningful if non-root users are adding << 1094 << 1095 Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY << 1096 "root", namely the CAP_SYS_ADMIN capability i << 1097 namespace. Otherwise it will fail with EACCE << 1098 << 1099 Getting key status << 1100 ------------------ << 1101 << 1102 FS_IOC_GET_ENCRYPTION_KEY_STATUS << 1103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ << 1104 << 1105 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl re << 1106 master encryption key. It can be executed on << 1107 the target filesystem, but using the filesyst << 1108 recommended. It takes in a pointer to << 1109 struct fscrypt_get_key_status_arg, defined as << 1110 << 1111 struct fscrypt_get_key_status_arg { << 1112 /* input */ << 1113 struct fscrypt_key_specifier key_ << 1114 __u32 __reserved[6]; << 1115 << 1116 /* output */ << 1117 #define FSCRYPT_KEY_STATUS_ABSENT << 1118 #define FSCRYPT_KEY_STATUS_PRESENT << 1119 #define FSCRYPT_KEY_STATUS_INCOMPLETELY_R << 1120 __u32 status; << 1121 #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_ << 1122 __u32 status_flags; << 1123 __u32 user_count; << 1124 __u32 __out_reserved[13]; << 1125 }; << 1126 << 1127 The caller must zero all input fields, then f << 1128 << 1129 - To get the status of a key for v1 encry << 1130 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T << 1131 in ``key_spec.u.descriptor``. << 1132 << 1133 - To get the status of a key for v2 encry << 1134 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T << 1135 in ``key_spec.u.identifier``. << 1136 << 1137 On success, 0 is returned and the kernel fill << 1138 << 1139 - ``status`` indicates whether the key is abs << 1140 incompletely removed. Incompletely removed << 1141 been initiated, but some files are still in << 1142 `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 << 1143 status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG << 1144 << 1145 - ``status_flags`` can contain the following << 1146 << 1147 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF << 1148 has added by the current user. This is << 1149 identified by ``identifier`` rather tha << 1150 << 1151 - ``user_count`` specifies the number of user << 1152 This is only set for keys identified by ``i << 1153 by ``descriptor``. << 1154 << 1155 FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail wit << 1156 << 1157 - ``EINVAL``: invalid key specifier type, or << 1158 - ``ENOTTY``: this type of filesystem does no << 1159 - ``EOPNOTSUPP``: the kernel was not configur << 1160 support for this filesystem, or the filesys << 1161 had encryption enabled on it << 1162 << 1163 Among other use cases, FS_IOC_GET_ENCRYPTION_ << 1164 for determining whether the key for a given e << 1165 to be added before prompting the user for the << 1166 derive the key. << 1167 << 1168 FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get << 1169 the filesystem-level keyring, i.e. the keyrin << 1170 `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMO << 1171 cannot get the status of a key that has only << 1172 encryption policies using the legacy mechanis << 1173 process-subscribed keyrings. << 1174 441 1175 Access semantics 442 Access semantics 1176 ================ 443 ================ 1177 444 1178 With the key 445 With the key 1179 ------------ 446 ------------ 1180 447 1181 With the encryption key, encrypted regular fi 448 With the encryption key, encrypted regular files, directories, and 1182 symlinks behave very similarly to their unenc 449 symlinks behave very similarly to their unencrypted counterparts --- 1183 after all, the encryption is intended to be t 450 after all, the encryption is intended to be transparent. However, 1184 astute users may notice some differences in b 451 astute users may notice some differences in behavior: 1185 452 1186 - Unencrypted files, or files encrypted with 453 - Unencrypted files, or files encrypted with a different encryption 1187 policy (i.e. different key, modes, or flags 454 policy (i.e. different key, modes, or flags), cannot be renamed or 1188 linked into an encrypted directory; see `En 455 linked into an encrypted directory; see `Encryption policy 1189 enforcement`_. Attempts to do so will fail 456 enforcement`_. Attempts to do so will fail with EXDEV. However, 1190 encrypted files can be renamed within an en 457 encrypted files can be renamed within an encrypted directory, or 1191 into an unencrypted directory. 458 into an unencrypted directory. 1192 459 1193 Note: "moving" an unencrypted file into an 460 Note: "moving" an unencrypted file into an encrypted directory, e.g. 1194 with the `mv` program, is implemented in us 461 with the `mv` program, is implemented in userspace by a copy 1195 followed by a delete. Be aware that the or 462 followed by a delete. Be aware that the original unencrypted data 1196 may remain recoverable from free space on t 463 may remain recoverable from free space on the disk; prefer to keep 1197 all files encrypted from the very beginning 464 all files encrypted from the very beginning. The `shred` program 1198 may be used to overwrite the source files b 465 may be used to overwrite the source files but isn't guaranteed to be 1199 effective on all filesystems and storage de 466 effective on all filesystems and storage devices. 1200 467 1201 - Direct I/O is supported on encrypted files !! 468 - Direct I/O is not supported on encrypted files. Attempts to use 1202 circumstances. For details, see `Direct I/ !! 469 direct I/O on such files will fall back to buffered I/O. 1203 470 1204 - The fallocate operations FALLOC_FL_COLLAPSE !! 471 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE, 1205 FALLOC_FL_INSERT_RANGE are not supported on !! 472 FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported 1206 fail with EOPNOTSUPP. !! 473 on encrypted files and will fail with EOPNOTSUPP. 1207 474 1208 - Online defragmentation of encrypted files i 475 - Online defragmentation of encrypted files is not supported. The 1209 EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE i 476 EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with 1210 EOPNOTSUPP. 477 EOPNOTSUPP. 1211 478 1212 - The ext4 filesystem does not support data j 479 - The ext4 filesystem does not support data journaling with encrypted 1213 regular files. It will fall back to ordere 480 regular files. It will fall back to ordered data mode instead. 1214 481 1215 - DAX (Direct Access) is not supported on enc 482 - DAX (Direct Access) is not supported on encrypted files. 1216 483 >> 484 - The st_size of an encrypted symlink will not necessarily give the >> 485 length of the symlink target as required by POSIX. It will actually >> 486 give the length of the ciphertext, which will be slightly longer >> 487 than the plaintext due to NUL-padding and an extra 2-byte overhead. >> 488 1217 - The maximum length of an encrypted symlink 489 - The maximum length of an encrypted symlink is 2 bytes shorter than 1218 the maximum length of an unencrypted symlin 490 the maximum length of an unencrypted symlink. For example, on an 1219 EXT4 filesystem with a 4K block size, unenc 491 EXT4 filesystem with a 4K block size, unencrypted symlinks can be up 1220 to 4095 bytes long, while encrypted symlink 492 to 4095 bytes long, while encrypted symlinks can only be up to 4093 1221 bytes long (both lengths excluding the term 493 bytes long (both lengths excluding the terminating null). 1222 494 1223 Note that mmap *is* supported. This is possi 495 Note that mmap *is* supported. This is possible because the pagecache 1224 for an encrypted file contains the plaintext, 496 for an encrypted file contains the plaintext, not the ciphertext. 1225 497 1226 Without the key 498 Without the key 1227 --------------- 499 --------------- 1228 500 1229 Some filesystem operations may be performed o 501 Some filesystem operations may be performed on encrypted regular 1230 files, directories, and symlinks even before 502 files, directories, and symlinks even before their encryption key has 1231 been added, or after their encryption key has !! 503 been provided: 1232 504 1233 - File metadata may be read, e.g. using stat( 505 - File metadata may be read, e.g. using stat(). 1234 506 1235 - Directories may be listed, in which case th 507 - Directories may be listed, in which case the filenames will be 1236 listed in an encoded form derived from thei 508 listed in an encoded form derived from their ciphertext. The 1237 current encoding algorithm is described in 509 current encoding algorithm is described in `Filename hashing and 1238 encoding`_. The algorithm is subject to ch 510 encoding`_. The algorithm is subject to change, but it is 1239 guaranteed that the presented filenames wil 511 guaranteed that the presented filenames will be no longer than 1240 NAME_MAX bytes, will not contain the ``/`` 512 NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and 1241 will uniquely identify directory entries. 513 will uniquely identify directory entries. 1242 514 1243 The ``.`` and ``..`` directory entries are 515 The ``.`` and ``..`` directory entries are special. They are always 1244 present and are not encrypted or encoded. 516 present and are not encrypted or encoded. 1245 517 1246 - Files may be deleted. That is, nondirector 518 - Files may be deleted. That is, nondirectory files may be deleted 1247 with unlink() as usual, and empty directori 519 with unlink() as usual, and empty directories may be deleted with 1248 rmdir() as usual. Therefore, ``rm`` and `` 520 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as 1249 expected. 521 expected. 1250 522 1251 - Symlink targets may be read and followed, b 523 - Symlink targets may be read and followed, but they will be presented 1252 in encrypted form, similar to filenames in 524 in encrypted form, similar to filenames in directories. Hence, they 1253 are unlikely to point to anywhere useful. 525 are unlikely to point to anywhere useful. 1254 526 1255 Without the key, regular files cannot be open 527 Without the key, regular files cannot be opened or truncated. 1256 Attempts to do so will fail with ENOKEY. Thi 528 Attempts to do so will fail with ENOKEY. This implies that any 1257 regular file operations that require a file d 529 regular file operations that require a file descriptor, such as 1258 read(), write(), mmap(), fallocate(), and ioc 530 read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. 1259 531 1260 Also without the key, files of any type (incl 532 Also without the key, files of any type (including directories) cannot 1261 be created or linked into an encrypted direct 533 be created or linked into an encrypted directory, nor can a name in an 1262 encrypted directory be the source or target o 534 encrypted directory be the source or target of a rename, nor can an 1263 O_TMPFILE temporary file be created in an enc 535 O_TMPFILE temporary file be created in an encrypted directory. All 1264 such operations will fail with ENOKEY. 536 such operations will fail with ENOKEY. 1265 537 1266 It is not currently possible to backup and re 538 It is not currently possible to backup and restore encrypted files 1267 without the encryption key. This would requi 539 without the encryption key. This would require special APIs which 1268 have not yet been implemented. 540 have not yet been implemented. 1269 541 1270 Encryption policy enforcement 542 Encryption policy enforcement 1271 ============================= 543 ============================= 1272 544 1273 After an encryption policy has been set on a 545 After an encryption policy has been set on a directory, all regular 1274 files, directories, and symbolic links create 546 files, directories, and symbolic links created in that directory 1275 (recursively) will inherit that encryption po 547 (recursively) will inherit that encryption policy. Special files --- 1276 that is, named pipes, device nodes, and UNIX 548 that is, named pipes, device nodes, and UNIX domain sockets --- will 1277 not be encrypted. 549 not be encrypted. 1278 550 1279 Except for those special files, it is forbidd 551 Except for those special files, it is forbidden to have unencrypted 1280 files, or files encrypted with a different en 552 files, or files encrypted with a different encryption policy, in an 1281 encrypted directory tree. Attempts to link o 553 encrypted directory tree. Attempts to link or rename such a file into 1282 an encrypted directory will fail with EXDEV. 554 an encrypted directory will fail with EXDEV. This is also enforced 1283 during ->lookup() to provide limited protecti 555 during ->lookup() to provide limited protection against offline 1284 attacks that try to disable or downgrade encr 556 attacks that try to disable or downgrade encryption in known locations 1285 where applications may later write sensitive 557 where applications may later write sensitive data. It is recommended 1286 that systems implementing a form of "verified 558 that systems implementing a form of "verified boot" take advantage of 1287 this by validating all top-level encryption p 559 this by validating all top-level encryption policies prior to access. 1288 560 1289 Inline encryption support << 1290 ========================= << 1291 << 1292 By default, fscrypt uses the kernel crypto AP << 1293 operations (other than HKDF, which fscrypt pa << 1294 itself). The kernel crypto API supports hard << 1295 but only ones that work in the traditional wa << 1296 outputs (e.g. plaintexts and ciphertexts) are << 1297 take advantage of such hardware, but the trad << 1298 model isn't particularly efficient and fscryp << 1299 for it. << 1300 << 1301 Instead, many newer systems (especially mobil << 1302 encryption hardware* that can encrypt/decrypt << 1303 way to/from the storage device. Linux suppor << 1304 through a set of extensions to the block laye << 1305 blk-crypto allows filesystems to attach encry << 1306 (I/O requests) to specify how the data will b << 1307 in-line. For more information about blk-cryp << 1308 :ref:`Documentation/block/inline-encryption.r << 1309 << 1310 On supported filesystems (currently ext4 and << 1311 blk-crypto instead of the kernel crypto API t << 1312 contents. To enable this, set CONFIG_FS_ENCR << 1313 the kernel configuration, and specify the "in << 1314 when mounting the filesystem. << 1315 << 1316 Note that the "inlinecrypt" mount option just << 1317 encryption when possible; it doesn't force it << 1318 still fall back to using the kernel crypto AP << 1319 inline encryption hardware doesn't have the n << 1320 (e.g. support for the needed encryption algor << 1321 and where blk-crypto-fallback is unusable. ( << 1322 to be usable, it must be enabled in the kerne << 1323 CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y.) << 1324 << 1325 Currently fscrypt always uses the filesystem << 1326 usually 4096 bytes) as the data unit size. T << 1327 inline encryption hardware that supports that << 1328 << 1329 Inline encryption doesn't affect the cipherte << 1330 the on-disk format, so users may freely switc << 1331 using "inlinecrypt" and not using "inlinecryp << 1332 << 1333 Direct I/O support << 1334 ================== << 1335 << 1336 For direct I/O on an encrypted file to work, << 1337 must be met (in addition to the conditions fo << 1338 unencrypted file): << 1339 << 1340 * The file must be using inline encryption. << 1341 the filesystem must be mounted with ``-o in << 1342 encryption hardware must be present. Howev << 1343 is also available. For details, see `Inlin << 1344 << 1345 * The I/O request must be fully aligned to th << 1346 This means that the file position the I/O i << 1347 of all I/O segments, and the memory address << 1348 must be multiples of this value. Note that << 1349 size may be greater than the logical block << 1350 << 1351 If either of the above conditions is not met, << 1352 encrypted file will fall back to buffered I/O << 1353 << 1354 Implementation details 561 Implementation details 1355 ====================== 562 ====================== 1356 563 1357 Encryption context 564 Encryption context 1358 ------------------ 565 ------------------ 1359 566 1360 An encryption policy is represented on-disk b !! 567 An encryption policy is represented on-disk by a :c:type:`struct 1361 struct fscrypt_context_v1 or struct fscrypt_c !! 568 fscrypt_context`. It is up to individual filesystems to decide where 1362 individual filesystems to decide where to sto !! 569 to store it, but normally it would be stored in a hidden extended 1363 would be stored in a hidden extended attribut !! 570 attribute. It should *not* be exposed by the xattr-related system 1364 exposed by the xattr-related system calls suc !! 571 calls such as getxattr() and setxattr() because of the special 1365 setxattr() because of the special semantics o !! 572 semantics of the encryption xattr. (In particular, there would be 1366 (In particular, there would be much confusion !! 573 much confusion if an encryption policy were to be added to or removed 1367 were to be added to or removed from anything !! 574 from anything other than an empty directory.) The struct is defined 1368 directory.) These structs are defined as fol !! 575 as follows:: 1369 !! 576 1370 #define FSCRYPT_FILE_NONCE_SIZE 16 !! 577 #define FS_KEY_DESCRIPTOR_SIZE 8 1371 !! 578 #define FS_KEY_DERIVATION_NONCE_SIZE 16 1372 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 << 1373 struct fscrypt_context_v1 { << 1374 u8 version; << 1375 u8 contents_encryption_mode; << 1376 u8 filenames_encryption_mode; << 1377 u8 flags; << 1378 u8 master_key_descriptor[FSCRYPT_ << 1379 u8 nonce[FSCRYPT_FILE_NONCE_SIZE] << 1380 }; << 1381 579 1382 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 !! 580 struct fscrypt_context { 1383 struct fscrypt_context_v2 { !! 581 u8 format; 1384 u8 version; << 1385 u8 contents_encryption_mode; 582 u8 contents_encryption_mode; 1386 u8 filenames_encryption_mode; 583 u8 filenames_encryption_mode; 1387 u8 flags; 584 u8 flags; 1388 u8 log2_data_unit_size; !! 585 u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; 1389 u8 __reserved[3]; !! 586 u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; 1390 u8 master_key_identifier[FSCRYPT_ << 1391 u8 nonce[FSCRYPT_FILE_NONCE_SIZE] << 1392 }; 587 }; 1393 588 1394 The context structs contain the same informat !! 589 Note that :c:type:`struct fscrypt_context` contains the same 1395 policy structs (see `Setting an encryption po !! 590 information as :c:type:`struct fscrypt_policy` (see `Setting an 1396 context structs also contain a nonce. The no !! 591 encryption policy`_), except that :c:type:`struct fscrypt_context` 1397 by the kernel and is used as KDF input or as !! 592 also contains a nonce. The nonce is randomly generated by the kernel 1398 different files to be encrypted differently; !! 593 and is used to derive the inode's encryption key as described in 1399 keys`_ and `DIRECT_KEY policies`_. !! 594 `Per-file keys`_. 1400 595 1401 Data path changes 596 Data path changes 1402 ----------------- 597 ----------------- 1403 598 1404 When inline encryption is used, filesystems j !! 599 For the read path (->readpage()) of regular files, filesystems can 1405 encryption contexts with bios to specify how << 1406 inline encryption hardware will encrypt/decry << 1407 << 1408 When inline encryption isn't used, filesystem << 1409 the file contents themselves, as described be << 1410 << 1411 For the read path (->read_folio()) of regular << 1412 read the ciphertext into the page cache and d 600 read the ciphertext into the page cache and decrypt it in-place. The 1413 folio lock must be held until decryption has !! 601 page lock must be held until decryption has finished, to prevent the 1414 folio from becoming visible to userspace prem !! 602 page from becoming visible to userspace prematurely. 1415 603 1416 For the write path (->writepage()) of regular 604 For the write path (->writepage()) of regular files, filesystems 1417 cannot encrypt data in-place in the page cach 605 cannot encrypt data in-place in the page cache, since the cached 1418 plaintext must be preserved. Instead, filesy 606 plaintext must be preserved. Instead, filesystems must encrypt into a 1419 temporary buffer or "bounce page", then write 607 temporary buffer or "bounce page", then write out the temporary 1420 buffer. Some filesystems, such as UBIFS, alr 608 buffer. Some filesystems, such as UBIFS, already use temporary 1421 buffers regardless of encryption. Other file 609 buffers regardless of encryption. Other filesystems, such as ext4 and 1422 F2FS, have to allocate bounce pages specially 610 F2FS, have to allocate bounce pages specially for encryption. 1423 611 1424 Filename hashing and encoding 612 Filename hashing and encoding 1425 ----------------------------- 613 ----------------------------- 1426 614 1427 Modern filesystems accelerate directory looku 615 Modern filesystems accelerate directory lookups by using indexed 1428 directories. An indexed directory is organiz 616 directories. An indexed directory is organized as a tree keyed by 1429 filename hashes. When a ->lookup() is reques 617 filename hashes. When a ->lookup() is requested, the filesystem 1430 normally hashes the filename being looked up 618 normally hashes the filename being looked up so that it can quickly 1431 find the corresponding directory entry, if an 619 find the corresponding directory entry, if any. 1432 620 1433 With encryption, lookups must be supported an 621 With encryption, lookups must be supported and efficient both with and 1434 without the encryption key. Clearly, it woul 622 without the encryption key. Clearly, it would not work to hash the 1435 plaintext filenames, since the plaintext file 623 plaintext filenames, since the plaintext filenames are unavailable 1436 without the key. (Hashing the plaintext file 624 without the key. (Hashing the plaintext filenames would also make it 1437 impossible for the filesystem's fsck tool to 625 impossible for the filesystem's fsck tool to optimize encrypted 1438 directories.) Instead, filesystems hash the 626 directories.) Instead, filesystems hash the ciphertext filenames, 1439 i.e. the bytes actually stored on-disk in the 627 i.e. the bytes actually stored on-disk in the directory entries. When 1440 asked to do a ->lookup() with the key, the fi 628 asked to do a ->lookup() with the key, the filesystem just encrypts 1441 the user-supplied name to get the ciphertext. 629 the user-supplied name to get the ciphertext. 1442 630 1443 Lookups without the key are more complicated. 631 Lookups without the key are more complicated. The raw ciphertext may 1444 contain the ``\0`` and ``/`` characters, whic 632 contain the ``\0`` and ``/`` characters, which are illegal in 1445 filenames. Therefore, readdir() must base64u !! 633 filenames. Therefore, readdir() must base64-encode the ciphertext for 1446 for presentation. For most filenames, this w !! 634 presentation. For most filenames, this works fine; on ->lookup(), the 1447 the filesystem just base64url-decodes the use !! 635 filesystem just base64-decodes the user-supplied name to get back to 1448 back to the raw ciphertext. !! 636 the raw ciphertext. 1449 637 1450 However, for very long filenames, base64url e !! 638 However, for very long filenames, base64 encoding would cause the 1451 filename length to exceed NAME_MAX. To preve 639 filename length to exceed NAME_MAX. To prevent this, readdir() 1452 actually presents long filenames in an abbrev 640 actually presents long filenames in an abbreviated form which encodes 1453 a strong "hash" of the ciphertext filename, a 641 a strong "hash" of the ciphertext filename, along with the optional 1454 filesystem-specific hash(es) needed for direc 642 filesystem-specific hash(es) needed for directory lookups. This 1455 allows the filesystem to still, with a high d 643 allows the filesystem to still, with a high degree of confidence, map 1456 the filename given in ->lookup() back to a pa 644 the filename given in ->lookup() back to a particular directory entry 1457 that was previously listed by readdir(). See !! 645 that was previously listed by readdir(). See :c:type:`struct 1458 struct fscrypt_nokey_name in the source for m !! 646 fscrypt_digested_name` in the source for more details. 1459 647 1460 Note that the precise way that filenames are 648 Note that the precise way that filenames are presented to userspace 1461 without the key is subject to change in the f 649 without the key is subject to change in the future. It is only meant 1462 as a way to temporarily present valid filenam 650 as a way to temporarily present valid filenames so that commands like 1463 ``rm -r`` work as expected on encrypted direc 651 ``rm -r`` work as expected on encrypted directories. 1464 652 1465 Tests 653 Tests 1466 ===== 654 ===== 1467 655 1468 To test fscrypt, use xfstests, which is Linux 656 To test fscrypt, use xfstests, which is Linux's de facto standard 1469 filesystem test suite. First, run all the te 657 filesystem test suite. First, run all the tests in the "encrypt" 1470 group on the relevant filesystem(s). One can !! 658 group on the relevant filesystem(s). For example, to test ext4 and 1471 with the 'inlinecrypt' mount option to test t << 1472 inline encryption support. For example, to t << 1473 f2fs encryption using `kvm-xfstests 659 f2fs encryption using `kvm-xfstests 1474 <https://github.com/tytso/xfstests-bld/blob/m 660 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: 1475 661 1476 kvm-xfstests -c ext4,f2fs -g encrypt 662 kvm-xfstests -c ext4,f2fs -g encrypt 1477 kvm-xfstests -c ext4,f2fs -g encrypt -m i << 1478 663 1479 UBIFS encryption can also be tested this way, 664 UBIFS encryption can also be tested this way, but it should be done in 1480 a separate command, and it takes some time fo 665 a separate command, and it takes some time for kvm-xfstests to set up 1481 emulated UBI volumes:: 666 emulated UBI volumes:: 1482 667 1483 kvm-xfstests -c ubifs -g encrypt 668 kvm-xfstests -c ubifs -g encrypt 1484 669 1485 No tests should fail. However, tests that us 670 No tests should fail. However, tests that use non-default encryption 1486 modes (e.g. generic/549 and generic/550) will 671 modes (e.g. generic/549 and generic/550) will be skipped if the needed 1487 algorithms were not built into the kernel's c 672 algorithms were not built into the kernel's crypto API. Also, tests 1488 that access the raw block device (e.g. generi 673 that access the raw block device (e.g. generic/399, generic/548, 1489 generic/549, generic/550) will be skipped on 674 generic/549, generic/550) will be skipped on UBIFS. 1490 675 1491 Besides running the "encrypt" group tests, fo 676 Besides running the "encrypt" group tests, for ext4 and f2fs it's also 1492 possible to run most xfstests with the "test_ 677 possible to run most xfstests with the "test_dummy_encryption" mount 1493 option. This option causes all new files to 678 option. This option causes all new files to be automatically 1494 encrypted with a dummy key, without having to 679 encrypted with a dummy key, without having to make any API calls. 1495 This tests the encrypted I/O paths more thoro 680 This tests the encrypted I/O paths more thoroughly. To do this with 1496 kvm-xfstests, use the "encrypt" filesystem co 681 kvm-xfstests, use the "encrypt" filesystem configuration:: 1497 682 1498 kvm-xfstests -c ext4/encrypt,f2fs/encrypt 683 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 1499 kvm-xfstests -c ext4/encrypt,f2fs/encrypt << 1500 684 1501 Because this runs many more tests than "-g en 685 Because this runs many more tests than "-g encrypt" does, it takes 1502 much longer to run; so also consider using `g 686 much longer to run; so also consider using `gce-xfstests 1503 <https://github.com/tytso/xfstests-bld/blob/m 687 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_ 1504 instead of kvm-xfstests:: 688 instead of kvm-xfstests:: 1505 689 1506 gce-xfstests -c ext4/encrypt,f2fs/encrypt 690 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 1507 gce-xfstests -c ext4/encrypt,f2fs/encrypt <<

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/Documentation/filesystems/fscrypt.rst

Diff markup

Differences between /Documentation/filesystems/fscrypt.rst (Version linux-6.12-rc7) and /Documentation/filesystems/fscrypt.rst (Version linux-5.3.18)

TOMOYO Linux Cross Reference Linux/Documentation/filesystems/fscrypt.rst

Diff markup

Differences between /Documentation/filesystems/fscrypt.rst (Version linux-6.12-rc7) and /Documentation/filesystems/fscrypt.rst (Version linux-5.3.18)

TOMOYO Linux Cross Reference
Linux/Documentation/filesystems/fscrypt.rst