Commit | Line | Data |
---|---|---|
f4f864c1 EB |
1 | ===================================== |
2 | Filesystem-level encryption (fscrypt) | |
3 | ===================================== | |
4 | ||
5 | Introduction | |
6 | ============ | |
7 | ||
8 | fscrypt is a library which filesystems can hook into to support | |
9 | transparent encryption of files and directories. | |
10 | ||
11 | Note: "fscrypt" in this document refers to the kernel-level portion, | |
12 | implemented in ``fs/crypto/``, as opposed to the userspace tool | |
13 | `fscrypt <https://github.com/google/fscrypt>`_. This document only | |
14 | covers the kernel-level portion. For command-line examples of how to | |
15 | use encryption, see the documentation for the userspace tool `fscrypt | |
16 | <https://github.com/google/fscrypt>`_. Also, it is recommended to use | |
17 | the fscrypt userspace tool, or other existing userspace tools such as | |
18 | `fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key | |
19 | management system | |
20 | <https://source.android.com/security/encryption/file-based>`_, over | |
21 | using the kernel's API directly. Using existing tools reduces the | |
22 | chance of introducing your own security bugs. (Nevertheless, for | |
23 | completeness this documentation covers the kernel's API anyway.) | |
24 | ||
25 | Unlike dm-crypt, fscrypt operates at the filesystem level rather than | |
26 | at the block device level. This allows it to encrypt different files | |
27 | with different keys and to have unencrypted files on the same | |
28 | filesystem. This is useful for multi-user systems where each user's | |
29 | data-at-rest needs to be cryptographically isolated from the others. | |
30 | However, except for filenames, fscrypt does not encrypt filesystem | |
31 | metadata. | |
32 | ||
33 | Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated | |
34 | directly into supported filesystems --- currently ext4, F2FS, and | |
35 | UBIFS. This allows encrypted files to be read and written without | |
36 | caching both the decrypted and encrypted pages in the pagecache, | |
37 | thereby nearly halving the memory used and bringing it in line with | |
38 | unencrypted files. Similarly, half as many dentries and inodes are | |
39 | needed. eCryptfs also limits encrypted filenames to 143 bytes, | |
40 | causing application compatibility issues; fscrypt allows the full 255 | |
41 | bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be | |
42 | used by unprivileged users, with no need to mount anything. | |
43 | ||
44 | fscrypt does not support encrypting files in-place. Instead, it | |
45 | supports marking an empty directory as encrypted. Then, after | |
46 | userspace provides the key, all regular files, directories, and | |
47 | symbolic links created in that directory tree are transparently | |
48 | encrypted. | |
49 | ||
50 | Threat model | |
51 | ============ | |
52 | ||
53 | Offline attacks | |
54 | --------------- | |
55 | ||
56 | Provided that userspace chooses a strong encryption key, fscrypt | |
57 | protects the confidentiality of file contents and filenames in the | |
58 | event of a single point-in-time permanent offline compromise of the | |
59 | block device content. fscrypt does not protect the confidentiality of | |
60 | non-filename metadata, e.g. file sizes, file permissions, file | |
61 | timestamps, and extended attributes. Also, the existence and location | |
62 | of holes (unallocated blocks which logically contain all zeroes) in | |
63 | files is not protected. | |
64 | ||
65 | fscrypt is not guaranteed to protect confidentiality or authenticity | |
66 | if an attacker is able to manipulate the filesystem offline prior to | |
67 | an authorized user later accessing the filesystem. | |
68 | ||
69 | Online attacks | |
70 | -------------- | |
71 | ||
72 | fscrypt (and storage encryption in general) can only provide limited | |
73 | protection, if any at all, against online attacks. In detail: | |
74 | ||
ba13f2c8 EB |
75 | Side-channel attacks |
76 | ~~~~~~~~~~~~~~~~~~~~ | |
77 | ||
f4f864c1 EB |
78 | fscrypt is only resistant to side-channel attacks, such as timing or |
79 | electromagnetic attacks, to the extent that the underlying Linux | |
80 | Cryptographic API algorithms are. If a vulnerable algorithm is used, | |
81 | such as a table-based implementation of AES, it may be possible for an | |
82 | attacker to mount a side channel attack against the online system. | |
83 | Side channel attacks may also be mounted against applications | |
84 | consuming decrypted data. | |
85 | ||
ba13f2c8 EB |
86 | Unauthorized file access |
87 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
88 | ||
89 | After an encryption key has been added, fscrypt does not hide the | |
90 | plaintext file contents or filenames from other users on the same | |
91 | system. Instead, existing access control mechanisms such as file mode | |
92 | bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose. | |
93 | ||
94 | (For the reasoning behind this, understand that while the key is | |
95 | added, the confidentiality of the data, from the perspective of the | |
96 | system itself, is *not* protected by the mathematical properties of | |
97 | encryption but rather only by the correctness of the kernel. | |
98 | Therefore, any encryption-specific access control checks would merely | |
99 | be enforced by kernel *code* and therefore would be largely redundant | |
100 | with the wide variety of access control mechanisms already available.) | |
101 | ||
102 | Kernel memory compromise | |
103 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
104 | ||
105 | An attacker who compromises the system enough to read from arbitrary | |
106 | memory, e.g. by mounting a physical attack or by exploiting a kernel | |
107 | security vulnerability, can compromise all encryption keys that are | |
108 | currently in use. | |
109 | ||
110 | However, fscrypt allows encryption keys to be removed from the kernel, | |
111 | which may protect them from later compromise. | |
112 | ||
113 | In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the | |
114 | FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master | |
115 | encryption key from kernel memory. If it does so, it will also try to | |
116 | evict all cached inodes which had been "unlocked" using the key, | |
117 | thereby wiping their per-file keys and making them once again appear | |
118 | "locked", i.e. in ciphertext or encrypted form. | |
119 | ||
120 | However, these ioctls have some limitations: | |
121 | ||
122 | - Per-file keys for in-use files will *not* be removed or wiped. | |
123 | Therefore, for maximum effect, userspace should close the relevant | |
124 | encrypted files and directories before removing a master key, as | |
125 | well as kill any processes whose working directory is in an affected | |
126 | encrypted directory. | |
127 | ||
128 | - The kernel cannot magically wipe copies of the master key(s) that | |
129 | userspace might have as well. Therefore, userspace must wipe all | |
130 | copies of the master key(s) it makes as well; normally this should | |
131 | be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting | |
132 | for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies | |
133 | to all higher levels in the key hierarchy. Userspace should also | |
134 | follow other security precautions such as mlock()ing memory | |
135 | containing keys to prevent it from being swapped out. | |
136 | ||
137 | - In general, decrypted contents and filenames in the kernel VFS | |
138 | caches are freed but not wiped. Therefore, portions thereof may be | |
139 | recoverable from freed memory, even after the corresponding key(s) | |
140 | were wiped. To partially solve this, you can set | |
141 | CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1 | |
142 | to your kernel command line. However, this has a performance cost. | |
143 | ||
144 | - Secret keys might still exist in CPU registers, in crypto | |
145 | accelerator hardware (if used by the crypto API to implement any of | |
146 | the algorithms), or in other places not explicitly considered here. | |
147 | ||
148 | Limitations of v1 policies | |
149 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
150 | ||
151 | v1 encryption policies have some weaknesses with respect to online | |
152 | attacks: | |
153 | ||
154 | - There is no verification that the provided master key is correct. | |
155 | Therefore, a malicious user can temporarily associate the wrong key | |
156 | with another user's encrypted files to which they have read-only | |
157 | access. Because of filesystem caching, the wrong key will then be | |
158 | used by the other user's accesses to those files, even if the other | |
159 | user has the correct key in their own keyring. This violates the | |
160 | meaning of "read-only access". | |
161 | ||
162 | - A compromise of a per-file key also compromises the master key from | |
163 | which it was derived. | |
164 | ||
165 | - Non-root users cannot securely remove encryption keys. | |
166 | ||
167 | All the above problems are fixed with v2 encryption policies. For | |
168 | this reason among others, it is recommended to use v2 encryption | |
169 | policies on all new encrypted directories. | |
f4f864c1 EB |
170 | |
171 | Key hierarchy | |
172 | ============= | |
173 | ||
174 | Master Keys | |
175 | ----------- | |
176 | ||
177 | Each encrypted directory tree is protected by a *master key*. Master | |
178 | keys can be up to 64 bytes long, and must be at least as long as the | |
179 | greater of the key length needed by the contents and filenames | |
180 | encryption modes being used. For example, if AES-256-XTS is used for | |
181 | contents encryption, the master key must be 64 bytes (512 bits). Note | |
182 | that the XTS mode is defined to require a key twice as long as that | |
183 | required by the underlying block cipher. | |
184 | ||
185 | To "unlock" an encrypted directory tree, userspace must provide the | |
186 | appropriate master key. There can be any number of master keys, each | |
187 | of which protects any number of directory trees on any number of | |
188 | filesystems. | |
189 | ||
ba13f2c8 EB |
190 | Master keys must be real cryptographic keys, i.e. indistinguishable |
191 | from random bytestrings of the same length. This implies that users | |
192 | **must not** directly use a password as a master key, zero-pad a | |
193 | shorter key, or repeat a shorter key. Security cannot be guaranteed | |
194 | if userspace makes any such error, as the cryptographic proofs and | |
195 | analysis would no longer apply. | |
196 | ||
197 | Instead, users should generate master keys either using a | |
198 | cryptographically secure random number generator, or by using a KDF | |
199 | (Key Derivation Function). The kernel does not do any key stretching; | |
200 | therefore, if userspace derives the key from a low-entropy secret such | |
201 | as a passphrase, it is critical that a KDF designed for this purpose | |
202 | be used, such as scrypt, PBKDF2, or Argon2. | |
203 | ||
204 | Key derivation function | |
205 | ----------------------- | |
206 | ||
207 | With one exception, fscrypt never uses the master key(s) for | |
208 | encryption directly. Instead, they are only used as input to a KDF | |
209 | (Key Derivation Function) to derive the actual keys. | |
210 | ||
211 | The KDF used for a particular master key differs depending on whether | |
212 | the key is used for v1 encryption policies or for v2 encryption | |
213 | policies. Users **must not** use the same key for both v1 and v2 | |
214 | encryption policies. (No real-world attack is currently known on this | |
215 | specific case of key reuse, but its security cannot be guaranteed | |
216 | since the cryptographic proofs and analysis would no longer apply.) | |
217 | ||
218 | For v1 encryption policies, the KDF only supports deriving per-file | |
219 | encryption keys. It works by encrypting the master key with | |
220 | AES-128-ECB, using the file's 16-byte nonce as the AES key. The | |
221 | resulting ciphertext is used as the derived key. If the ciphertext is | |
222 | longer than needed, then it is truncated to the needed length. | |
223 | ||
224 | For v2 encryption policies, the KDF is HKDF-SHA512. The master key is | |
225 | passed as the "input keying material", no salt is used, and a distinct | |
226 | "application-specific information string" is used for each distinct | |
227 | key to be derived. For example, when a per-file encryption key is | |
228 | derived, the application-specific information string is the file's | |
229 | nonce prefixed with "fscrypt\\0" and a context byte. Different | |
230 | context bytes are used for other types of derived keys. | |
231 | ||
232 | HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because | |
233 | HKDF is more flexible, is nonreversible, and evenly distributes | |
234 | entropy from the master key. HKDF is also standardized and widely | |
235 | used by other software, whereas the AES-128-ECB based KDF is ad-hoc. | |
f4f864c1 EB |
236 | |
237 | Per-file keys | |
238 | ------------- | |
239 | ||
8094c3ce EB |
240 | Since each master key can protect many files, it is necessary to |
241 | "tweak" the encryption of each file so that the same plaintext in two | |
242 | files doesn't map to the same ciphertext, or vice versa. In most | |
243 | cases, fscrypt does this by deriving per-file keys. When a new | |
244 | encrypted inode (regular file, directory, or symlink) is created, | |
245 | fscrypt randomly generates a 16-byte nonce and stores it in the | |
ba13f2c8 EB |
246 | inode's encryption xattr. Then, it uses a KDF (as described in `Key |
247 | derivation function`_) to derive the file's key from the master key | |
248 | and nonce. | |
f4f864c1 | 249 | |
8094c3ce EB |
250 | Key derivation was chosen over key wrapping because wrapped keys would |
251 | require larger xattrs which would be less likely to fit in-line in the | |
252 | filesystem's inode table, and there didn't appear to be any | |
253 | significant advantages to key wrapping. In particular, currently | |
254 | there is no requirement to support unlocking a file with multiple | |
255 | alternative master keys or to support rotating master keys. Instead, | |
256 | the master keys may be wrapped in userspace, e.g. as is done by the | |
257 | `fscrypt <https://github.com/google/fscrypt>`_ tool. | |
258 | ||
b103fb76 EB |
259 | DIRECT_KEY policies |
260 | ------------------- | |
ba13f2c8 EB |
261 | |
262 | The Adiantum encryption mode (see `Encryption modes and usage`_) is | |
263 | suitable for both contents and filenames encryption, and it accepts | |
264 | long IVs --- long enough to hold both an 8-byte logical block number | |
265 | and a 16-byte per-file nonce. Also, the overhead of each Adiantum key | |
266 | is greater than that of an AES-256-XTS key. | |
267 | ||
268 | Therefore, to improve performance and save memory, for Adiantum a | |
269 | "direct key" configuration is supported. When the user has enabled | |
270 | this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy, | |
271 | per-file keys are not used. Instead, whenever any data (contents or | |
272 | filenames) is encrypted, the file's 16-byte nonce is included in the | |
273 | IV. Moreover: | |
274 | ||
275 | - For v1 encryption policies, the encryption is done directly with the | |
276 | master key. Because of this, users **must not** use the same master | |
277 | key for any other purpose, even for other v1 policies. | |
278 | ||
279 | - For v2 encryption policies, the encryption is done with a per-mode | |
280 | key derived using the KDF. Users may use the same master key for | |
281 | other v2 encryption policies. | |
282 | ||
b103fb76 EB |
283 | IV_INO_LBLK_64 policies |
284 | ----------------------- | |
285 | ||
286 | When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy, | |
287 | the encryption keys are derived from the master key, encryption mode | |
288 | number, and filesystem UUID. This normally results in all files | |
289 | protected by the same master key sharing a single contents encryption | |
290 | key and a single filenames encryption key. To still encrypt different | |
291 | files' data differently, inode numbers are included in the IVs. | |
292 | Consequently, shrinking the filesystem may not be allowed. | |
293 | ||
294 | This format is optimized for use with inline encryption hardware | |
295 | compliant with the UFS or eMMC standards, which support only 64 IV | |
296 | bits per I/O request and may have only a small number of keyslots. | |
297 | ||
ba13f2c8 EB |
298 | Key identifiers |
299 | --------------- | |
300 | ||
301 | For master keys used for v2 encryption policies, a unique 16-byte "key | |
302 | identifier" is also derived using the KDF. This value is stored in | |
303 | the clear, since it is needed to reliably identify the key itself. | |
304 | ||
aa408f83 DR |
305 | Dirhash keys |
306 | ------------ | |
307 | ||
308 | For directories that are indexed using a secret-keyed dirhash over the | |
309 | plaintext filenames, the KDF is also used to derive a 128-bit | |
310 | SipHash-2-4 key per directory in order to hash filenames. This works | |
311 | just like deriving a per-file encryption key, except that a different | |
312 | KDF context is used. Currently, only casefolded ("case-insensitive") | |
313 | encrypted directories use this style of hashing. | |
314 | ||
f4f864c1 EB |
315 | Encryption modes and usage |
316 | ========================== | |
317 | ||
318 | fscrypt allows one encryption mode to be specified for file contents | |
319 | and one encryption mode to be specified for filenames. Different | |
320 | directory trees are permitted to use different encryption modes. | |
321 | Currently, the following pairs of encryption modes are supported: | |
322 | ||
323 | - AES-256-XTS for contents and AES-256-CTS-CBC for filenames | |
324 | - AES-128-CBC for contents and AES-128-CTS-CBC for filenames | |
8094c3ce EB |
325 | - Adiantum for both contents and filenames |
326 | ||
327 | If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. | |
f4f864c1 | 328 | |
f4f864c1 | 329 | AES-128-CBC was added only for low-powered embedded devices with |
adbd9b4d | 330 | crypto accelerators such as CAAM or CESA that do not support XTS. To |
4006d799 EB |
331 | use AES-128-CBC, CONFIG_CRYPTO_ESSIV and CONFIG_CRYPTO_SHA256 (or |
332 | another SHA-256 implementation) must be enabled so that ESSIV can be | |
333 | used. | |
f4f864c1 | 334 | |
8094c3ce EB |
335 | Adiantum is a (primarily) stream cipher-based mode that is fast even |
336 | on CPUs without dedicated crypto instructions. It's also a true | |
337 | wide-block mode, unlike XTS. It can also eliminate the need to derive | |
338 | per-file keys. However, it depends on the security of two primitives, | |
339 | XChaCha12 and AES-256, rather than just one. See the paper | |
340 | "Adiantum: length-preserving encryption for entry-level processors" | |
341 | (https://eprint.iacr.org/2018/720.pdf) for more details. To use | |
342 | Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast | |
343 | implementations of ChaCha and NHPoly1305 should be enabled, e.g. | |
344 | CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. | |
345 | ||
f4f864c1 EB |
346 | New encryption modes can be added relatively easily, without changes |
347 | to individual filesystems. However, authenticated encryption (AE) | |
348 | modes are not currently supported because of the difficulty of dealing | |
349 | with ciphertext expansion. | |
350 | ||
8094c3ce EB |
351 | Contents encryption |
352 | ------------------- | |
353 | ||
f4f864c1 | 354 | For file contents, each filesystem block is encrypted independently. |
196624e1 CR |
355 | Starting from Linux kernel 5.5, encryption of filesystems with block |
356 | size less than system's page size is supported. | |
8094c3ce EB |
357 | |
358 | Each block's IV is set to the logical block number within the file as | |
359 | a little endian number, except that: | |
360 | ||
361 | - With CBC mode encryption, ESSIV is also used. Specifically, each IV | |
362 | is encrypted with AES-256 where the AES-256 key is the SHA-256 hash | |
363 | of the file's data encryption key. | |
364 | ||
b103fb76 EB |
365 | - With `DIRECT_KEY policies`_, the file's nonce is appended to the IV. |
366 | Currently this is only allowed with the Adiantum encryption mode. | |
367 | ||
368 | - With `IV_INO_LBLK_64 policies`_, the logical block number is limited | |
369 | to 32 bits and is placed in bits 0-31 of the IV. The inode number | |
370 | (which is also limited to 32 bits) is placed in bits 32-63. | |
371 | ||
372 | Note that because file logical block numbers are included in the IVs, | |
373 | filesystems must enforce that blocks are never shifted around within | |
374 | encrypted files, e.g. via "collapse range" or "insert range". | |
8094c3ce EB |
375 | |
376 | Filenames encryption | |
377 | -------------------- | |
378 | ||
379 | For filenames, each full filename is encrypted at once. Because of | |
380 | the requirements to retain support for efficient directory lookups and | |
381 | filenames of up to 255 bytes, the same IV is used for every filename | |
382 | in a directory. | |
383 | ||
b103fb76 EB |
384 | However, each encrypted directory still uses a unique key, or |
385 | alternatively has the file's nonce (for `DIRECT_KEY policies`_) or | |
386 | inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. | |
387 | Thus, IV reuse is limited to within a single directory. | |
8094c3ce EB |
388 | |
389 | With CTS-CBC, the IV reuse means that when the plaintext filenames | |
390 | share a common prefix at least as long as the cipher block size (16 | |
391 | bytes for AES), the corresponding encrypted filenames will also share | |
392 | a common prefix. This is undesirable. Adiantum does not have this | |
393 | weakness, as it is a wide-block encryption mode. | |
394 | ||
395 | All supported filenames encryption modes accept any plaintext length | |
396 | >= 16 bytes; cipher block alignment is not required. However, | |
397 | filenames shorter than 16 bytes are NUL-padded to 16 bytes before | |
398 | being encrypted. In addition, to reduce leakage of filename lengths | |
399 | via their ciphertexts, all filenames are NUL-padded to the next 4, 8, | |
400 | 16, or 32-byte boundary (configurable). 32 is recommended since this | |
401 | provides the best confidentiality, at the cost of making directory | |
402 | entries consume slightly more space. Note that since NUL (``\0``) is | |
403 | not otherwise a valid character in filenames, the padding will never | |
404 | produce duplicate plaintexts. | |
f4f864c1 EB |
405 | |
406 | Symbolic link targets are considered a type of filename and are | |
8094c3ce EB |
407 | encrypted in the same way as filenames in directory entries, except |
408 | that IV reuse is not a problem as each symlink has its own inode. | |
f4f864c1 EB |
409 | |
410 | User API | |
411 | ======== | |
412 | ||
413 | Setting an encryption policy | |
414 | ---------------------------- | |
415 | ||
ba13f2c8 EB |
416 | FS_IOC_SET_ENCRYPTION_POLICY |
417 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
418 | ||
f4f864c1 EB |
419 | The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an |
420 | empty directory or verifies that a directory or regular file already | |
421 | has the specified encryption policy. It takes in a pointer to a | |
ba13f2c8 EB |
422 | :c:type:`struct fscrypt_policy_v1` or a :c:type:`struct |
423 | fscrypt_policy_v2`, defined as follows:: | |
f4f864c1 | 424 | |
ba13f2c8 EB |
425 | #define FSCRYPT_POLICY_V1 0 |
426 | #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 | |
427 | struct fscrypt_policy_v1 { | |
f4f864c1 EB |
428 | __u8 version; |
429 | __u8 contents_encryption_mode; | |
430 | __u8 filenames_encryption_mode; | |
431 | __u8 flags; | |
2336d0de | 432 | __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; |
f4f864c1 | 433 | }; |
ba13f2c8 EB |
434 | #define fscrypt_policy fscrypt_policy_v1 |
435 | ||
436 | #define FSCRYPT_POLICY_V2 2 | |
437 | #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 | |
438 | struct fscrypt_policy_v2 { | |
439 | __u8 version; | |
440 | __u8 contents_encryption_mode; | |
441 | __u8 filenames_encryption_mode; | |
442 | __u8 flags; | |
443 | __u8 __reserved[4]; | |
444 | __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; | |
445 | }; | |
f4f864c1 EB |
446 | |
447 | This structure must be initialized as follows: | |
448 | ||
ba13f2c8 EB |
449 | - ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is |
450 | :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct | |
451 | is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original | |
452 | policy version as "v1", though its version code is really 0.) For | |
453 | new encrypted directories, use v2 policies. | |
f4f864c1 EB |
454 | |
455 | - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must | |
2336d0de EB |
456 | be set to constants from ``<linux/fscrypt.h>`` which identify the |
457 | encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS | |
458 | (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS | |
459 | (4) for ``filenames_encryption_mode``. | |
f4f864c1 | 460 | |
b103fb76 EB |
461 | - ``flags`` contains optional flags from ``<linux/fscrypt.h>``: |
462 | ||
463 | - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when | |
464 | encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 | |
465 | (0x3). | |
466 | - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_. | |
467 | - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64 | |
468 | policies`_. This is mutually exclusive with DIRECT_KEY and is not | |
469 | supported on v1 policies. | |
ba13f2c8 EB |
470 | |
471 | - For v2 encryption policies, ``__reserved`` must be zeroed. | |
f4f864c1 | 472 | |
ba13f2c8 EB |
473 | - For v1 encryption policies, ``master_key_descriptor`` specifies how |
474 | to find the master key in a keyring; see `Adding keys`_. It is up | |
475 | to userspace to choose a unique ``master_key_descriptor`` for each | |
476 | master key. The e4crypt and fscrypt tools use the first 8 bytes of | |
f4f864c1 EB |
477 | ``SHA-512(SHA-512(master_key))``, but this particular scheme is not |
478 | required. Also, the master key need not be in the keyring yet when | |
479 | FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added | |
480 | before any files can be created in the encrypted directory. | |
481 | ||
ba13f2c8 EB |
482 | For v2 encryption policies, ``master_key_descriptor`` has been |
483 | replaced with ``master_key_identifier``, which is longer and cannot | |
484 | be arbitrarily chosen. Instead, the key must first be added using | |
485 | `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` | |
486 | the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must | |
487 | be used as the ``master_key_identifier`` in the :c:type:`struct | |
488 | fscrypt_policy_v2`. | |
489 | ||
f4f864c1 EB |
490 | If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY |
491 | verifies that the file is an empty directory. If so, the specified | |
492 | encryption policy is assigned to the directory, turning it into an | |
493 | encrypted directory. After that, and after providing the | |
494 | corresponding master key as described in `Adding keys`_, all regular | |
495 | files, directories (recursively), and symlinks created in the | |
496 | directory will be encrypted, inheriting the same encryption policy. | |
497 | The filenames in the directory's entries will be encrypted as well. | |
498 | ||
499 | Alternatively, if the file is already encrypted, then | |
500 | FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption | |
501 | policy exactly matches the actual one. If they match, then the ioctl | |
502 | returns 0. Otherwise, it fails with EEXIST. This works on both | |
503 | regular files and directories, including nonempty directories. | |
504 | ||
ba13f2c8 EB |
505 | When a v2 encryption policy is assigned to a directory, it is also |
506 | required that either the specified key has been added by the current | |
507 | user or that the caller has CAP_FOWNER in the initial user namespace. | |
508 | (This is needed to prevent a user from encrypting their data with | |
509 | another user's key.) The key must remain added while | |
510 | FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new | |
511 | encrypted directory does not need to be accessed immediately, then the | |
512 | key can be removed right away afterwards. | |
513 | ||
f4f864c1 EB |
514 | Note that the ext4 filesystem does not allow the root directory to be |
515 | encrypted, even if it is empty. Users who want to encrypt an entire | |
516 | filesystem with one key should consider using dm-crypt instead. | |
517 | ||
518 | FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: | |
519 | ||
520 | - ``EACCES``: the file is not owned by the process's uid, nor does the | |
521 | process have the CAP_FOWNER capability in a namespace with the file | |
522 | owner's uid mapped | |
523 | - ``EEXIST``: the file is already encrypted with an encryption policy | |
524 | different from the one specified | |
525 | - ``EINVAL``: an invalid encryption policy was specified (invalid | |
6e1918cf DR |
526 | version, mode(s), or flags; or reserved bits were set); or a v1 |
527 | encryption policy was specified but the directory has the casefold | |
528 | flag enabled (casefolding is incompatible with v1 policies). | |
ba13f2c8 EB |
529 | - ``ENOKEY``: a v2 encryption policy was specified, but the key with |
530 | the specified ``master_key_identifier`` has not been added, nor does | |
531 | the process have the CAP_FOWNER capability in the initial user | |
532 | namespace | |
f4f864c1 EB |
533 | - ``ENOTDIR``: the file is unencrypted and is a regular file, not a |
534 | directory | |
535 | - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory | |
536 | - ``ENOTTY``: this type of filesystem does not implement encryption | |
537 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
643fa961 | 538 | support for filesystems, or the filesystem superblock has not |
f4f864c1 | 539 | had encryption enabled on it. (For example, to use encryption on an |
643fa961 | 540 | ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the |
f4f864c1 EB |
541 | kernel config, and the superblock must have had the "encrypt" |
542 | feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O | |
543 | encrypt``.) | |
544 | - ``EPERM``: this directory may not be encrypted, e.g. because it is | |
545 | the root directory of an ext4 filesystem | |
546 | - ``EROFS``: the filesystem is readonly | |
547 | ||
548 | Getting an encryption policy | |
549 | ---------------------------- | |
550 | ||
ba13f2c8 EB |
551 | Two ioctls are available to get a file's encryption policy: |
552 | ||
553 | - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_ | |
554 | - `FS_IOC_GET_ENCRYPTION_POLICY`_ | |
555 | ||
556 | The extended (_EX) version of the ioctl is more general and is | |
557 | recommended to use when possible. However, on older kernels only the | |
558 | original ioctl is available. Applications should try the extended | |
559 | version, and if it fails with ENOTTY fall back to the original | |
560 | version. | |
561 | ||
562 | FS_IOC_GET_ENCRYPTION_POLICY_EX | |
563 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
564 | ||
565 | The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption | |
566 | policy, if any, for a directory or regular file. No additional | |
567 | permissions are required beyond the ability to open the file. It | |
568 | takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`, | |
569 | defined as follows:: | |
570 | ||
571 | struct fscrypt_get_policy_ex_arg { | |
572 | __u64 policy_size; /* input/output */ | |
573 | union { | |
574 | __u8 version; | |
575 | struct fscrypt_policy_v1 v1; | |
576 | struct fscrypt_policy_v2 v2; | |
577 | } policy; /* output */ | |
578 | }; | |
579 | ||
580 | The caller must initialize ``policy_size`` to the size available for | |
581 | the policy struct, i.e. ``sizeof(arg.policy)``. | |
582 | ||
583 | On success, the policy struct is returned in ``policy``, and its | |
584 | actual size is returned in ``policy_size``. ``policy.version`` should | |
585 | be checked to determine the version of policy returned. Note that the | |
586 | version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1). | |
f4f864c1 | 587 | |
ba13f2c8 | 588 | FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors: |
f4f864c1 EB |
589 | |
590 | - ``EINVAL``: the file is encrypted, but it uses an unrecognized | |
ba13f2c8 | 591 | encryption policy version |
f4f864c1 | 592 | - ``ENODATA``: the file is not encrypted |
ba13f2c8 EB |
593 | - ``ENOTTY``: this type of filesystem does not implement encryption, |
594 | or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX | |
595 | (try FS_IOC_GET_ENCRYPTION_POLICY instead) | |
f4f864c1 | 596 | - ``EOPNOTSUPP``: the kernel was not configured with encryption |
0642ea24 CY |
597 | support for this filesystem, or the filesystem superblock has not |
598 | had encryption enabled on it | |
ba13f2c8 EB |
599 | - ``EOVERFLOW``: the file is encrypted and uses a recognized |
600 | encryption policy version, but the policy struct does not fit into | |
601 | the provided buffer | |
f4f864c1 EB |
602 | |
603 | Note: if you only need to know whether a file is encrypted or not, on | |
604 | most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl | |
605 | and check for FS_ENCRYPT_FL, or to use the statx() system call and | |
606 | check for STATX_ATTR_ENCRYPTED in stx_attributes. | |
607 | ||
ba13f2c8 EB |
608 | FS_IOC_GET_ENCRYPTION_POLICY |
609 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
610 | ||
611 | The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the | |
612 | encryption policy, if any, for a directory or regular file. However, | |
613 | unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, | |
614 | FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy | |
615 | version. It takes in a pointer directly to a :c:type:`struct | |
616 | fscrypt_policy_v1` rather than a :c:type:`struct | |
617 | fscrypt_get_policy_ex_arg`. | |
618 | ||
619 | The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those | |
620 | for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that | |
621 | FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is | |
622 | encrypted using a newer encryption policy version. | |
623 | ||
f4f864c1 EB |
624 | Getting the per-filesystem salt |
625 | ------------------------------- | |
626 | ||
627 | Some filesystems, such as ext4 and F2FS, also support the deprecated | |
628 | ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly | |
629 | generated 16-byte value stored in the filesystem superblock. This | |
630 | value is intended to used as a salt when deriving an encryption key | |
631 | from a passphrase or other low-entropy user credential. | |
632 | ||
633 | FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to | |
634 | generate and manage any needed salt(s) in userspace. | |
635 | ||
636 | Adding keys | |
637 | ----------- | |
638 | ||
ba13f2c8 EB |
639 | FS_IOC_ADD_ENCRYPTION_KEY |
640 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
641 | ||
642 | The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to | |
643 | the filesystem, making all files on the filesystem which were | |
644 | encrypted using that key appear "unlocked", i.e. in plaintext form. | |
645 | It can be executed on any file or directory on the target filesystem, | |
646 | but using the filesystem's root directory is recommended. It takes in | |
647 | a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as | |
648 | follows:: | |
649 | ||
650 | struct fscrypt_add_key_arg { | |
651 | struct fscrypt_key_specifier key_spec; | |
652 | __u32 raw_size; | |
93edd392 EB |
653 | __u32 key_id; |
654 | __u32 __reserved[8]; | |
ba13f2c8 EB |
655 | __u8 raw[]; |
656 | }; | |
657 | ||
658 | #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1 | |
659 | #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2 | |
660 | ||
661 | struct fscrypt_key_specifier { | |
662 | __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */ | |
663 | __u32 __reserved; | |
664 | union { | |
665 | __u8 __reserved[32]; /* reserve some extra space */ | |
666 | __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; | |
667 | __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; | |
668 | } u; | |
669 | }; | |
670 | ||
93edd392 EB |
671 | struct fscrypt_provisioning_key_payload { |
672 | __u32 type; | |
673 | __u32 __reserved; | |
674 | __u8 raw[]; | |
675 | }; | |
676 | ||
ba13f2c8 EB |
677 | :c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized |
678 | as follows: | |
679 | ||
680 | - If the key is being added for use by v1 encryption policies, then | |
681 | ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and | |
682 | ``key_spec.u.descriptor`` must contain the descriptor of the key | |
683 | being added, corresponding to the value in the | |
684 | ``master_key_descriptor`` field of :c:type:`struct | |
685 | fscrypt_policy_v1`. To add this type of key, the calling process | |
686 | must have the CAP_SYS_ADMIN capability in the initial user | |
687 | namespace. | |
688 | ||
689 | Alternatively, if the key is being added for use by v2 encryption | |
690 | policies, then ``key_spec.type`` must contain | |
691 | FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is | |
692 | an *output* field which the kernel fills in with a cryptographic | |
693 | hash of the key. To add this type of key, the calling process does | |
694 | not need any privileges. However, the number of keys that can be | |
695 | added is limited by the user's quota for the keyrings service (see | |
696 | ``Documentation/security/keys/core.rst``). | |
697 | ||
698 | - ``raw_size`` must be the size of the ``raw`` key provided, in bytes. | |
93edd392 EB |
699 | Alternatively, if ``key_id`` is nonzero, this field must be 0, since |
700 | in that case the size is implied by the specified Linux keyring key. | |
701 | ||
702 | - ``key_id`` is 0 if the raw key is given directly in the ``raw`` | |
703 | field. Otherwise ``key_id`` is the ID of a Linux keyring key of | |
704 | type "fscrypt-provisioning" whose payload is a :c:type:`struct | |
705 | fscrypt_provisioning_key_payload` whose ``raw`` field contains the | |
706 | raw key and whose ``type`` field matches ``key_spec.type``. Since | |
707 | ``raw`` is variable-length, the total size of this key's payload | |
708 | must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the | |
709 | raw key size. The process must have Search permission on this key. | |
710 | ||
711 | Most users should leave this 0 and specify the raw key directly. | |
712 | The support for specifying a Linux keyring key is intended mainly to | |
713 | allow re-adding keys after a filesystem is unmounted and re-mounted, | |
714 | without having to store the raw keys in userspace memory. | |
ba13f2c8 EB |
715 | |
716 | - ``raw`` is a variable-length field which must contain the actual | |
93edd392 EB |
717 | key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is |
718 | nonzero, then this field is unused. | |
ba13f2c8 EB |
719 | |
720 | For v2 policy keys, the kernel keeps track of which user (identified | |
721 | by effective user ID) added the key, and only allows the key to be | |
722 | removed by that user --- or by "root", if they use | |
723 | `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_. | |
724 | ||
725 | However, if another user has added the key, it may be desirable to | |
726 | prevent that other user from unexpectedly removing it. Therefore, | |
727 | FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key | |
728 | *again*, even if it's already added by other user(s). In this case, | |
729 | FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the | |
730 | current user, rather than actually add the key again (but the raw key | |
731 | must still be provided, as a proof of knowledge). | |
732 | ||
733 | FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to | |
734 | the key was either added or already exists. | |
735 | ||
736 | FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors: | |
737 | ||
738 | - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the | |
739 | caller does not have the CAP_SYS_ADMIN capability in the initial | |
93edd392 EB |
740 | user namespace; or the raw key was specified by Linux key ID but the |
741 | process lacks Search permission on the key. | |
ba13f2c8 EB |
742 | - ``EDQUOT``: the key quota for this user would be exceeded by adding |
743 | the key | |
744 | - ``EINVAL``: invalid key size or key specifier type, or reserved bits | |
745 | were set | |
93edd392 EB |
746 | - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the |
747 | key has the wrong type | |
748 | - ``ENOKEY``: the raw key was specified by Linux key ID, but no key | |
749 | exists with that ID | |
ba13f2c8 EB |
750 | - ``ENOTTY``: this type of filesystem does not implement encryption |
751 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
752 | support for this filesystem, or the filesystem superblock has not | |
753 | had encryption enabled on it | |
754 | ||
755 | Legacy method | |
756 | ~~~~~~~~~~~~~ | |
757 | ||
758 | For v1 encryption policies, a master encryption key can also be | |
759 | provided by adding it to a process-subscribed keyring, e.g. to a | |
760 | session keyring, or to a user keyring if the user keyring is linked | |
761 | into the session keyring. | |
762 | ||
763 | This method is deprecated (and not supported for v2 encryption | |
764 | policies) for several reasons. First, it cannot be used in | |
765 | combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_), | |
766 | so for removing a key a workaround such as keyctl_unlink() in | |
767 | combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would | |
768 | have to be used. Second, it doesn't match the fact that the | |
769 | locked/unlocked status of encrypted files (i.e. whether they appear to | |
770 | be in plaintext form or in ciphertext form) is global. This mismatch | |
771 | has caused much confusion as well as real problems when processes | |
772 | running under different UIDs, such as a ``sudo`` command, need to | |
773 | access encrypted files. | |
774 | ||
775 | Nevertheless, to add a key to one of the process-subscribed keyrings, | |
776 | the add_key() system call can be used (see: | |
f4f864c1 EB |
777 | ``Documentation/security/keys/core.rst``). The key type must be |
778 | "logon"; keys of this type are kept in kernel memory and cannot be | |
779 | read back by userspace. The key description must be "fscrypt:" | |
780 | followed by the 16-character lower case hex representation of the | |
781 | ``master_key_descriptor`` that was set in the encryption policy. The | |
782 | key payload must conform to the following structure:: | |
783 | ||
ba13f2c8 | 784 | #define FSCRYPT_MAX_KEY_SIZE 64 |
f4f864c1 EB |
785 | |
786 | struct fscrypt_key { | |
ba13f2c8 EB |
787 | __u32 mode; |
788 | __u8 raw[FSCRYPT_MAX_KEY_SIZE]; | |
789 | __u32 size; | |
f4f864c1 EB |
790 | }; |
791 | ||
792 | ``mode`` is ignored; just set it to 0. The actual key is provided in | |
793 | ``raw`` with ``size`` indicating its size in bytes. That is, the | |
794 | bytes ``raw[0..size-1]`` (inclusive) are the actual key. | |
795 | ||
796 | The key description prefix "fscrypt:" may alternatively be replaced | |
797 | with a filesystem-specific prefix such as "ext4:". However, the | |
798 | filesystem-specific prefixes are deprecated and should not be used in | |
799 | new programs. | |
800 | ||
ba13f2c8 EB |
801 | Removing keys |
802 | ------------- | |
803 | ||
804 | Two ioctls are available for removing a key that was added by | |
805 | `FS_IOC_ADD_ENCRYPTION_KEY`_: | |
806 | ||
807 | - `FS_IOC_REMOVE_ENCRYPTION_KEY`_ | |
808 | - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_ | |
809 | ||
810 | These two ioctls differ only in cases where v2 policy keys are added | |
811 | or removed by non-root users. | |
812 | ||
813 | These ioctls don't work on keys that were added via the legacy | |
814 | process-subscribed keyrings mechanism. | |
815 | ||
816 | Before using these ioctls, read the `Kernel memory compromise`_ | |
817 | section for a discussion of the security goals and limitations of | |
818 | these ioctls. | |
819 | ||
820 | FS_IOC_REMOVE_ENCRYPTION_KEY | |
821 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
822 | ||
823 | The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master | |
824 | encryption key from the filesystem, and possibly removes the key | |
825 | itself. It can be executed on any file or directory on the target | |
826 | filesystem, but using the filesystem's root directory is recommended. | |
827 | It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`, | |
828 | defined as follows:: | |
829 | ||
830 | struct fscrypt_remove_key_arg { | |
831 | struct fscrypt_key_specifier key_spec; | |
832 | #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001 | |
833 | #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002 | |
834 | __u32 removal_status_flags; /* output */ | |
835 | __u32 __reserved[5]; | |
836 | }; | |
837 | ||
838 | This structure must be zeroed, then initialized as follows: | |
839 | ||
840 | - The key to remove is specified by ``key_spec``: | |
841 | ||
842 | - To remove a key used by v1 encryption policies, set | |
843 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill | |
844 | in ``key_spec.u.descriptor``. To remove this type of key, the | |
845 | calling process must have the CAP_SYS_ADMIN capability in the | |
846 | initial user namespace. | |
847 | ||
848 | - To remove a key used by v2 encryption policies, set | |
849 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill | |
850 | in ``key_spec.u.identifier``. | |
851 | ||
852 | For v2 policy keys, this ioctl is usable by non-root users. However, | |
853 | to make this possible, it actually just removes the current user's | |
854 | claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY. | |
855 | Only after all claims are removed is the key really removed. | |
856 | ||
857 | For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000, | |
858 | then the key will be "claimed" by uid 1000, and | |
859 | FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if | |
860 | both uids 1000 and 2000 added the key, then for each uid | |
861 | FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only | |
862 | once *both* are removed is the key really removed. (Think of it like | |
863 | unlinking a file that may have hard links.) | |
864 | ||
865 | If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also | |
866 | try to "lock" all files that had been unlocked with the key. It won't | |
867 | lock files that are still in-use, so this ioctl is expected to be used | |
868 | in cooperation with userspace ensuring that none of the files are | |
869 | still open. However, if necessary, this ioctl can be executed again | |
870 | later to retry locking any remaining files. | |
871 | ||
872 | FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed | |
873 | (but may still have files remaining to be locked), the user's claim to | |
874 | the key was removed, or the key was already removed but had files | |
875 | remaining to be the locked so the ioctl retried locking them. In any | |
876 | of these cases, ``removal_status_flags`` is filled in with the | |
877 | following informational status flags: | |
878 | ||
879 | - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s) | |
880 | are still in-use. Not guaranteed to be set in the case where only | |
881 | the user's claim to the key was removed. | |
882 | - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the | |
883 | user's claim to the key was removed, not the key itself | |
884 | ||
885 | FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors: | |
886 | ||
887 | - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type | |
888 | was specified, but the caller does not have the CAP_SYS_ADMIN | |
889 | capability in the initial user namespace | |
890 | - ``EINVAL``: invalid key specifier type, or reserved bits were set | |
891 | - ``ENOKEY``: the key object was not found at all, i.e. it was never | |
892 | added in the first place or was already fully removed including all | |
893 | files locked; or, the user does not have a claim to the key (but | |
894 | someone else does). | |
895 | - ``ENOTTY``: this type of filesystem does not implement encryption | |
896 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
897 | support for this filesystem, or the filesystem superblock has not | |
898 | had encryption enabled on it | |
899 | ||
900 | FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS | |
901 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
902 | ||
903 | FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as | |
904 | `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the | |
905 | ALL_USERS version of the ioctl will remove all users' claims to the | |
906 | key, not just the current user's. I.e., the key itself will always be | |
907 | removed, no matter how many users have added it. This difference is | |
908 | only meaningful if non-root users are adding and removing keys. | |
909 | ||
910 | Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires | |
911 | "root", namely the CAP_SYS_ADMIN capability in the initial user | |
912 | namespace. Otherwise it will fail with EACCES. | |
913 | ||
914 | Getting key status | |
915 | ------------------ | |
916 | ||
917 | FS_IOC_GET_ENCRYPTION_KEY_STATUS | |
918 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
919 | ||
920 | The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a | |
921 | master encryption key. It can be executed on any file or directory on | |
922 | the target filesystem, but using the filesystem's root directory is | |
923 | recommended. It takes in a pointer to a :c:type:`struct | |
924 | fscrypt_get_key_status_arg`, defined as follows:: | |
925 | ||
926 | struct fscrypt_get_key_status_arg { | |
927 | /* input */ | |
928 | struct fscrypt_key_specifier key_spec; | |
929 | __u32 __reserved[6]; | |
930 | ||
931 | /* output */ | |
932 | #define FSCRYPT_KEY_STATUS_ABSENT 1 | |
933 | #define FSCRYPT_KEY_STATUS_PRESENT 2 | |
934 | #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3 | |
935 | __u32 status; | |
936 | #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001 | |
937 | __u32 status_flags; | |
938 | __u32 user_count; | |
939 | __u32 __out_reserved[13]; | |
940 | }; | |
941 | ||
942 | The caller must zero all input fields, then fill in ``key_spec``: | |
943 | ||
944 | - To get the status of a key for v1 encryption policies, set | |
945 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill | |
946 | in ``key_spec.u.descriptor``. | |
947 | ||
948 | - To get the status of a key for v2 encryption policies, set | |
949 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill | |
950 | in ``key_spec.u.identifier``. | |
951 | ||
952 | On success, 0 is returned and the kernel fills in the output fields: | |
953 | ||
954 | - ``status`` indicates whether the key is absent, present, or | |
955 | incompletely removed. Incompletely removed means that the master | |
956 | secret has been removed, but some files are still in use; i.e., | |
957 | `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational | |
958 | status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY. | |
959 | ||
960 | - ``status_flags`` can contain the following flags: | |
961 | ||
962 | - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key | |
963 | has added by the current user. This is only set for keys | |
964 | identified by ``identifier`` rather than by ``descriptor``. | |
965 | ||
966 | - ``user_count`` specifies the number of users who have added the key. | |
967 | This is only set for keys identified by ``identifier`` rather than | |
968 | by ``descriptor``. | |
969 | ||
970 | FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors: | |
971 | ||
972 | - ``EINVAL``: invalid key specifier type, or reserved bits were set | |
973 | - ``ENOTTY``: this type of filesystem does not implement encryption | |
974 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
975 | support for this filesystem, or the filesystem superblock has not | |
976 | had encryption enabled on it | |
977 | ||
978 | Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful | |
979 | for determining whether the key for a given encrypted directory needs | |
980 | to be added before prompting the user for the passphrase needed to | |
981 | derive the key. | |
982 | ||
983 | FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in | |
984 | the filesystem-level keyring, i.e. the keyring managed by | |
985 | `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It | |
986 | cannot get the status of a key that has only been added for use by v1 | |
987 | encryption policies using the legacy mechanism involving | |
988 | process-subscribed keyrings. | |
f4f864c1 EB |
989 | |
990 | Access semantics | |
991 | ================ | |
992 | ||
993 | With the key | |
994 | ------------ | |
995 | ||
996 | With the encryption key, encrypted regular files, directories, and | |
997 | symlinks behave very similarly to their unencrypted counterparts --- | |
998 | after all, the encryption is intended to be transparent. However, | |
999 | astute users may notice some differences in behavior: | |
1000 | ||
1001 | - Unencrypted files, or files encrypted with a different encryption | |
1002 | policy (i.e. different key, modes, or flags), cannot be renamed or | |
1003 | linked into an encrypted directory; see `Encryption policy | |
f5e55e77 | 1004 | enforcement`_. Attempts to do so will fail with EXDEV. However, |
f4f864c1 EB |
1005 | encrypted files can be renamed within an encrypted directory, or |
1006 | into an unencrypted directory. | |
1007 | ||
f5e55e77 EB |
1008 | Note: "moving" an unencrypted file into an encrypted directory, e.g. |
1009 | with the `mv` program, is implemented in userspace by a copy | |
1010 | followed by a delete. Be aware that the original unencrypted data | |
1011 | may remain recoverable from free space on the disk; prefer to keep | |
1012 | all files encrypted from the very beginning. The `shred` program | |
1013 | may be used to overwrite the source files but isn't guaranteed to be | |
1014 | effective on all filesystems and storage devices. | |
1015 | ||
f4f864c1 EB |
1016 | - Direct I/O is not supported on encrypted files. Attempts to use |
1017 | direct I/O on such files will fall back to buffered I/O. | |
1018 | ||
1019 | - The fallocate operations FALLOC_FL_COLLAPSE_RANGE, | |
1020 | FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported | |
1021 | on encrypted files and will fail with EOPNOTSUPP. | |
1022 | ||
1023 | - Online defragmentation of encrypted files is not supported. The | |
1024 | EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with | |
1025 | EOPNOTSUPP. | |
1026 | ||
1027 | - The ext4 filesystem does not support data journaling with encrypted | |
1028 | regular files. It will fall back to ordered data mode instead. | |
1029 | ||
1030 | - DAX (Direct Access) is not supported on encrypted files. | |
1031 | ||
1032 | - The st_size of an encrypted symlink will not necessarily give the | |
1033 | length of the symlink target as required by POSIX. It will actually | |
2f46a2bc EB |
1034 | give the length of the ciphertext, which will be slightly longer |
1035 | than the plaintext due to NUL-padding and an extra 2-byte overhead. | |
1036 | ||
1037 | - The maximum length of an encrypted symlink is 2 bytes shorter than | |
1038 | the maximum length of an unencrypted symlink. For example, on an | |
1039 | EXT4 filesystem with a 4K block size, unencrypted symlinks can be up | |
1040 | to 4095 bytes long, while encrypted symlinks can only be up to 4093 | |
1041 | bytes long (both lengths excluding the terminating null). | |
f4f864c1 EB |
1042 | |
1043 | Note that mmap *is* supported. This is possible because the pagecache | |
1044 | for an encrypted file contains the plaintext, not the ciphertext. | |
1045 | ||
1046 | Without the key | |
1047 | --------------- | |
1048 | ||
1049 | Some filesystem operations may be performed on encrypted regular | |
1050 | files, directories, and symlinks even before their encryption key has | |
ba13f2c8 | 1051 | been added, or after their encryption key has been removed: |
f4f864c1 EB |
1052 | |
1053 | - File metadata may be read, e.g. using stat(). | |
1054 | ||
1055 | - Directories may be listed, in which case the filenames will be | |
1056 | listed in an encoded form derived from their ciphertext. The | |
1057 | current encoding algorithm is described in `Filename hashing and | |
1058 | encoding`_. The algorithm is subject to change, but it is | |
1059 | guaranteed that the presented filenames will be no longer than | |
1060 | NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and | |
1061 | will uniquely identify directory entries. | |
1062 | ||
1063 | The ``.`` and ``..`` directory entries are special. They are always | |
1064 | present and are not encrypted or encoded. | |
1065 | ||
1066 | - Files may be deleted. That is, nondirectory files may be deleted | |
1067 | with unlink() as usual, and empty directories may be deleted with | |
1068 | rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as | |
1069 | expected. | |
1070 | ||
1071 | - Symlink targets may be read and followed, but they will be presented | |
1072 | in encrypted form, similar to filenames in directories. Hence, they | |
1073 | are unlikely to point to anywhere useful. | |
1074 | ||
1075 | Without the key, regular files cannot be opened or truncated. | |
1076 | Attempts to do so will fail with ENOKEY. This implies that any | |
1077 | regular file operations that require a file descriptor, such as | |
1078 | read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. | |
1079 | ||
1080 | Also without the key, files of any type (including directories) cannot | |
1081 | be created or linked into an encrypted directory, nor can a name in an | |
1082 | encrypted directory be the source or target of a rename, nor can an | |
1083 | O_TMPFILE temporary file be created in an encrypted directory. All | |
1084 | such operations will fail with ENOKEY. | |
1085 | ||
1086 | It is not currently possible to backup and restore encrypted files | |
1087 | without the encryption key. This would require special APIs which | |
1088 | have not yet been implemented. | |
1089 | ||
1090 | Encryption policy enforcement | |
1091 | ============================= | |
1092 | ||
1093 | After an encryption policy has been set on a directory, all regular | |
1094 | files, directories, and symbolic links created in that directory | |
1095 | (recursively) will inherit that encryption policy. Special files --- | |
1096 | that is, named pipes, device nodes, and UNIX domain sockets --- will | |
1097 | not be encrypted. | |
1098 | ||
1099 | Except for those special files, it is forbidden to have unencrypted | |
1100 | files, or files encrypted with a different encryption policy, in an | |
1101 | encrypted directory tree. Attempts to link or rename such a file into | |
f5e55e77 | 1102 | an encrypted directory will fail with EXDEV. This is also enforced |
f4f864c1 EB |
1103 | during ->lookup() to provide limited protection against offline |
1104 | attacks that try to disable or downgrade encryption in known locations | |
1105 | where applications may later write sensitive data. It is recommended | |
1106 | that systems implementing a form of "verified boot" take advantage of | |
1107 | this by validating all top-level encryption policies prior to access. | |
1108 | ||
1109 | Implementation details | |
1110 | ====================== | |
1111 | ||
1112 | Encryption context | |
1113 | ------------------ | |
1114 | ||
1115 | An encryption policy is represented on-disk by a :c:type:`struct | |
ba13f2c8 EB |
1116 | fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is |
1117 | up to individual filesystems to decide where to store it, but normally | |
1118 | it would be stored in a hidden extended attribute. It should *not* be | |
1119 | exposed by the xattr-related system calls such as getxattr() and | |
1120 | setxattr() because of the special semantics of the encryption xattr. | |
1121 | (In particular, there would be much confusion if an encryption policy | |
1122 | were to be added to or removed from anything other than an empty | |
1123 | directory.) These structs are defined as follows:: | |
f4f864c1 | 1124 | |
f4f864c1 EB |
1125 | #define FS_KEY_DERIVATION_NONCE_SIZE 16 |
1126 | ||
ba13f2c8 EB |
1127 | #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 |
1128 | struct fscrypt_context_v1 { | |
1129 | u8 version; | |
f4f864c1 EB |
1130 | u8 contents_encryption_mode; |
1131 | u8 filenames_encryption_mode; | |
1132 | u8 flags; | |
2336d0de | 1133 | u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; |
f4f864c1 EB |
1134 | u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; |
1135 | }; | |
1136 | ||
ba13f2c8 EB |
1137 | #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 |
1138 | struct fscrypt_context_v2 { | |
1139 | u8 version; | |
1140 | u8 contents_encryption_mode; | |
1141 | u8 filenames_encryption_mode; | |
1142 | u8 flags; | |
1143 | u8 __reserved[4]; | |
1144 | u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; | |
1145 | u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; | |
1146 | }; | |
1147 | ||
1148 | The context structs contain the same information as the corresponding | |
1149 | policy structs (see `Setting an encryption policy`_), except that the | |
1150 | context structs also contain a nonce. The nonce is randomly generated | |
1151 | by the kernel and is used as KDF input or as a tweak to cause | |
1152 | different files to be encrypted differently; see `Per-file keys`_ and | |
b103fb76 | 1153 | `DIRECT_KEY policies`_. |
f4f864c1 EB |
1154 | |
1155 | Data path changes | |
1156 | ----------------- | |
1157 | ||
1158 | For the read path (->readpage()) of regular files, filesystems can | |
1159 | read the ciphertext into the page cache and decrypt it in-place. The | |
1160 | page lock must be held until decryption has finished, to prevent the | |
1161 | page from becoming visible to userspace prematurely. | |
1162 | ||
1163 | For the write path (->writepage()) of regular files, filesystems | |
1164 | cannot encrypt data in-place in the page cache, since the cached | |
1165 | plaintext must be preserved. Instead, filesystems must encrypt into a | |
1166 | temporary buffer or "bounce page", then write out the temporary | |
1167 | buffer. Some filesystems, such as UBIFS, already use temporary | |
1168 | buffers regardless of encryption. Other filesystems, such as ext4 and | |
1169 | F2FS, have to allocate bounce pages specially for encryption. | |
1170 | ||
1171 | Filename hashing and encoding | |
1172 | ----------------------------- | |
1173 | ||
1174 | Modern filesystems accelerate directory lookups by using indexed | |
1175 | directories. An indexed directory is organized as a tree keyed by | |
1176 | filename hashes. When a ->lookup() is requested, the filesystem | |
1177 | normally hashes the filename being looked up so that it can quickly | |
1178 | find the corresponding directory entry, if any. | |
1179 | ||
1180 | With encryption, lookups must be supported and efficient both with and | |
1181 | without the encryption key. Clearly, it would not work to hash the | |
1182 | plaintext filenames, since the plaintext filenames are unavailable | |
1183 | without the key. (Hashing the plaintext filenames would also make it | |
1184 | impossible for the filesystem's fsck tool to optimize encrypted | |
1185 | directories.) Instead, filesystems hash the ciphertext filenames, | |
1186 | i.e. the bytes actually stored on-disk in the directory entries. When | |
1187 | asked to do a ->lookup() with the key, the filesystem just encrypts | |
1188 | the user-supplied name to get the ciphertext. | |
1189 | ||
1190 | Lookups without the key are more complicated. The raw ciphertext may | |
1191 | contain the ``\0`` and ``/`` characters, which are illegal in | |
1192 | filenames. Therefore, readdir() must base64-encode the ciphertext for | |
1193 | presentation. For most filenames, this works fine; on ->lookup(), the | |
1194 | filesystem just base64-decodes the user-supplied name to get back to | |
1195 | the raw ciphertext. | |
1196 | ||
1197 | However, for very long filenames, base64 encoding would cause the | |
1198 | filename length to exceed NAME_MAX. To prevent this, readdir() | |
1199 | actually presents long filenames in an abbreviated form which encodes | |
1200 | a strong "hash" of the ciphertext filename, along with the optional | |
1201 | filesystem-specific hash(es) needed for directory lookups. This | |
1202 | allows the filesystem to still, with a high degree of confidence, map | |
1203 | the filename given in ->lookup() back to a particular directory entry | |
1204 | that was previously listed by readdir(). See :c:type:`struct | |
1205 | fscrypt_digested_name` in the source for more details. | |
1206 | ||
1207 | Note that the precise way that filenames are presented to userspace | |
1208 | without the key is subject to change in the future. It is only meant | |
1209 | as a way to temporarily present valid filenames so that commands like | |
1210 | ``rm -r`` work as expected on encrypted directories. | |
05643363 EB |
1211 | |
1212 | Tests | |
1213 | ===== | |
1214 | ||
1215 | To test fscrypt, use xfstests, which is Linux's de facto standard | |
1216 | filesystem test suite. First, run all the tests in the "encrypt" | |
1217 | group on the relevant filesystem(s). For example, to test ext4 and | |
1218 | f2fs encryption using `kvm-xfstests | |
1219 | <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: | |
1220 | ||
1221 | kvm-xfstests -c ext4,f2fs -g encrypt | |
1222 | ||
1223 | UBIFS encryption can also be tested this way, but it should be done in | |
1224 | a separate command, and it takes some time for kvm-xfstests to set up | |
1225 | emulated UBI volumes:: | |
1226 | ||
1227 | kvm-xfstests -c ubifs -g encrypt | |
1228 | ||
1229 | No tests should fail. However, tests that use non-default encryption | |
1230 | modes (e.g. generic/549 and generic/550) will be skipped if the needed | |
1231 | algorithms were not built into the kernel's crypto API. Also, tests | |
1232 | that access the raw block device (e.g. generic/399, generic/548, | |
1233 | generic/549, generic/550) will be skipped on UBIFS. | |
1234 | ||
1235 | Besides running the "encrypt" group tests, for ext4 and f2fs it's also | |
1236 | possible to run most xfstests with the "test_dummy_encryption" mount | |
1237 | option. This option causes all new files to be automatically | |
1238 | encrypted with a dummy key, without having to make any API calls. | |
1239 | This tests the encrypted I/O paths more thoroughly. To do this with | |
1240 | kvm-xfstests, use the "encrypt" filesystem configuration:: | |
1241 | ||
1242 | kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto | |
1243 | ||
1244 | Because this runs many more tests than "-g encrypt" does, it takes | |
1245 | much longer to run; so also consider using `gce-xfstests | |
1246 | <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_ | |
1247 | instead of kvm-xfstests:: | |
1248 | ||
1249 | gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto |