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