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 | ||
75 | fscrypt is only resistant to side-channel attacks, such as timing or | |
76 | electromagnetic attacks, to the extent that the underlying Linux | |
77 | Cryptographic API algorithms are. If a vulnerable algorithm is used, | |
78 | such as a table-based implementation of AES, it may be possible for an | |
79 | attacker to mount a side channel attack against the online system. | |
80 | Side channel attacks may also be mounted against applications | |
81 | consuming decrypted data. | |
82 | ||
83 | After an encryption key has been provided, fscrypt is not designed to | |
84 | hide the plaintext file contents or filenames from other users on the | |
85 | same system, regardless of the visibility of the keyring key. | |
86 | Instead, existing access control mechanisms such as file mode bits, | |
87 | POSIX ACLs, LSMs, or mount namespaces should be used for this purpose. | |
88 | Also note that as long as the encryption keys are *anywhere* in | |
89 | memory, an online attacker can necessarily compromise them by mounting | |
90 | a physical attack or by exploiting any kernel security vulnerability | |
91 | which provides an arbitrary memory read primitive. | |
92 | ||
93 | While it is ostensibly possible to "evict" keys from the system, | |
94 | recently accessed encrypted files will remain accessible at least | |
95 | until the filesystem is unmounted or the VFS caches are dropped, e.g. | |
96 | using ``echo 2 > /proc/sys/vm/drop_caches``. Even after that, if the | |
97 | RAM is compromised before being powered off, it will likely still be | |
98 | possible to recover portions of the plaintext file contents, if not | |
99 | some of the encryption keys as well. (Since Linux v4.12, all | |
100 | in-kernel keys related to fscrypt are sanitized before being freed. | |
101 | However, userspace would need to do its part as well.) | |
102 | ||
103 | Currently, fscrypt does not prevent a user from maliciously providing | |
104 | an incorrect key for another user's existing encrypted files. A | |
105 | protection against this is planned. | |
106 | ||
107 | Key hierarchy | |
108 | ============= | |
109 | ||
110 | Master Keys | |
111 | ----------- | |
112 | ||
113 | Each encrypted directory tree is protected by a *master key*. Master | |
114 | keys can be up to 64 bytes long, and must be at least as long as the | |
115 | greater of the key length needed by the contents and filenames | |
116 | encryption modes being used. For example, if AES-256-XTS is used for | |
117 | contents encryption, the master key must be 64 bytes (512 bits). Note | |
118 | that the XTS mode is defined to require a key twice as long as that | |
119 | required by the underlying block cipher. | |
120 | ||
121 | To "unlock" an encrypted directory tree, userspace must provide the | |
122 | appropriate master key. There can be any number of master keys, each | |
123 | of which protects any number of directory trees on any number of | |
124 | filesystems. | |
125 | ||
126 | Userspace should generate master keys either using a cryptographically | |
127 | secure random number generator, or by using a KDF (Key Derivation | |
128 | Function). Note that whenever a KDF is used to "stretch" a | |
129 | lower-entropy secret such as a passphrase, it is critical that a KDF | |
130 | designed for this purpose be used, such as scrypt, PBKDF2, or Argon2. | |
131 | ||
132 | Per-file keys | |
133 | ------------- | |
134 | ||
8094c3ce EB |
135 | Since each master key can protect many files, it is necessary to |
136 | "tweak" the encryption of each file so that the same plaintext in two | |
137 | files doesn't map to the same ciphertext, or vice versa. In most | |
138 | cases, fscrypt does this by deriving per-file keys. When a new | |
139 | encrypted inode (regular file, directory, or symlink) is created, | |
140 | fscrypt randomly generates a 16-byte nonce and stores it in the | |
141 | inode's encryption xattr. Then, it uses a KDF (Key Derivation | |
142 | Function) to derive the file's key from the master key and nonce. | |
143 | ||
144 | The Adiantum encryption mode (see `Encryption modes and usage`_) is | |
145 | special, since it accepts longer IVs and is suitable for both contents | |
146 | and filenames encryption. For it, a "direct key" option is offered | |
147 | where the file's nonce is included in the IVs and the master key is | |
148 | used for encryption directly. This improves performance; however, | |
149 | users must not use the same master key for any other encryption mode. | |
150 | ||
151 | Below, the KDF and design considerations are described in more detail. | |
152 | ||
153 | The current KDF works by encrypting the master key with AES-128-ECB, | |
154 | using the file's nonce as the AES key. The output is used as the | |
155 | derived key. If the output is longer than needed, then it is | |
156 | truncated to the needed length. | |
f4f864c1 EB |
157 | |
158 | Note: this KDF meets the primary security requirement, which is to | |
159 | produce unique derived keys that preserve the entropy of the master | |
160 | key, assuming that the master key is already a good pseudorandom key. | |
161 | However, it is nonstandard and has some problems such as being | |
162 | reversible, so it is generally considered to be a mistake! It may be | |
163 | replaced with HKDF or another more standard KDF in the future. | |
164 | ||
8094c3ce EB |
165 | Key derivation was chosen over key wrapping because wrapped keys would |
166 | require larger xattrs which would be less likely to fit in-line in the | |
167 | filesystem's inode table, and there didn't appear to be any | |
168 | significant advantages to key wrapping. In particular, currently | |
169 | there is no requirement to support unlocking a file with multiple | |
170 | alternative master keys or to support rotating master keys. Instead, | |
171 | the master keys may be wrapped in userspace, e.g. as is done by the | |
172 | `fscrypt <https://github.com/google/fscrypt>`_ tool. | |
173 | ||
174 | Including the inode number in the IVs was considered. However, it was | |
175 | rejected as it would have prevented ext4 filesystems from being | |
176 | resized, and by itself still wouldn't have been sufficient to prevent | |
177 | the same key from being directly reused for both XTS and CTS-CBC. | |
178 | ||
f4f864c1 EB |
179 | Encryption modes and usage |
180 | ========================== | |
181 | ||
182 | fscrypt allows one encryption mode to be specified for file contents | |
183 | and one encryption mode to be specified for filenames. Different | |
184 | directory trees are permitted to use different encryption modes. | |
185 | Currently, the following pairs of encryption modes are supported: | |
186 | ||
187 | - AES-256-XTS for contents and AES-256-CTS-CBC for filenames | |
188 | - AES-128-CBC for contents and AES-128-CTS-CBC for filenames | |
8094c3ce EB |
189 | - Adiantum for both contents and filenames |
190 | ||
191 | If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. | |
f4f864c1 | 192 | |
f4f864c1 | 193 | AES-128-CBC was added only for low-powered embedded devices with |
adbd9b4d EB |
194 | crypto accelerators such as CAAM or CESA that do not support XTS. To |
195 | use AES-128-CBC, CONFIG_CRYPTO_SHA256 (or another SHA-256 | |
196 | implementation) must be enabled so that ESSIV can be used. | |
f4f864c1 | 197 | |
8094c3ce EB |
198 | Adiantum is a (primarily) stream cipher-based mode that is fast even |
199 | on CPUs without dedicated crypto instructions. It's also a true | |
200 | wide-block mode, unlike XTS. It can also eliminate the need to derive | |
201 | per-file keys. However, it depends on the security of two primitives, | |
202 | XChaCha12 and AES-256, rather than just one. See the paper | |
203 | "Adiantum: length-preserving encryption for entry-level processors" | |
204 | (https://eprint.iacr.org/2018/720.pdf) for more details. To use | |
205 | Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast | |
206 | implementations of ChaCha and NHPoly1305 should be enabled, e.g. | |
207 | CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. | |
208 | ||
f4f864c1 EB |
209 | New encryption modes can be added relatively easily, without changes |
210 | to individual filesystems. However, authenticated encryption (AE) | |
211 | modes are not currently supported because of the difficulty of dealing | |
212 | with ciphertext expansion. | |
213 | ||
8094c3ce EB |
214 | Contents encryption |
215 | ------------------- | |
216 | ||
f4f864c1 EB |
217 | For file contents, each filesystem block is encrypted independently. |
218 | Currently, only the case where the filesystem block size is equal to | |
8094c3ce EB |
219 | the system's page size (usually 4096 bytes) is supported. |
220 | ||
221 | Each block's IV is set to the logical block number within the file as | |
222 | a little endian number, except that: | |
223 | ||
224 | - With CBC mode encryption, ESSIV is also used. Specifically, each IV | |
225 | is encrypted with AES-256 where the AES-256 key is the SHA-256 hash | |
226 | of the file's data encryption key. | |
227 | ||
2336d0de EB |
228 | - In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY |
229 | set in the fscrypt_policy), the file's nonce is also appended to the | |
230 | IV. Currently this is only allowed with the Adiantum encryption | |
231 | mode. | |
8094c3ce EB |
232 | |
233 | Filenames encryption | |
234 | -------------------- | |
235 | ||
236 | For filenames, each full filename is encrypted at once. Because of | |
237 | the requirements to retain support for efficient directory lookups and | |
238 | filenames of up to 255 bytes, the same IV is used for every filename | |
239 | in a directory. | |
240 | ||
241 | However, each encrypted directory still uses a unique key; or | |
242 | alternatively (for the "direct key" configuration) has the file's | |
243 | nonce included in the IVs. Thus, IV reuse is limited to within a | |
244 | single directory. | |
245 | ||
246 | With CTS-CBC, the IV reuse means that when the plaintext filenames | |
247 | share a common prefix at least as long as the cipher block size (16 | |
248 | bytes for AES), the corresponding encrypted filenames will also share | |
249 | a common prefix. This is undesirable. Adiantum does not have this | |
250 | weakness, as it is a wide-block encryption mode. | |
251 | ||
252 | All supported filenames encryption modes accept any plaintext length | |
253 | >= 16 bytes; cipher block alignment is not required. However, | |
254 | filenames shorter than 16 bytes are NUL-padded to 16 bytes before | |
255 | being encrypted. In addition, to reduce leakage of filename lengths | |
256 | via their ciphertexts, all filenames are NUL-padded to the next 4, 8, | |
257 | 16, or 32-byte boundary (configurable). 32 is recommended since this | |
258 | provides the best confidentiality, at the cost of making directory | |
259 | entries consume slightly more space. Note that since NUL (``\0``) is | |
260 | not otherwise a valid character in filenames, the padding will never | |
261 | produce duplicate plaintexts. | |
f4f864c1 EB |
262 | |
263 | Symbolic link targets are considered a type of filename and are | |
8094c3ce EB |
264 | encrypted in the same way as filenames in directory entries, except |
265 | that IV reuse is not a problem as each symlink has its own inode. | |
f4f864c1 EB |
266 | |
267 | User API | |
268 | ======== | |
269 | ||
270 | Setting an encryption policy | |
271 | ---------------------------- | |
272 | ||
273 | The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an | |
274 | empty directory or verifies that a directory or regular file already | |
275 | has the specified encryption policy. It takes in a pointer to a | |
276 | :c:type:`struct fscrypt_policy`, defined as follows:: | |
277 | ||
2336d0de | 278 | #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 |
f4f864c1 EB |
279 | |
280 | struct fscrypt_policy { | |
281 | __u8 version; | |
282 | __u8 contents_encryption_mode; | |
283 | __u8 filenames_encryption_mode; | |
284 | __u8 flags; | |
2336d0de | 285 | __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; |
f4f864c1 EB |
286 | }; |
287 | ||
288 | This structure must be initialized as follows: | |
289 | ||
290 | - ``version`` must be 0. | |
291 | ||
292 | - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must | |
2336d0de EB |
293 | be set to constants from ``<linux/fscrypt.h>`` which identify the |
294 | encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS | |
295 | (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS | |
296 | (4) for ``filenames_encryption_mode``. | |
f4f864c1 | 297 | |
2336d0de | 298 | - ``flags`` must contain a value from ``<linux/fscrypt.h>`` which |
f4f864c1 | 299 | identifies the amount of NUL-padding to use when encrypting |
2336d0de EB |
300 | filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3). In |
301 | addition, if the chosen encryption modes are both | |
302 | FSCRYPT_MODE_ADIANTUM, this can contain | |
303 | FSCRYPT_POLICY_FLAG_DIRECT_KEY to specify that the master key should | |
304 | be used directly, without key derivation. | |
f4f864c1 EB |
305 | |
306 | - ``master_key_descriptor`` specifies how to find the master key in | |
307 | the keyring; see `Adding keys`_. It is up to userspace to choose a | |
308 | unique ``master_key_descriptor`` for each master key. The e4crypt | |
309 | and fscrypt tools use the first 8 bytes of | |
310 | ``SHA-512(SHA-512(master_key))``, but this particular scheme is not | |
311 | required. Also, the master key need not be in the keyring yet when | |
312 | FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added | |
313 | before any files can be created in the encrypted directory. | |
314 | ||
315 | If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY | |
316 | verifies that the file is an empty directory. If so, the specified | |
317 | encryption policy is assigned to the directory, turning it into an | |
318 | encrypted directory. After that, and after providing the | |
319 | corresponding master key as described in `Adding keys`_, all regular | |
320 | files, directories (recursively), and symlinks created in the | |
321 | directory will be encrypted, inheriting the same encryption policy. | |
322 | The filenames in the directory's entries will be encrypted as well. | |
323 | ||
324 | Alternatively, if the file is already encrypted, then | |
325 | FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption | |
326 | policy exactly matches the actual one. If they match, then the ioctl | |
327 | returns 0. Otherwise, it fails with EEXIST. This works on both | |
328 | regular files and directories, including nonempty directories. | |
329 | ||
330 | Note that the ext4 filesystem does not allow the root directory to be | |
331 | encrypted, even if it is empty. Users who want to encrypt an entire | |
332 | filesystem with one key should consider using dm-crypt instead. | |
333 | ||
334 | FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: | |
335 | ||
336 | - ``EACCES``: the file is not owned by the process's uid, nor does the | |
337 | process have the CAP_FOWNER capability in a namespace with the file | |
338 | owner's uid mapped | |
339 | - ``EEXIST``: the file is already encrypted with an encryption policy | |
340 | different from the one specified | |
341 | - ``EINVAL``: an invalid encryption policy was specified (invalid | |
342 | version, mode(s), or flags) | |
343 | - ``ENOTDIR``: the file is unencrypted and is a regular file, not a | |
344 | directory | |
345 | - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory | |
346 | - ``ENOTTY``: this type of filesystem does not implement encryption | |
347 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
643fa961 | 348 | support for filesystems, or the filesystem superblock has not |
f4f864c1 | 349 | had encryption enabled on it. (For example, to use encryption on an |
643fa961 | 350 | ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the |
f4f864c1 EB |
351 | kernel config, and the superblock must have had the "encrypt" |
352 | feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O | |
353 | encrypt``.) | |
354 | - ``EPERM``: this directory may not be encrypted, e.g. because it is | |
355 | the root directory of an ext4 filesystem | |
356 | - ``EROFS``: the filesystem is readonly | |
357 | ||
358 | Getting an encryption policy | |
359 | ---------------------------- | |
360 | ||
361 | The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct | |
362 | fscrypt_policy`, if any, for a directory or regular file. See above | |
363 | for the struct definition. No additional permissions are required | |
364 | beyond the ability to open the file. | |
365 | ||
366 | FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors: | |
367 | ||
368 | - ``EINVAL``: the file is encrypted, but it uses an unrecognized | |
369 | encryption context format | |
370 | - ``ENODATA``: the file is not encrypted | |
371 | - ``ENOTTY``: this type of filesystem does not implement encryption | |
372 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
373 | support for this filesystem | |
374 | ||
375 | Note: if you only need to know whether a file is encrypted or not, on | |
376 | most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl | |
377 | and check for FS_ENCRYPT_FL, or to use the statx() system call and | |
378 | check for STATX_ATTR_ENCRYPTED in stx_attributes. | |
379 | ||
380 | Getting the per-filesystem salt | |
381 | ------------------------------- | |
382 | ||
383 | Some filesystems, such as ext4 and F2FS, also support the deprecated | |
384 | ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly | |
385 | generated 16-byte value stored in the filesystem superblock. This | |
386 | value is intended to used as a salt when deriving an encryption key | |
387 | from a passphrase or other low-entropy user credential. | |
388 | ||
389 | FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to | |
390 | generate and manage any needed salt(s) in userspace. | |
391 | ||
392 | Adding keys | |
393 | ----------- | |
394 | ||
395 | To provide a master key, userspace must add it to an appropriate | |
396 | keyring using the add_key() system call (see: | |
397 | ``Documentation/security/keys/core.rst``). The key type must be | |
398 | "logon"; keys of this type are kept in kernel memory and cannot be | |
399 | read back by userspace. The key description must be "fscrypt:" | |
400 | followed by the 16-character lower case hex representation of the | |
401 | ``master_key_descriptor`` that was set in the encryption policy. The | |
402 | key payload must conform to the following structure:: | |
403 | ||
2336d0de | 404 | #define FSCRYPT_MAX_KEY_SIZE 64 |
f4f864c1 EB |
405 | |
406 | struct fscrypt_key { | |
407 | u32 mode; | |
2336d0de | 408 | u8 raw[FSCRYPT_MAX_KEY_SIZE]; |
f4f864c1 EB |
409 | u32 size; |
410 | }; | |
411 | ||
412 | ``mode`` is ignored; just set it to 0. The actual key is provided in | |
413 | ``raw`` with ``size`` indicating its size in bytes. That is, the | |
414 | bytes ``raw[0..size-1]`` (inclusive) are the actual key. | |
415 | ||
416 | The key description prefix "fscrypt:" may alternatively be replaced | |
417 | with a filesystem-specific prefix such as "ext4:". However, the | |
418 | filesystem-specific prefixes are deprecated and should not be used in | |
419 | new programs. | |
420 | ||
421 | There are several different types of keyrings in which encryption keys | |
422 | may be placed, such as a session keyring, a user session keyring, or a | |
423 | user keyring. Each key must be placed in a keyring that is "attached" | |
424 | to all processes that might need to access files encrypted with it, in | |
425 | the sense that request_key() will find the key. Generally, if only | |
426 | processes belonging to a specific user need to access a given | |
427 | encrypted directory and no session keyring has been installed, then | |
428 | that directory's key should be placed in that user's user session | |
429 | keyring or user keyring. Otherwise, a session keyring should be | |
430 | installed if needed, and the key should be linked into that session | |
431 | keyring, or in a keyring linked into that session keyring. | |
432 | ||
433 | Note: introducing the complex visibility semantics of keyrings here | |
434 | was arguably a mistake --- especially given that by design, after any | |
435 | process successfully opens an encrypted file (thereby setting up the | |
436 | per-file key), possessing the keyring key is not actually required for | |
437 | any process to read/write the file until its in-memory inode is | |
438 | evicted. In the future there probably should be a way to provide keys | |
439 | directly to the filesystem instead, which would make the intended | |
440 | semantics clearer. | |
441 | ||
442 | Access semantics | |
443 | ================ | |
444 | ||
445 | With the key | |
446 | ------------ | |
447 | ||
448 | With the encryption key, encrypted regular files, directories, and | |
449 | symlinks behave very similarly to their unencrypted counterparts --- | |
450 | after all, the encryption is intended to be transparent. However, | |
451 | astute users may notice some differences in behavior: | |
452 | ||
453 | - Unencrypted files, or files encrypted with a different encryption | |
454 | policy (i.e. different key, modes, or flags), cannot be renamed or | |
455 | linked into an encrypted directory; see `Encryption policy | |
f5e55e77 | 456 | enforcement`_. Attempts to do so will fail with EXDEV. However, |
f4f864c1 EB |
457 | encrypted files can be renamed within an encrypted directory, or |
458 | into an unencrypted directory. | |
459 | ||
f5e55e77 EB |
460 | Note: "moving" an unencrypted file into an encrypted directory, e.g. |
461 | with the `mv` program, is implemented in userspace by a copy | |
462 | followed by a delete. Be aware that the original unencrypted data | |
463 | may remain recoverable from free space on the disk; prefer to keep | |
464 | all files encrypted from the very beginning. The `shred` program | |
465 | may be used to overwrite the source files but isn't guaranteed to be | |
466 | effective on all filesystems and storage devices. | |
467 | ||
f4f864c1 EB |
468 | - Direct I/O is not supported on encrypted files. Attempts to use |
469 | direct I/O on such files will fall back to buffered I/O. | |
470 | ||
471 | - The fallocate operations FALLOC_FL_COLLAPSE_RANGE, | |
472 | FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported | |
473 | on encrypted files and will fail with EOPNOTSUPP. | |
474 | ||
475 | - Online defragmentation of encrypted files is not supported. The | |
476 | EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with | |
477 | EOPNOTSUPP. | |
478 | ||
479 | - The ext4 filesystem does not support data journaling with encrypted | |
480 | regular files. It will fall back to ordered data mode instead. | |
481 | ||
482 | - DAX (Direct Access) is not supported on encrypted files. | |
483 | ||
484 | - The st_size of an encrypted symlink will not necessarily give the | |
485 | length of the symlink target as required by POSIX. It will actually | |
2f46a2bc EB |
486 | give the length of the ciphertext, which will be slightly longer |
487 | than the plaintext due to NUL-padding and an extra 2-byte overhead. | |
488 | ||
489 | - The maximum length of an encrypted symlink is 2 bytes shorter than | |
490 | the maximum length of an unencrypted symlink. For example, on an | |
491 | EXT4 filesystem with a 4K block size, unencrypted symlinks can be up | |
492 | to 4095 bytes long, while encrypted symlinks can only be up to 4093 | |
493 | bytes long (both lengths excluding the terminating null). | |
f4f864c1 EB |
494 | |
495 | Note that mmap *is* supported. This is possible because the pagecache | |
496 | for an encrypted file contains the plaintext, not the ciphertext. | |
497 | ||
498 | Without the key | |
499 | --------------- | |
500 | ||
501 | Some filesystem operations may be performed on encrypted regular | |
502 | files, directories, and symlinks even before their encryption key has | |
503 | been provided: | |
504 | ||
505 | - File metadata may be read, e.g. using stat(). | |
506 | ||
507 | - Directories may be listed, in which case the filenames will be | |
508 | listed in an encoded form derived from their ciphertext. The | |
509 | current encoding algorithm is described in `Filename hashing and | |
510 | encoding`_. The algorithm is subject to change, but it is | |
511 | guaranteed that the presented filenames will be no longer than | |
512 | NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and | |
513 | will uniquely identify directory entries. | |
514 | ||
515 | The ``.`` and ``..`` directory entries are special. They are always | |
516 | present and are not encrypted or encoded. | |
517 | ||
518 | - Files may be deleted. That is, nondirectory files may be deleted | |
519 | with unlink() as usual, and empty directories may be deleted with | |
520 | rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as | |
521 | expected. | |
522 | ||
523 | - Symlink targets may be read and followed, but they will be presented | |
524 | in encrypted form, similar to filenames in directories. Hence, they | |
525 | are unlikely to point to anywhere useful. | |
526 | ||
527 | Without the key, regular files cannot be opened or truncated. | |
528 | Attempts to do so will fail with ENOKEY. This implies that any | |
529 | regular file operations that require a file descriptor, such as | |
530 | read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. | |
531 | ||
532 | Also without the key, files of any type (including directories) cannot | |
533 | be created or linked into an encrypted directory, nor can a name in an | |
534 | encrypted directory be the source or target of a rename, nor can an | |
535 | O_TMPFILE temporary file be created in an encrypted directory. All | |
536 | such operations will fail with ENOKEY. | |
537 | ||
538 | It is not currently possible to backup and restore encrypted files | |
539 | without the encryption key. This would require special APIs which | |
540 | have not yet been implemented. | |
541 | ||
542 | Encryption policy enforcement | |
543 | ============================= | |
544 | ||
545 | After an encryption policy has been set on a directory, all regular | |
546 | files, directories, and symbolic links created in that directory | |
547 | (recursively) will inherit that encryption policy. Special files --- | |
548 | that is, named pipes, device nodes, and UNIX domain sockets --- will | |
549 | not be encrypted. | |
550 | ||
551 | Except for those special files, it is forbidden to have unencrypted | |
552 | files, or files encrypted with a different encryption policy, in an | |
553 | encrypted directory tree. Attempts to link or rename such a file into | |
f5e55e77 | 554 | an encrypted directory will fail with EXDEV. This is also enforced |
f4f864c1 EB |
555 | during ->lookup() to provide limited protection against offline |
556 | attacks that try to disable or downgrade encryption in known locations | |
557 | where applications may later write sensitive data. It is recommended | |
558 | that systems implementing a form of "verified boot" take advantage of | |
559 | this by validating all top-level encryption policies prior to access. | |
560 | ||
561 | Implementation details | |
562 | ====================== | |
563 | ||
564 | Encryption context | |
565 | ------------------ | |
566 | ||
567 | An encryption policy is represented on-disk by a :c:type:`struct | |
568 | fscrypt_context`. It is up to individual filesystems to decide where | |
569 | to store it, but normally it would be stored in a hidden extended | |
570 | attribute. It should *not* be exposed by the xattr-related system | |
571 | calls such as getxattr() and setxattr() because of the special | |
572 | semantics of the encryption xattr. (In particular, there would be | |
573 | much confusion if an encryption policy were to be added to or removed | |
574 | from anything other than an empty directory.) The struct is defined | |
575 | as follows:: | |
576 | ||
2336d0de | 577 | #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 |
f4f864c1 EB |
578 | #define FS_KEY_DERIVATION_NONCE_SIZE 16 |
579 | ||
580 | struct fscrypt_context { | |
581 | u8 format; | |
582 | u8 contents_encryption_mode; | |
583 | u8 filenames_encryption_mode; | |
584 | u8 flags; | |
2336d0de | 585 | u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; |
f4f864c1 EB |
586 | u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; |
587 | }; | |
588 | ||
589 | Note that :c:type:`struct fscrypt_context` contains the same | |
590 | information as :c:type:`struct fscrypt_policy` (see `Setting an | |
591 | encryption policy`_), except that :c:type:`struct fscrypt_context` | |
592 | also contains a nonce. The nonce is randomly generated by the kernel | |
593 | and is used to derive the inode's encryption key as described in | |
594 | `Per-file keys`_. | |
595 | ||
596 | Data path changes | |
597 | ----------------- | |
598 | ||
599 | For the read path (->readpage()) of regular files, filesystems can | |
600 | read the ciphertext into the page cache and decrypt it in-place. The | |
601 | page lock must be held until decryption has finished, to prevent the | |
602 | page from becoming visible to userspace prematurely. | |
603 | ||
604 | For the write path (->writepage()) of regular files, filesystems | |
605 | cannot encrypt data in-place in the page cache, since the cached | |
606 | plaintext must be preserved. Instead, filesystems must encrypt into a | |
607 | temporary buffer or "bounce page", then write out the temporary | |
608 | buffer. Some filesystems, such as UBIFS, already use temporary | |
609 | buffers regardless of encryption. Other filesystems, such as ext4 and | |
610 | F2FS, have to allocate bounce pages specially for encryption. | |
611 | ||
612 | Filename hashing and encoding | |
613 | ----------------------------- | |
614 | ||
615 | Modern filesystems accelerate directory lookups by using indexed | |
616 | directories. An indexed directory is organized as a tree keyed by | |
617 | filename hashes. When a ->lookup() is requested, the filesystem | |
618 | normally hashes the filename being looked up so that it can quickly | |
619 | find the corresponding directory entry, if any. | |
620 | ||
621 | With encryption, lookups must be supported and efficient both with and | |
622 | without the encryption key. Clearly, it would not work to hash the | |
623 | plaintext filenames, since the plaintext filenames are unavailable | |
624 | without the key. (Hashing the plaintext filenames would also make it | |
625 | impossible for the filesystem's fsck tool to optimize encrypted | |
626 | directories.) Instead, filesystems hash the ciphertext filenames, | |
627 | i.e. the bytes actually stored on-disk in the directory entries. When | |
628 | asked to do a ->lookup() with the key, the filesystem just encrypts | |
629 | the user-supplied name to get the ciphertext. | |
630 | ||
631 | Lookups without the key are more complicated. The raw ciphertext may | |
632 | contain the ``\0`` and ``/`` characters, which are illegal in | |
633 | filenames. Therefore, readdir() must base64-encode the ciphertext for | |
634 | presentation. For most filenames, this works fine; on ->lookup(), the | |
635 | filesystem just base64-decodes the user-supplied name to get back to | |
636 | the raw ciphertext. | |
637 | ||
638 | However, for very long filenames, base64 encoding would cause the | |
639 | filename length to exceed NAME_MAX. To prevent this, readdir() | |
640 | actually presents long filenames in an abbreviated form which encodes | |
641 | a strong "hash" of the ciphertext filename, along with the optional | |
642 | filesystem-specific hash(es) needed for directory lookups. This | |
643 | allows the filesystem to still, with a high degree of confidence, map | |
644 | the filename given in ->lookup() back to a particular directory entry | |
645 | that was previously listed by readdir(). See :c:type:`struct | |
646 | fscrypt_digested_name` in the source for more details. | |
647 | ||
648 | Note that the precise way that filenames are presented to userspace | |
649 | without the key is subject to change in the future. It is only meant | |
650 | as a way to temporarily present valid filenames so that commands like | |
651 | ``rm -r`` work as expected on encrypted directories. | |
05643363 EB |
652 | |
653 | Tests | |
654 | ===== | |
655 | ||
656 | To test fscrypt, use xfstests, which is Linux's de facto standard | |
657 | filesystem test suite. First, run all the tests in the "encrypt" | |
658 | group on the relevant filesystem(s). For example, to test ext4 and | |
659 | f2fs encryption using `kvm-xfstests | |
660 | <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: | |
661 | ||
662 | kvm-xfstests -c ext4,f2fs -g encrypt | |
663 | ||
664 | UBIFS encryption can also be tested this way, but it should be done in | |
665 | a separate command, and it takes some time for kvm-xfstests to set up | |
666 | emulated UBI volumes:: | |
667 | ||
668 | kvm-xfstests -c ubifs -g encrypt | |
669 | ||
670 | No tests should fail. However, tests that use non-default encryption | |
671 | modes (e.g. generic/549 and generic/550) will be skipped if the needed | |
672 | algorithms were not built into the kernel's crypto API. Also, tests | |
673 | that access the raw block device (e.g. generic/399, generic/548, | |
674 | generic/549, generic/550) will be skipped on UBIFS. | |
675 | ||
676 | Besides running the "encrypt" group tests, for ext4 and f2fs it's also | |
677 | possible to run most xfstests with the "test_dummy_encryption" mount | |
678 | option. This option causes all new files to be automatically | |
679 | encrypted with a dummy key, without having to make any API calls. | |
680 | This tests the encrypted I/O paths more thoroughly. To do this with | |
681 | kvm-xfstests, use the "encrypt" filesystem configuration:: | |
682 | ||
683 | kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto | |
684 | ||
685 | Because this runs many more tests than "-g encrypt" does, it takes | |
686 | much longer to run; so also consider using `gce-xfstests | |
687 | <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_ | |
688 | instead of kvm-xfstests:: | |
689 | ||
690 | gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto |