]>
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 EB |
193 | AES-128-CBC was added only for low-powered embedded devices with |
194 | crypto accelerators such as CAAM or CESA that do not support XTS. | |
195 | ||
8094c3ce EB |
196 | Adiantum is a (primarily) stream cipher-based mode that is fast even |
197 | on CPUs without dedicated crypto instructions. It's also a true | |
198 | wide-block mode, unlike XTS. It can also eliminate the need to derive | |
199 | per-file keys. However, it depends on the security of two primitives, | |
200 | XChaCha12 and AES-256, rather than just one. See the paper | |
201 | "Adiantum: length-preserving encryption for entry-level processors" | |
202 | (https://eprint.iacr.org/2018/720.pdf) for more details. To use | |
203 | Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast | |
204 | implementations of ChaCha and NHPoly1305 should be enabled, e.g. | |
205 | CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. | |
206 | ||
f4f864c1 EB |
207 | New encryption modes can be added relatively easily, without changes |
208 | to individual filesystems. However, authenticated encryption (AE) | |
209 | modes are not currently supported because of the difficulty of dealing | |
210 | with ciphertext expansion. | |
211 | ||
8094c3ce EB |
212 | Contents encryption |
213 | ------------------- | |
214 | ||
f4f864c1 EB |
215 | For file contents, each filesystem block is encrypted independently. |
216 | Currently, only the case where the filesystem block size is equal to | |
8094c3ce EB |
217 | the system's page size (usually 4096 bytes) is supported. |
218 | ||
219 | Each block's IV is set to the logical block number within the file as | |
220 | a little endian number, except that: | |
221 | ||
222 | - With CBC mode encryption, ESSIV is also used. Specifically, each IV | |
223 | is encrypted with AES-256 where the AES-256 key is the SHA-256 hash | |
224 | of the file's data encryption key. | |
225 | ||
226 | - In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in | |
227 | the fscrypt_policy), the file's nonce is also appended to the IV. | |
228 | Currently this is only allowed with the Adiantum encryption mode. | |
229 | ||
230 | Filenames encryption | |
231 | -------------------- | |
232 | ||
233 | For filenames, each full filename is encrypted at once. Because of | |
234 | the requirements to retain support for efficient directory lookups and | |
235 | filenames of up to 255 bytes, the same IV is used for every filename | |
236 | in a directory. | |
237 | ||
238 | However, each encrypted directory still uses a unique key; or | |
239 | alternatively (for the "direct key" configuration) has the file's | |
240 | nonce included in the IVs. Thus, IV reuse is limited to within a | |
241 | single directory. | |
242 | ||
243 | With CTS-CBC, the IV reuse means that when the plaintext filenames | |
244 | share a common prefix at least as long as the cipher block size (16 | |
245 | bytes for AES), the corresponding encrypted filenames will also share | |
246 | a common prefix. This is undesirable. Adiantum does not have this | |
247 | weakness, as it is a wide-block encryption mode. | |
248 | ||
249 | All supported filenames encryption modes accept any plaintext length | |
250 | >= 16 bytes; cipher block alignment is not required. However, | |
251 | filenames shorter than 16 bytes are NUL-padded to 16 bytes before | |
252 | being encrypted. In addition, to reduce leakage of filename lengths | |
253 | via their ciphertexts, all filenames are NUL-padded to the next 4, 8, | |
254 | 16, or 32-byte boundary (configurable). 32 is recommended since this | |
255 | provides the best confidentiality, at the cost of making directory | |
256 | entries consume slightly more space. Note that since NUL (``\0``) is | |
257 | not otherwise a valid character in filenames, the padding will never | |
258 | produce duplicate plaintexts. | |
f4f864c1 EB |
259 | |
260 | Symbolic link targets are considered a type of filename and are | |
8094c3ce EB |
261 | encrypted in the same way as filenames in directory entries, except |
262 | that IV reuse is not a problem as each symlink has its own inode. | |
f4f864c1 EB |
263 | |
264 | User API | |
265 | ======== | |
266 | ||
267 | Setting an encryption policy | |
268 | ---------------------------- | |
269 | ||
270 | The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an | |
271 | empty directory or verifies that a directory or regular file already | |
272 | has the specified encryption policy. It takes in a pointer to a | |
273 | :c:type:`struct fscrypt_policy`, defined as follows:: | |
274 | ||
275 | #define FS_KEY_DESCRIPTOR_SIZE 8 | |
276 | ||
277 | struct fscrypt_policy { | |
278 | __u8 version; | |
279 | __u8 contents_encryption_mode; | |
280 | __u8 filenames_encryption_mode; | |
281 | __u8 flags; | |
282 | __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; | |
283 | }; | |
284 | ||
285 | This structure must be initialized as follows: | |
286 | ||
287 | - ``version`` must be 0. | |
288 | ||
289 | - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must | |
290 | be set to constants from ``<linux/fs.h>`` which identify the | |
291 | encryption modes to use. If unsure, use | |
292 | FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` | |
293 | and FS_ENCRYPTION_MODE_AES_256_CTS (4) for | |
294 | ``filenames_encryption_mode``. | |
295 | ||
8094c3ce | 296 | - ``flags`` must contain a value from ``<linux/fs.h>`` which |
f4f864c1 EB |
297 | identifies the amount of NUL-padding to use when encrypting |
298 | filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3). | |
8094c3ce EB |
299 | In addition, if the chosen encryption modes are both |
300 | FS_ENCRYPTION_MODE_ADIANTUM, this can contain | |
301 | FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be | |
302 | used directly, without key derivation. | |
f4f864c1 EB |
303 | |
304 | - ``master_key_descriptor`` specifies how to find the master key in | |
305 | the keyring; see `Adding keys`_. It is up to userspace to choose a | |
306 | unique ``master_key_descriptor`` for each master key. The e4crypt | |
307 | and fscrypt tools use the first 8 bytes of | |
308 | ``SHA-512(SHA-512(master_key))``, but this particular scheme is not | |
309 | required. Also, the master key need not be in the keyring yet when | |
310 | FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added | |
311 | before any files can be created in the encrypted directory. | |
312 | ||
313 | If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY | |
314 | verifies that the file is an empty directory. If so, the specified | |
315 | encryption policy is assigned to the directory, turning it into an | |
316 | encrypted directory. After that, and after providing the | |
317 | corresponding master key as described in `Adding keys`_, all regular | |
318 | files, directories (recursively), and symlinks created in the | |
319 | directory will be encrypted, inheriting the same encryption policy. | |
320 | The filenames in the directory's entries will be encrypted as well. | |
321 | ||
322 | Alternatively, if the file is already encrypted, then | |
323 | FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption | |
324 | policy exactly matches the actual one. If they match, then the ioctl | |
325 | returns 0. Otherwise, it fails with EEXIST. This works on both | |
326 | regular files and directories, including nonempty directories. | |
327 | ||
328 | Note that the ext4 filesystem does not allow the root directory to be | |
329 | encrypted, even if it is empty. Users who want to encrypt an entire | |
330 | filesystem with one key should consider using dm-crypt instead. | |
331 | ||
332 | FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: | |
333 | ||
334 | - ``EACCES``: the file is not owned by the process's uid, nor does the | |
335 | process have the CAP_FOWNER capability in a namespace with the file | |
336 | owner's uid mapped | |
337 | - ``EEXIST``: the file is already encrypted with an encryption policy | |
338 | different from the one specified | |
339 | - ``EINVAL``: an invalid encryption policy was specified (invalid | |
340 | version, mode(s), or flags) | |
341 | - ``ENOTDIR``: the file is unencrypted and is a regular file, not a | |
342 | directory | |
343 | - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory | |
344 | - ``ENOTTY``: this type of filesystem does not implement encryption | |
345 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
643fa961 | 346 | support for filesystems, or the filesystem superblock has not |
f4f864c1 | 347 | had encryption enabled on it. (For example, to use encryption on an |
643fa961 | 348 | ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the |
f4f864c1 EB |
349 | kernel config, and the superblock must have had the "encrypt" |
350 | feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O | |
351 | encrypt``.) | |
352 | - ``EPERM``: this directory may not be encrypted, e.g. because it is | |
353 | the root directory of an ext4 filesystem | |
354 | - ``EROFS``: the filesystem is readonly | |
355 | ||
356 | Getting an encryption policy | |
357 | ---------------------------- | |
358 | ||
359 | The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct | |
360 | fscrypt_policy`, if any, for a directory or regular file. See above | |
361 | for the struct definition. No additional permissions are required | |
362 | beyond the ability to open the file. | |
363 | ||
364 | FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors: | |
365 | ||
366 | - ``EINVAL``: the file is encrypted, but it uses an unrecognized | |
367 | encryption context format | |
368 | - ``ENODATA``: the file is not encrypted | |
369 | - ``ENOTTY``: this type of filesystem does not implement encryption | |
370 | - ``EOPNOTSUPP``: the kernel was not configured with encryption | |
371 | support for this filesystem | |
372 | ||
373 | Note: if you only need to know whether a file is encrypted or not, on | |
374 | most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl | |
375 | and check for FS_ENCRYPT_FL, or to use the statx() system call and | |
376 | check for STATX_ATTR_ENCRYPTED in stx_attributes. | |
377 | ||
378 | Getting the per-filesystem salt | |
379 | ------------------------------- | |
380 | ||
381 | Some filesystems, such as ext4 and F2FS, also support the deprecated | |
382 | ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly | |
383 | generated 16-byte value stored in the filesystem superblock. This | |
384 | value is intended to used as a salt when deriving an encryption key | |
385 | from a passphrase or other low-entropy user credential. | |
386 | ||
387 | FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to | |
388 | generate and manage any needed salt(s) in userspace. | |
389 | ||
390 | Adding keys | |
391 | ----------- | |
392 | ||
393 | To provide a master key, userspace must add it to an appropriate | |
394 | keyring using the add_key() system call (see: | |
395 | ``Documentation/security/keys/core.rst``). The key type must be | |
396 | "logon"; keys of this type are kept in kernel memory and cannot be | |
397 | read back by userspace. The key description must be "fscrypt:" | |
398 | followed by the 16-character lower case hex representation of the | |
399 | ``master_key_descriptor`` that was set in the encryption policy. The | |
400 | key payload must conform to the following structure:: | |
401 | ||
402 | #define FS_MAX_KEY_SIZE 64 | |
403 | ||
404 | struct fscrypt_key { | |
405 | u32 mode; | |
406 | u8 raw[FS_MAX_KEY_SIZE]; | |
407 | u32 size; | |
408 | }; | |
409 | ||
410 | ``mode`` is ignored; just set it to 0. The actual key is provided in | |
411 | ``raw`` with ``size`` indicating its size in bytes. That is, the | |
412 | bytes ``raw[0..size-1]`` (inclusive) are the actual key. | |
413 | ||
414 | The key description prefix "fscrypt:" may alternatively be replaced | |
415 | with a filesystem-specific prefix such as "ext4:". However, the | |
416 | filesystem-specific prefixes are deprecated and should not be used in | |
417 | new programs. | |
418 | ||
419 | There are several different types of keyrings in which encryption keys | |
420 | may be placed, such as a session keyring, a user session keyring, or a | |
421 | user keyring. Each key must be placed in a keyring that is "attached" | |
422 | to all processes that might need to access files encrypted with it, in | |
423 | the sense that request_key() will find the key. Generally, if only | |
424 | processes belonging to a specific user need to access a given | |
425 | encrypted directory and no session keyring has been installed, then | |
426 | that directory's key should be placed in that user's user session | |
427 | keyring or user keyring. Otherwise, a session keyring should be | |
428 | installed if needed, and the key should be linked into that session | |
429 | keyring, or in a keyring linked into that session keyring. | |
430 | ||
431 | Note: introducing the complex visibility semantics of keyrings here | |
432 | was arguably a mistake --- especially given that by design, after any | |
433 | process successfully opens an encrypted file (thereby setting up the | |
434 | per-file key), possessing the keyring key is not actually required for | |
435 | any process to read/write the file until its in-memory inode is | |
436 | evicted. In the future there probably should be a way to provide keys | |
437 | directly to the filesystem instead, which would make the intended | |
438 | semantics clearer. | |
439 | ||
440 | Access semantics | |
441 | ================ | |
442 | ||
443 | With the key | |
444 | ------------ | |
445 | ||
446 | With the encryption key, encrypted regular files, directories, and | |
447 | symlinks behave very similarly to their unencrypted counterparts --- | |
448 | after all, the encryption is intended to be transparent. However, | |
449 | astute users may notice some differences in behavior: | |
450 | ||
451 | - Unencrypted files, or files encrypted with a different encryption | |
452 | policy (i.e. different key, modes, or flags), cannot be renamed or | |
453 | linked into an encrypted directory; see `Encryption policy | |
f5e55e77 | 454 | enforcement`_. Attempts to do so will fail with EXDEV. However, |
f4f864c1 EB |
455 | encrypted files can be renamed within an encrypted directory, or |
456 | into an unencrypted directory. | |
457 | ||
f5e55e77 EB |
458 | Note: "moving" an unencrypted file into an encrypted directory, e.g. |
459 | with the `mv` program, is implemented in userspace by a copy | |
460 | followed by a delete. Be aware that the original unencrypted data | |
461 | may remain recoverable from free space on the disk; prefer to keep | |
462 | all files encrypted from the very beginning. The `shred` program | |
463 | may be used to overwrite the source files but isn't guaranteed to be | |
464 | effective on all filesystems and storage devices. | |
465 | ||
f4f864c1 EB |
466 | - Direct I/O is not supported on encrypted files. Attempts to use |
467 | direct I/O on such files will fall back to buffered I/O. | |
468 | ||
469 | - The fallocate operations FALLOC_FL_COLLAPSE_RANGE, | |
470 | FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported | |
471 | on encrypted files and will fail with EOPNOTSUPP. | |
472 | ||
473 | - Online defragmentation of encrypted files is not supported. The | |
474 | EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with | |
475 | EOPNOTSUPP. | |
476 | ||
477 | - The ext4 filesystem does not support data journaling with encrypted | |
478 | regular files. It will fall back to ordered data mode instead. | |
479 | ||
480 | - DAX (Direct Access) is not supported on encrypted files. | |
481 | ||
482 | - The st_size of an encrypted symlink will not necessarily give the | |
483 | length of the symlink target as required by POSIX. It will actually | |
2f46a2bc EB |
484 | give the length of the ciphertext, which will be slightly longer |
485 | than the plaintext due to NUL-padding and an extra 2-byte overhead. | |
486 | ||
487 | - The maximum length of an encrypted symlink is 2 bytes shorter than | |
488 | the maximum length of an unencrypted symlink. For example, on an | |
489 | EXT4 filesystem with a 4K block size, unencrypted symlinks can be up | |
490 | to 4095 bytes long, while encrypted symlinks can only be up to 4093 | |
491 | bytes long (both lengths excluding the terminating null). | |
f4f864c1 EB |
492 | |
493 | Note that mmap *is* supported. This is possible because the pagecache | |
494 | for an encrypted file contains the plaintext, not the ciphertext. | |
495 | ||
496 | Without the key | |
497 | --------------- | |
498 | ||
499 | Some filesystem operations may be performed on encrypted regular | |
500 | files, directories, and symlinks even before their encryption key has | |
501 | been provided: | |
502 | ||
503 | - File metadata may be read, e.g. using stat(). | |
504 | ||
505 | - Directories may be listed, in which case the filenames will be | |
506 | listed in an encoded form derived from their ciphertext. The | |
507 | current encoding algorithm is described in `Filename hashing and | |
508 | encoding`_. The algorithm is subject to change, but it is | |
509 | guaranteed that the presented filenames will be no longer than | |
510 | NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and | |
511 | will uniquely identify directory entries. | |
512 | ||
513 | The ``.`` and ``..`` directory entries are special. They are always | |
514 | present and are not encrypted or encoded. | |
515 | ||
516 | - Files may be deleted. That is, nondirectory files may be deleted | |
517 | with unlink() as usual, and empty directories may be deleted with | |
518 | rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as | |
519 | expected. | |
520 | ||
521 | - Symlink targets may be read and followed, but they will be presented | |
522 | in encrypted form, similar to filenames in directories. Hence, they | |
523 | are unlikely to point to anywhere useful. | |
524 | ||
525 | Without the key, regular files cannot be opened or truncated. | |
526 | Attempts to do so will fail with ENOKEY. This implies that any | |
527 | regular file operations that require a file descriptor, such as | |
528 | read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. | |
529 | ||
530 | Also without the key, files of any type (including directories) cannot | |
531 | be created or linked into an encrypted directory, nor can a name in an | |
532 | encrypted directory be the source or target of a rename, nor can an | |
533 | O_TMPFILE temporary file be created in an encrypted directory. All | |
534 | such operations will fail with ENOKEY. | |
535 | ||
536 | It is not currently possible to backup and restore encrypted files | |
537 | without the encryption key. This would require special APIs which | |
538 | have not yet been implemented. | |
539 | ||
540 | Encryption policy enforcement | |
541 | ============================= | |
542 | ||
543 | After an encryption policy has been set on a directory, all regular | |
544 | files, directories, and symbolic links created in that directory | |
545 | (recursively) will inherit that encryption policy. Special files --- | |
546 | that is, named pipes, device nodes, and UNIX domain sockets --- will | |
547 | not be encrypted. | |
548 | ||
549 | Except for those special files, it is forbidden to have unencrypted | |
550 | files, or files encrypted with a different encryption policy, in an | |
551 | encrypted directory tree. Attempts to link or rename such a file into | |
f5e55e77 | 552 | an encrypted directory will fail with EXDEV. This is also enforced |
f4f864c1 EB |
553 | during ->lookup() to provide limited protection against offline |
554 | attacks that try to disable or downgrade encryption in known locations | |
555 | where applications may later write sensitive data. It is recommended | |
556 | that systems implementing a form of "verified boot" take advantage of | |
557 | this by validating all top-level encryption policies prior to access. | |
558 | ||
559 | Implementation details | |
560 | ====================== | |
561 | ||
562 | Encryption context | |
563 | ------------------ | |
564 | ||
565 | An encryption policy is represented on-disk by a :c:type:`struct | |
566 | fscrypt_context`. It is up to individual filesystems to decide where | |
567 | to store it, but normally it would be stored in a hidden extended | |
568 | attribute. It should *not* be exposed by the xattr-related system | |
569 | calls such as getxattr() and setxattr() because of the special | |
570 | semantics of the encryption xattr. (In particular, there would be | |
571 | much confusion if an encryption policy were to be added to or removed | |
572 | from anything other than an empty directory.) The struct is defined | |
573 | as follows:: | |
574 | ||
575 | #define FS_KEY_DESCRIPTOR_SIZE 8 | |
576 | #define FS_KEY_DERIVATION_NONCE_SIZE 16 | |
577 | ||
578 | struct fscrypt_context { | |
579 | u8 format; | |
580 | u8 contents_encryption_mode; | |
581 | u8 filenames_encryption_mode; | |
582 | u8 flags; | |
583 | u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; | |
584 | u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; | |
585 | }; | |
586 | ||
587 | Note that :c:type:`struct fscrypt_context` contains the same | |
588 | information as :c:type:`struct fscrypt_policy` (see `Setting an | |
589 | encryption policy`_), except that :c:type:`struct fscrypt_context` | |
590 | also contains a nonce. The nonce is randomly generated by the kernel | |
591 | and is used to derive the inode's encryption key as described in | |
592 | `Per-file keys`_. | |
593 | ||
594 | Data path changes | |
595 | ----------------- | |
596 | ||
597 | For the read path (->readpage()) of regular files, filesystems can | |
598 | read the ciphertext into the page cache and decrypt it in-place. The | |
599 | page lock must be held until decryption has finished, to prevent the | |
600 | page from becoming visible to userspace prematurely. | |
601 | ||
602 | For the write path (->writepage()) of regular files, filesystems | |
603 | cannot encrypt data in-place in the page cache, since the cached | |
604 | plaintext must be preserved. Instead, filesystems must encrypt into a | |
605 | temporary buffer or "bounce page", then write out the temporary | |
606 | buffer. Some filesystems, such as UBIFS, already use temporary | |
607 | buffers regardless of encryption. Other filesystems, such as ext4 and | |
608 | F2FS, have to allocate bounce pages specially for encryption. | |
609 | ||
610 | Filename hashing and encoding | |
611 | ----------------------------- | |
612 | ||
613 | Modern filesystems accelerate directory lookups by using indexed | |
614 | directories. An indexed directory is organized as a tree keyed by | |
615 | filename hashes. When a ->lookup() is requested, the filesystem | |
616 | normally hashes the filename being looked up so that it can quickly | |
617 | find the corresponding directory entry, if any. | |
618 | ||
619 | With encryption, lookups must be supported and efficient both with and | |
620 | without the encryption key. Clearly, it would not work to hash the | |
621 | plaintext filenames, since the plaintext filenames are unavailable | |
622 | without the key. (Hashing the plaintext filenames would also make it | |
623 | impossible for the filesystem's fsck tool to optimize encrypted | |
624 | directories.) Instead, filesystems hash the ciphertext filenames, | |
625 | i.e. the bytes actually stored on-disk in the directory entries. When | |
626 | asked to do a ->lookup() with the key, the filesystem just encrypts | |
627 | the user-supplied name to get the ciphertext. | |
628 | ||
629 | Lookups without the key are more complicated. The raw ciphertext may | |
630 | contain the ``\0`` and ``/`` characters, which are illegal in | |
631 | filenames. Therefore, readdir() must base64-encode the ciphertext for | |
632 | presentation. For most filenames, this works fine; on ->lookup(), the | |
633 | filesystem just base64-decodes the user-supplied name to get back to | |
634 | the raw ciphertext. | |
635 | ||
636 | However, for very long filenames, base64 encoding would cause the | |
637 | filename length to exceed NAME_MAX. To prevent this, readdir() | |
638 | actually presents long filenames in an abbreviated form which encodes | |
639 | a strong "hash" of the ciphertext filename, along with the optional | |
640 | filesystem-specific hash(es) needed for directory lookups. This | |
641 | allows the filesystem to still, with a high degree of confidence, map | |
642 | the filename given in ->lookup() back to a particular directory entry | |
643 | that was previously listed by readdir(). See :c:type:`struct | |
644 | fscrypt_digested_name` in the source for more details. | |
645 | ||
646 | Note that the precise way that filenames are presented to userspace | |
647 | without the key is subject to change in the future. It is only meant | |
648 | as a way to temporarily present valid filenames so that commands like | |
649 | ``rm -r`` work as expected on encrypted directories. |