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