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