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