1 =====================================
2 Filesystem-level encryption (fscrypt)
3 =====================================
8 fscrypt is a library which filesystems can hook into to support
9 transparent encryption of files and directories.
11 Note: "fscrypt" in this document refers to the kernel-level portion,
12 implemented in ``fs/crypto/``, as opposed to the userspace tool
13 `fscrypt <https://github.com/google/fscrypt>`_. This document only
14 covers the kernel-level portion. For command-line examples of how to
15 use encryption, see the documentation for the userspace tool `fscrypt
16 <https://github.com/google/fscrypt>`_. Also, it is recommended to use
17 the fscrypt userspace tool, or other existing userspace tools such as
18 `fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key
20 <https://source.android.com/security/encryption/file-based>`_, over
21 using the kernel's API directly. Using existing tools reduces the
22 chance of introducing your own security bugs. (Nevertheless, for
23 completeness this documentation covers the kernel's API anyway.)
25 Unlike dm-crypt, fscrypt operates at the filesystem level rather than
26 at the block device level. This allows it to encrypt different files
27 with different keys and to have unencrypted files on the same
28 filesystem. This is useful for multi-user systems where each user's
29 data-at-rest needs to be cryptographically isolated from the others.
30 However, except for filenames, fscrypt does not encrypt filesystem
33 Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated
34 directly into supported filesystems --- currently ext4, F2FS, UBIFS,
35 and CephFS. This allows encrypted files to be read and written
36 without caching both the decrypted and encrypted pages in the
37 pagecache, thereby nearly halving the memory used and bringing it in
38 line with unencrypted files. Similarly, half as many dentries and
39 inodes are needed. eCryptfs also limits encrypted filenames to 143
40 bytes, causing application compatibility issues; fscrypt allows the
41 full 255 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API
42 can be used by unprivileged users, with no need to mount anything.
44 fscrypt does not support encrypting files in-place. Instead, it
45 supports marking an empty directory as encrypted. Then, after
46 userspace provides the key, all regular files, directories, and
47 symbolic links created in that directory tree are transparently
56 Provided that userspace chooses a strong encryption key, fscrypt
57 protects the confidentiality of file contents and filenames in the
58 event of a single point-in-time permanent offline compromise of the
59 block device content. fscrypt does not protect the confidentiality of
60 non-filename metadata, e.g. file sizes, file permissions, file
61 timestamps, and extended attributes. Also, the existence and location
62 of holes (unallocated blocks which logically contain all zeroes) in
63 files is not protected.
65 fscrypt is not guaranteed to protect confidentiality or authenticity
66 if an attacker is able to manipulate the filesystem offline prior to
67 an authorized user later accessing the filesystem.
72 fscrypt (and storage encryption in general) can only provide limited
73 protection, if any at all, against online attacks. In detail:
78 fscrypt is only resistant to side-channel attacks, such as timing or
79 electromagnetic attacks, to the extent that the underlying Linux
80 Cryptographic API algorithms or inline encryption hardware are. If a
81 vulnerable algorithm is used, such as a table-based implementation of
82 AES, it may be possible for an attacker to mount a side channel attack
83 against the online system. Side channel attacks may also be mounted
84 against applications consuming decrypted data.
86 Unauthorized file access
87 ~~~~~~~~~~~~~~~~~~~~~~~~
89 After an encryption key has been added, fscrypt does not hide the
90 plaintext file contents or filenames from other users on the same
91 system. Instead, existing access control mechanisms such as file mode
92 bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose.
94 (For the reasoning behind this, understand that while the key is
95 added, the confidentiality of the data, from the perspective of the
96 system itself, is *not* protected by the mathematical properties of
97 encryption but rather only by the correctness of the kernel.
98 Therefore, any encryption-specific access control checks would merely
99 be enforced by kernel *code* and therefore would be largely redundant
100 with the wide variety of access control mechanisms already available.)
102 Kernel memory compromise
103 ~~~~~~~~~~~~~~~~~~~~~~~~
105 An attacker who compromises the system enough to read from arbitrary
106 memory, e.g. by mounting a physical attack or by exploiting a kernel
107 security vulnerability, can compromise all encryption keys that are
110 However, fscrypt allows encryption keys to be removed from the kernel,
111 which may protect them from later compromise.
113 In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the
114 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
115 encryption key from kernel memory. If it does so, it will also try to
116 evict all cached inodes which had been "unlocked" using the key,
117 thereby wiping their per-file keys and making them once again appear
118 "locked", i.e. in ciphertext or encrypted form.
120 However, these ioctls have some limitations:
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
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.
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.
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.
148 Limitations of v1 policies
149 ~~~~~~~~~~~~~~~~~~~~~~~~~~
151 v1 encryption policies have some weaknesses with respect to online
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".
162 - A compromise of a per-file key also compromises the master key from
163 which it was derived.
165 - Non-root users cannot securely remove encryption keys.
167 All the above problems are fixed with v2 encryption policies. For
168 this reason among others, it is recommended to use v2 encryption
169 policies on all new encrypted directories.
177 Each encrypted directory tree is protected by a *master key*. Master
178 keys can be up to 64 bytes long, and must be at least as long as the
179 greater of the security strength of the contents and filenames
180 encryption modes being used. For example, if any AES-256 mode is
181 used, the master key must be at least 256 bits, i.e. 32 bytes. A
182 stricter requirement applies if the key is used by a v1 encryption
183 policy and AES-256-XTS is used; such keys must be 64 bytes.
185 To "unlock" an encrypted directory tree, userspace must provide the
186 appropriate master key. There can be any number of master keys, each
187 of which protects any number of directory trees on any number of
190 Master keys must be real cryptographic keys, i.e. indistinguishable
191 from random bytestrings of the same length. This implies that users
192 **must not** directly use a password as a master key, zero-pad a
193 shorter key, or repeat a shorter key. Security cannot be guaranteed
194 if userspace makes any such error, as the cryptographic proofs and
195 analysis would no longer apply.
197 Instead, users should generate master keys either using a
198 cryptographically secure random number generator, or by using a KDF
199 (Key Derivation Function). The kernel does not do any key stretching;
200 therefore, if userspace derives the key from a low-entropy secret such
201 as a passphrase, it is critical that a KDF designed for this purpose
202 be used, such as scrypt, PBKDF2, or Argon2.
204 Key derivation function
205 -----------------------
207 With one exception, fscrypt never uses the master key(s) for
208 encryption directly. Instead, they are only used as input to a KDF
209 (Key Derivation Function) to derive the actual keys.
211 The KDF used for a particular master key differs depending on whether
212 the key is used for v1 encryption policies or for v2 encryption
213 policies. Users **must not** use the same key for both v1 and v2
214 encryption policies. (No real-world attack is currently known on this
215 specific case of key reuse, but its security cannot be guaranteed
216 since the cryptographic proofs and analysis would no longer apply.)
218 For v1 encryption policies, the KDF only supports deriving per-file
219 encryption keys. It works by encrypting the master key with
220 AES-128-ECB, using the file's 16-byte nonce as the AES key. The
221 resulting ciphertext is used as the derived key. If the ciphertext is
222 longer than needed, then it is truncated to the needed length.
224 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
225 passed as the "input keying material", no salt is used, and a distinct
226 "application-specific information string" is used for each distinct
227 key to be derived. For example, when a per-file encryption key is
228 derived, the application-specific information string is the file's
229 nonce prefixed with "fscrypt\\0" and a context byte. Different
230 context bytes are used for other types of derived keys.
232 HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
233 HKDF is more flexible, is nonreversible, and evenly distributes
234 entropy from the master key. HKDF is also standardized and widely
235 used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
237 Per-file encryption keys
238 ------------------------
240 Since 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
242 files doesn't map to the same ciphertext, or vice versa. In most
243 cases, fscrypt does this by deriving per-file keys. When a new
244 encrypted inode (regular file, directory, or symlink) is created,
245 fscrypt randomly generates a 16-byte nonce and stores it in the
246 inode's encryption xattr. Then, it uses a KDF (as described in `Key
247 derivation function`_) to derive the file's key from the master key
250 Key derivation was chosen over key wrapping because wrapped keys would
251 require larger xattrs which would be less likely to fit in-line in the
252 filesystem's inode table, and there didn't appear to be any
253 significant advantages to key wrapping. In particular, currently
254 there is no requirement to support unlocking a file with multiple
255 alternative master keys or to support rotating master keys. Instead,
256 the master keys may be wrapped in userspace, e.g. as is done by the
257 `fscrypt <https://github.com/google/fscrypt>`_ tool.
262 The Adiantum encryption mode (see `Encryption modes and usage`_) is
263 suitable for both contents and filenames encryption, and it accepts
264 long IVs --- long enough to hold both an 8-byte data unit index and a
265 16-byte per-file nonce. Also, the overhead of each Adiantum key is
266 greater than that of an AES-256-XTS key.
268 Therefore, to improve performance and save memory, for Adiantum a
269 "direct key" configuration is supported. When the user has enabled
270 this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
271 per-file encryption keys are not used. Instead, whenever any data
272 (contents or filenames) is encrypted, the file's 16-byte nonce is
273 included in the IV. Moreover:
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.
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.
283 IV_INO_LBLK_64 policies
284 -----------------------
286 When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy,
287 the encryption keys are derived from the master key, encryption mode
288 number, and filesystem UUID. This normally results in all files
289 protected by the same master key sharing a single contents encryption
290 key and a single filenames encryption key. To still encrypt different
291 files' data differently, inode numbers are included in the IVs.
292 Consequently, shrinking the filesystem may not be allowed.
294 This format is optimized for use with inline encryption hardware
295 compliant with the UFS standard, which supports only 64 IV bits per
296 I/O request and may have only a small number of keyslots.
298 IV_INO_LBLK_32 policies
299 -----------------------
301 IV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for
302 IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
303 SipHash key is derived from the master key) and added to the file data
304 unit index mod 2^32 to produce a 32-bit IV.
306 This format is optimized for use with inline encryption hardware
307 compliant with the eMMC v5.2 standard, which supports only 32 IV bits
308 per I/O request and may have only a small number of keyslots. This
309 format results in some level of IV reuse, so it should only be used
310 when necessary due to hardware limitations.
315 For master keys used for v2 encryption policies, a unique 16-byte "key
316 identifier" is also derived using the KDF. This value is stored in
317 the clear, since it is needed to reliably identify the key itself.
322 For directories that are indexed using a secret-keyed dirhash over the
323 plaintext filenames, the KDF is also used to derive a 128-bit
324 SipHash-2-4 key per directory in order to hash filenames. This works
325 just like deriving a per-file encryption key, except that a different
326 KDF context is used. Currently, only casefolded ("case-insensitive")
327 encrypted directories use this style of hashing.
329 Encryption modes and usage
330 ==========================
332 fscrypt allows one encryption mode to be specified for file contents
333 and one encryption mode to be specified for filenames. Different
334 directory trees are permitted to use different encryption modes.
339 Currently, the following pairs of encryption modes are supported:
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
347 Authenticated encryption modes are not currently supported because of
348 the difficulty of dealing with ciphertext expansion. Therefore,
349 contents encryption uses a block cipher in `XTS mode
350 <https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or
352 <https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_,
353 or a wide-block cipher. Filenames encryption uses a
354 block cipher in `CTS-CBC mode
355 <https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
358 The (AES-256-XTS, AES-256-CTS-CBC) pair is the recommended default.
359 It is also the only option that is *guaranteed* to always be supported
360 if the kernel supports fscrypt at all; see `Kernel config options`_.
362 The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
363 upgrades the filenames encryption to use a wide-block cipher. (A
364 *wide-block cipher*, also called a tweakable super-pseudorandom
365 permutation, has the property that changing one bit scrambles the
366 entire result.) As described in `Filenames encryption`_, a wide-block
367 cipher is the ideal mode for the problem domain, though CTS-CBC is the
368 "least bad" choice among the alternatives. For more information about
369 HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_.
371 Adiantum is recommended on systems where AES is too slow due to lack
372 of hardware acceleration for AES. Adiantum is a wide-block cipher
373 that uses XChaCha12 and AES-256 as its underlying components. Most of
374 the work is done by XChaCha12, which is much faster than AES when AES
375 acceleration is unavailable. For more information about Adiantum, see
376 `the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_.
378 The (AES-128-CBC-ESSIV, AES-128-CTS-CBC) pair exists only to support
379 systems whose only form of AES acceleration is an off-CPU crypto
380 accelerator such as CAAM or CESA that does not support XTS.
382 The remaining mode pairs are the "national pride ciphers":
384 - (SM4-XTS, SM4-CTS-CBC)
386 Generally speaking, these ciphers aren't "bad" per se, but they
387 receive limited security review compared to the usual choices such as
388 AES and ChaCha. They also don't bring much new to the table. It is
389 suggested to only use these ciphers where their use is mandated.
391 Kernel config options
392 ---------------------
394 Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in
395 only the basic support from the crypto API needed to use AES-256-XTS
396 and AES-256-CTS-CBC encryption. For optimal performance, it is
397 strongly recommended to also enable any available platform-specific
398 kconfig options that provide acceleration for the algorithm(s) you
399 wish to use. Support for any "non-default" encryption modes typically
400 requires extra kconfig options as well.
402 Below, some relevant options are listed by encryption mode. Note,
403 acceleration options not listed below may be available for your
404 platform; refer to the kconfig menus. File contents encryption can
405 also be configured to use inline encryption hardware instead of the
406 kernel crypto API (see `Inline encryption support`_); in that case,
407 the file contents mode doesn't need to supported in the kernel crypto
408 API, but the filenames mode still does.
410 - AES-256-XTS and AES-256-CTS-CBC
412 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
413 - x86: CONFIG_CRYPTO_AES_NI_INTEL
417 - CONFIG_CRYPTO_HCTR2
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
426 - CONFIG_CRYPTO_ADIANTUM
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
436 - AES-128-CBC-ESSIV and AES-128-CTS-CBC:
438 - CONFIG_CRYPTO_ESSIV
439 - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
441 - AES-CBC acceleration
443 fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512
444 acceleration is recommended:
448 - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
449 - x86: CONFIG_CRYPTO_SHA512_SSSE3
454 For contents encryption, each file's contents is divided into "data
455 units". Each data unit is encrypted independently. The IV for each
456 data unit incorporates the zero-based index of the data unit within
457 the file. This ensures that each data unit within a file is encrypted
458 differently, which is essential to prevent leaking information.
460 Note: the encryption depending on the offset into the file means that
461 operations like "collapse range" and "insert range" that rearrange the
462 extent mapping of files are not supported on encrypted files.
464 There are two cases for the sizes of the data units:
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`_.
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.
478 In the case of compression + encryption, the compressed data is
479 encrypted. UBIFS compression works as described above. f2fs
480 compression works a bit differently; it compresses a number of
481 filesystem blocks into a smaller number of filesystem blocks.
482 Therefore a f2fs-compressed file still uses fixed-size data units, and
483 it is encrypted in a similar way to a file containing holes.
485 As mentioned in `Key hierarchy`_, the default encryption setting uses
486 per-file keys. In this case, the IV for each data unit is simply the
487 index of the data unit in the file. However, users can select an
488 encryption setting that does not use per-file keys. For these, some
489 kind of file identifier is incorporated into the IVs as follows:
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.
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.
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.
504 The byte order of the IV is always little endian.
506 If the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an
507 ESSIV layer is automatically included. In this case, before the IV is
508 passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
509 key is the SHA-256 hash of the file's contents encryption key.
514 For filenames, each full filename is encrypted at once. Because of
515 the requirements to retain support for efficient directory lookups and
516 filenames of up to 255 bytes, the same IV is used for every filename
519 However, each encrypted directory still uses a unique key, or
520 alternatively has the file's nonce (for `DIRECT_KEY policies`_) or
521 inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs.
522 Thus, IV reuse is limited to within a single directory.
524 With CTS-CBC, the IV reuse means that when the plaintext filenames share a
525 common prefix at least as long as the cipher block size (16 bytes for AES), the
526 corresponding encrypted filenames will also share a common prefix. This is
527 undesirable. Adiantum and HCTR2 do not have this weakness, as they are
528 wide-block encryption modes.
530 All supported filenames encryption modes accept any plaintext length
531 >= 16 bytes; cipher block alignment is not required. However,
532 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
533 being encrypted. In addition, to reduce leakage of filename lengths
534 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
535 16, or 32-byte boundary (configurable). 32 is recommended since this
536 provides the best confidentiality, at the cost of making directory
537 entries consume slightly more space. Note that since NUL (``\0``) is
538 not otherwise a valid character in filenames, the padding will never
539 produce duplicate plaintexts.
541 Symbolic link targets are considered a type of filename and are
542 encrypted in the same way as filenames in directory entries, except
543 that IV reuse is not a problem as each symlink has its own inode.
548 Setting an encryption policy
549 ----------------------------
551 FS_IOC_SET_ENCRYPTION_POLICY
552 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
554 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
555 empty directory or verifies that a directory or regular file already
556 has the specified encryption policy. It takes in a pointer to
557 struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
560 #define FSCRYPT_POLICY_V1 0
561 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
562 struct fscrypt_policy_v1 {
564 __u8 contents_encryption_mode;
565 __u8 filenames_encryption_mode;
567 __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
569 #define fscrypt_policy fscrypt_policy_v1
571 #define FSCRYPT_POLICY_V2 2
572 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
573 struct fscrypt_policy_v2 {
575 __u8 contents_encryption_mode;
576 __u8 filenames_encryption_mode;
578 __u8 log2_data_unit_size;
580 __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
583 This structure must be initialized as follows:
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.
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
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`_.
604 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
606 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
607 encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32
609 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
610 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
612 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
615 v1 encryption policies only support the PAD_* and DIRECT_KEY flags.
616 The other flags are only supported by v2 encryption policies.
618 The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are
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.
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.
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.
641 Leave this field zeroed unless you are certain you need it. Using
642 an unnecessarily small data unit size reduces performance.
644 - For v2 encryption policies, ``__reserved`` must be zeroed.
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.
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.
663 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
664 verifies that the file is an empty directory. If so, the specified
665 encryption policy is assigned to the directory, turning it into an
666 encrypted directory. After that, and after providing the
667 corresponding master key as described in `Adding keys`_, all regular
668 files, directories (recursively), and symlinks created in the
669 directory will be encrypted, inheriting the same encryption policy.
670 The filenames in the directory's entries will be encrypted as well.
672 Alternatively, if the file is already encrypted, then
673 FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
674 policy exactly matches the actual one. If they match, then the ioctl
675 returns 0. Otherwise, it fails with EEXIST. This works on both
676 regular files and directories, including nonempty directories.
678 When a v2 encryption policy is assigned to a directory, it is also
679 required that either the specified key has been added by the current
680 user 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
682 another user's key.) The key must remain added while
683 FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new
684 encrypted directory does not need to be accessed immediately, then the
685 key can be removed right away afterwards.
687 Note that the ext4 filesystem does not allow the root directory to be
688 encrypted, even if it is empty. Users who want to encrypt an entire
689 filesystem with one key should consider using dm-crypt instead.
691 FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
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
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
706 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
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
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
721 Getting an encryption policy
722 ----------------------------
724 Two ioctls are available to get a file's encryption policy:
726 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
727 - `FS_IOC_GET_ENCRYPTION_POLICY`_
729 The extended (_EX) version of the ioctl is more general and is
730 recommended to use when possible. However, on older kernels only the
731 original ioctl is available. Applications should try the extended
732 version, and if it fails with ENOTTY fall back to the original
735 FS_IOC_GET_ENCRYPTION_POLICY_EX
736 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
738 The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
739 policy, if any, for a directory or regular file. No additional
740 permissions are required beyond the ability to open the file. It
741 takes in a pointer to struct fscrypt_get_policy_ex_arg,
744 struct fscrypt_get_policy_ex_arg {
745 __u64 policy_size; /* input/output */
748 struct fscrypt_policy_v1 v1;
749 struct fscrypt_policy_v2 v2;
750 } policy; /* output */
753 The caller must initialize ``policy_size`` to the size available for
754 the policy struct, i.e. ``sizeof(arg.policy)``.
756 On success, the policy struct is returned in ``policy``, and its
757 actual size is returned in ``policy_size``. ``policy.version`` should
758 be checked to determine the version of policy returned. Note that the
759 version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
761 FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:
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
776 Note: if you only need to know whether a file is encrypted or not, on
777 most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
778 and check for FS_ENCRYPT_FL, or to use the statx() system call and
779 check for STATX_ATTR_ENCRYPTED in stx_attributes.
781 FS_IOC_GET_ENCRYPTION_POLICY
782 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
784 The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
785 encryption policy, if any, for a directory or regular file. However,
786 unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
787 FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
788 version. It takes in a pointer directly to struct fscrypt_policy_v1
789 rather than struct fscrypt_get_policy_ex_arg.
791 The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
792 for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
793 FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
794 encrypted using a newer encryption policy version.
796 Getting the per-filesystem salt
797 -------------------------------
799 Some filesystems, such as ext4 and F2FS, also support the deprecated
800 ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly
801 generated 16-byte value stored in the filesystem superblock. This
802 value is intended to used as a salt when deriving an encryption key
803 from a passphrase or other low-entropy user credential.
805 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to
806 generate and manage any needed salt(s) in userspace.
808 Getting a file's encryption nonce
809 ---------------------------------
811 Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported.
812 On encrypted files and directories it gets the inode's 16-byte nonce.
813 On unencrypted files and directories, it fails with ENODATA.
815 This ioctl can be useful for automated tests which verify that the
816 encryption is being done correctly. It is not needed for normal use
822 FS_IOC_ADD_ENCRYPTION_KEY
823 ~~~~~~~~~~~~~~~~~~~~~~~~~
825 The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
826 the filesystem, making all files on the filesystem which were
827 encrypted using that key appear "unlocked", i.e. in plaintext form.
828 It can be executed on any file or directory on the target filesystem,
829 but using the filesystem's root directory is recommended. It takes in
830 a pointer to struct fscrypt_add_key_arg, defined as follows::
832 struct fscrypt_add_key_arg {
833 struct fscrypt_key_specifier key_spec;
840 #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1
841 #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2
843 struct fscrypt_key_specifier {
844 __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */
847 __u8 __reserved[32]; /* reserve some extra space */
848 __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
849 __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
853 struct fscrypt_provisioning_key_payload {
859 struct fscrypt_add_key_arg must be zeroed, then initialized
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.
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``).
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.
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
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.
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.
902 For v2 policy keys, the kernel keeps track of which user (identified
903 by effective user ID) added the key, and only allows the key to be
904 removed by that user --- or by "root", if they use
905 `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
907 However, if another user has added the key, it may be desirable to
908 prevent that other user from unexpectedly removing it. Therefore,
909 FS_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,
911 FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
912 current user, rather than actually add the key again (but the raw key
913 must still be provided, as a proof of knowledge).
915 FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
916 the key was either added or already exists.
918 FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:
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
926 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
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
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
940 For v1 encryption policies, a master encryption key can also be
941 provided by adding it to a process-subscribed keyring, e.g. to a
942 session keyring, or to a user keyring if the user keyring is linked
943 into the session keyring.
945 This method is deprecated (and not supported for v2 encryption
946 policies) for several reasons. First, it cannot be used in
947 combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
948 so for removing a key a workaround such as keyctl_unlink() in
949 combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would
950 have to be used. Second, it doesn't match the fact that the
951 locked/unlocked status of encrypted files (i.e. whether they appear to
952 be in plaintext form or in ciphertext form) is global. This mismatch
953 has caused much confusion as well as real problems when processes
954 running under different UIDs, such as a ``sudo`` command, need to
955 access encrypted files.
957 Nevertheless, to add a key to one of the process-subscribed keyrings,
958 the 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
961 read back by userspace. The key description must be "fscrypt:"
962 followed by the 16-character lower case hex representation of the
963 ``master_key_descriptor`` that was set in the encryption policy. The
964 key payload must conform to the following structure::
966 #define FSCRYPT_MAX_KEY_SIZE 64
970 __u8 raw[FSCRYPT_MAX_KEY_SIZE];
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
976 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
978 The key description prefix "fscrypt:" may alternatively be replaced
979 with a filesystem-specific prefix such as "ext4:". However, the
980 filesystem-specific prefixes are deprecated and should not be used in
986 Two ioctls are available for removing a key that was added by
987 `FS_IOC_ADD_ENCRYPTION_KEY`_:
989 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
990 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
992 These two ioctls differ only in cases where v2 policy keys are added
993 or removed by non-root users.
995 These ioctls don't work on keys that were added via the legacy
996 process-subscribed keyrings mechanism.
998 Before using these ioctls, read the `Kernel memory compromise`_
999 section for a discussion of the security goals and limitations of
1002 FS_IOC_REMOVE_ENCRYPTION_KEY
1003 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1005 The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
1006 encryption key from the filesystem, and possibly removes the key
1007 itself. It can be executed on any file or directory on the target
1008 filesystem, but using the filesystem's root directory is recommended.
1009 It takes in a pointer to struct fscrypt_remove_key_arg, defined
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];
1020 This structure must be zeroed, then initialized as follows:
1022 - The key to remove is specified by ``key_spec``:
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.
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``.
1034 For v2 policy keys, this ioctl is usable by non-root users. However,
1035 to make this possible, it actually just removes the current user's
1036 claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
1037 Only after all claims are removed is the key really removed.
1039 For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000,
1040 then the key will be "claimed" by uid 1000, and
1041 FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if
1042 both uids 1000 and 2000 added the key, then for each uid
1043 FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only
1044 once *both* are removed is the key really removed. (Think of it like
1045 unlinking a file that may have hard links.)
1047 If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
1048 try to "lock" all files that had been unlocked with the key. It won't
1049 lock files that are still in-use, so this ioctl is expected to be used
1050 in cooperation with userspace ensuring that none of the files are
1051 still open. However, if necessary, this ioctl can be executed again
1052 later to retry locking any remaining files.
1054 FS_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
1056 the key was removed, or the key was already removed but had files
1057 remaining to be the locked so the ioctl retried locking them. In any
1058 of these cases, ``removal_status_flags`` is filled in with the
1059 following informational status flags:
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
1067 FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:
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
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
1082 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
1083 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1085 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
1086 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
1087 ALL_USERS version of the ioctl will remove all users' claims to the
1088 key, not just the current user's. I.e., the key itself will always be
1089 removed, no matter how many users have added it. This difference is
1090 only meaningful if non-root users are adding and removing keys.
1092 Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires
1093 "root", namely the CAP_SYS_ADMIN capability in the initial user
1094 namespace. Otherwise it will fail with EACCES.
1099 FS_IOC_GET_ENCRYPTION_KEY_STATUS
1100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1102 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
1103 master encryption key. It can be executed on any file or directory on
1104 the target filesystem, but using the filesystem's root directory is
1105 recommended. It takes in a pointer to
1106 struct fscrypt_get_key_status_arg, defined as follows::
1108 struct fscrypt_get_key_status_arg {
1110 struct fscrypt_key_specifier key_spec;
1111 __u32 __reserved[6];
1114 #define FSCRYPT_KEY_STATUS_ABSENT 1
1115 #define FSCRYPT_KEY_STATUS_PRESENT 2
1116 #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3
1118 #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001
1121 __u32 __out_reserved[13];
1124 The caller must zero all input fields, then fill in ``key_spec``:
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``.
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``.
1134 On success, 0 is returned and the kernel fills in the output fields:
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.
1142 - ``status_flags`` can contain the following flags:
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``.
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
1152 FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:
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
1160 Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful
1161 for determining whether the key for a given encrypted directory needs
1162 to be added before prompting the user for the passphrase needed to
1165 FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
1166 the filesystem-level keyring, i.e. the keyring managed by
1167 `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It
1168 cannot get the status of a key that has only been added for use by v1
1169 encryption policies using the legacy mechanism involving
1170 process-subscribed keyrings.
1178 With the encryption key, encrypted regular files, directories, and
1179 symlinks behave very similarly to their unencrypted counterparts ---
1180 after all, the encryption is intended to be transparent. However,
1181 astute users may notice some differences in behavior:
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.
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.
1198 - Direct I/O is supported on encrypted files only under some
1199 circumstances. For details, see `Direct I/O support`_.
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.
1205 - Online defragmentation of encrypted files is not supported. The
1206 EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
1209 - The ext4 filesystem does not support data journaling with encrypted
1210 regular files. It will fall back to ordered data mode instead.
1212 - DAX (Direct Access) is not supported on encrypted files.
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).
1220 Note that mmap *is* supported. This is possible because the pagecache
1221 for an encrypted file contains the plaintext, not the ciphertext.
1226 Some filesystem operations may be performed on encrypted regular
1227 files, directories, and symlinks even before their encryption key has
1228 been added, or after their encryption key has been removed:
1230 - File metadata may be read, e.g. using stat().
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.
1240 The ``.`` and ``..`` directory entries are special. They are always
1241 present and are not encrypted or encoded.
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
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.
1252 Without the key, regular files cannot be opened or truncated.
1253 Attempts to do so will fail with ENOKEY. This implies that any
1254 regular file operations that require a file descriptor, such as
1255 read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
1257 Also without the key, files of any type (including directories) cannot
1258 be created or linked into an encrypted directory, nor can a name in an
1259 encrypted directory be the source or target of a rename, nor can an
1260 O_TMPFILE temporary file be created in an encrypted directory. All
1261 such operations will fail with ENOKEY.
1263 It is not currently possible to backup and restore encrypted files
1264 without the encryption key. This would require special APIs which
1265 have not yet been implemented.
1267 Encryption policy enforcement
1268 =============================
1270 After an encryption policy has been set on a directory, all regular
1271 files, directories, and symbolic links created in that directory
1272 (recursively) will inherit that encryption policy. Special files ---
1273 that is, named pipes, device nodes, and UNIX domain sockets --- will
1276 Except for those special files, it is forbidden to have unencrypted
1277 files, or files encrypted with a different encryption policy, in an
1278 encrypted directory tree. Attempts to link or rename such a file into
1279 an encrypted directory will fail with EXDEV. This is also enforced
1280 during ->lookup() to provide limited protection against offline
1281 attacks that try to disable or downgrade encryption in known locations
1282 where applications may later write sensitive data. It is recommended
1283 that systems implementing a form of "verified boot" take advantage of
1284 this by validating all top-level encryption policies prior to access.
1286 Inline encryption support
1287 =========================
1289 By default, fscrypt uses the kernel crypto API for all cryptographic
1290 operations (other than HKDF, which fscrypt partially implements
1291 itself). The kernel crypto API supports hardware crypto accelerators,
1292 but only ones that work in the traditional way where all inputs and
1293 outputs (e.g. plaintexts and ciphertexts) are in memory. fscrypt can
1294 take advantage of such hardware, but the traditional acceleration
1295 model isn't particularly efficient and fscrypt hasn't been optimized
1298 Instead, many newer systems (especially mobile SoCs) have *inline
1299 encryption hardware* that can encrypt/decrypt data while it is on its
1300 way to/from the storage device. Linux supports inline encryption
1301 through a set of extensions to the block layer called *blk-crypto*.
1302 blk-crypto allows filesystems to attach encryption contexts to bios
1303 (I/O requests) to specify how the data will be encrypted or decrypted
1304 in-line. For more information about blk-crypto, see
1305 :ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1307 On supported filesystems (currently ext4 and f2fs), fscrypt can use
1308 blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1309 contents. To enable this, set CONFIG_FS_ENCRYPTION_INLINE_CRYPT=y in
1310 the kernel configuration, and specify the "inlinecrypt" mount option
1311 when mounting the filesystem.
1313 Note that the "inlinecrypt" mount option just specifies to use inline
1314 encryption when possible; it doesn't force its use. fscrypt will
1315 still fall back to using the kernel crypto API on files where the
1316 inline encryption hardware doesn't have the needed crypto capabilities
1317 (e.g. support for the needed encryption algorithm and data unit size)
1318 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1319 to be usable, it must be enabled in the kernel configuration with
1320 CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y.)
1322 Currently fscrypt always uses the filesystem block size (which is
1323 usually 4096 bytes) as the data unit size. Therefore, it can only use
1324 inline encryption hardware that supports that data unit size.
1326 Inline encryption doesn't affect the ciphertext or other aspects of
1327 the on-disk format, so users may freely switch back and forth between
1328 using "inlinecrypt" and not using "inlinecrypt".
1333 For direct I/O on an encrypted file to work, the following conditions
1334 must be met (in addition to the conditions for direct I/O on an
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`_.
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.
1348 If either of the above conditions is not met, then direct I/O on the
1349 encrypted file will fall back to buffered I/O.
1351 Implementation details
1352 ======================
1357 An encryption policy is represented on-disk by
1358 struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to
1359 individual filesystems to decide where to store it, but normally it
1360 would be stored in a hidden extended attribute. It should *not* be
1361 exposed by the xattr-related system calls such as getxattr() and
1362 setxattr() because of the special semantics of the encryption xattr.
1363 (In particular, there would be much confusion if an encryption policy
1364 were to be added to or removed from anything other than an empty
1365 directory.) These structs are defined as follows::
1367 #define FSCRYPT_FILE_NONCE_SIZE 16
1369 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
1370 struct fscrypt_context_v1 {
1372 u8 contents_encryption_mode;
1373 u8 filenames_encryption_mode;
1375 u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
1376 u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
1379 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
1380 struct fscrypt_context_v2 {
1382 u8 contents_encryption_mode;
1383 u8 filenames_encryption_mode;
1385 u8 log2_data_unit_size;
1387 u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
1388 u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
1391 The context structs contain the same information as the corresponding
1392 policy structs (see `Setting an encryption policy`_), except that the
1393 context structs also contain a nonce. The nonce is randomly generated
1394 by the kernel and is used as KDF input or as a tweak to cause
1395 different files to be encrypted differently; see `Per-file encryption
1396 keys`_ and `DIRECT_KEY policies`_.
1401 When inline encryption is used, filesystems just need to associate
1402 encryption contexts with bios to specify how the block layer or the
1403 inline encryption hardware will encrypt/decrypt the file contents.
1405 When inline encryption isn't used, filesystems must encrypt/decrypt
1406 the file contents themselves, as described below:
1408 For the read path (->read_folio()) of regular files, filesystems can
1409 read the ciphertext into the page cache and decrypt it in-place. The
1410 folio lock must be held until decryption has finished, to prevent the
1411 folio from becoming visible to userspace prematurely.
1413 For the write path (->writepage()) of regular files, filesystems
1414 cannot encrypt data in-place in the page cache, since the cached
1415 plaintext must be preserved. Instead, filesystems must encrypt into a
1416 temporary buffer or "bounce page", then write out the temporary
1417 buffer. Some filesystems, such as UBIFS, already use temporary
1418 buffers regardless of encryption. Other filesystems, such as ext4 and
1419 F2FS, have to allocate bounce pages specially for encryption.
1421 Filename hashing and encoding
1422 -----------------------------
1424 Modern filesystems accelerate directory lookups by using indexed
1425 directories. An indexed directory is organized as a tree keyed by
1426 filename hashes. When a ->lookup() is requested, the filesystem
1427 normally hashes the filename being looked up so that it can quickly
1428 find the corresponding directory entry, if any.
1430 With encryption, lookups must be supported and efficient both with and
1431 without the encryption key. Clearly, it would not work to hash the
1432 plaintext filenames, since the plaintext filenames are unavailable
1433 without the key. (Hashing the plaintext filenames would also make it
1434 impossible for the filesystem's fsck tool to optimize encrypted
1435 directories.) Instead, filesystems hash the ciphertext filenames,
1436 i.e. the bytes actually stored on-disk in the directory entries. When
1437 asked to do a ->lookup() with the key, the filesystem just encrypts
1438 the user-supplied name to get the ciphertext.
1440 Lookups without the key are more complicated. The raw ciphertext may
1441 contain the ``\0`` and ``/`` characters, which are illegal in
1442 filenames. Therefore, readdir() must base64url-encode the ciphertext
1443 for presentation. For most filenames, this works fine; on ->lookup(),
1444 the filesystem just base64url-decodes the user-supplied name to get
1445 back to the raw ciphertext.
1447 However, for very long filenames, base64url encoding would cause the
1448 filename length to exceed NAME_MAX. To prevent this, readdir()
1449 actually presents long filenames in an abbreviated form which encodes
1450 a strong "hash" of the ciphertext filename, along with the optional
1451 filesystem-specific hash(es) needed for directory lookups. This
1452 allows the filesystem to still, with a high degree of confidence, map
1453 the filename given in ->lookup() back to a particular directory entry
1454 that was previously listed by readdir(). See
1455 struct fscrypt_nokey_name in the source for more details.
1457 Note that the precise way that filenames are presented to userspace
1458 without the key is subject to change in the future. It is only meant
1459 as a way to temporarily present valid filenames so that commands like
1460 ``rm -r`` work as expected on encrypted directories.
1465 To test fscrypt, use xfstests, which is Linux's de facto standard
1466 filesystem test suite. First, run all the tests in the "encrypt"
1467 group on the relevant filesystem(s). One can also run the tests
1468 with the 'inlinecrypt' mount option to test the implementation for
1469 inline encryption support. For example, to test ext4 and
1470 f2fs encryption using `kvm-xfstests
1471 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1473 kvm-xfstests -c ext4,f2fs -g encrypt
1474 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1476 UBIFS encryption can also be tested this way, but it should be done in
1477 a separate command, and it takes some time for kvm-xfstests to set up
1478 emulated UBI volumes::
1480 kvm-xfstests -c ubifs -g encrypt
1482 No tests should fail. However, tests that use non-default encryption
1483 modes (e.g. generic/549 and generic/550) will be skipped if the needed
1484 algorithms were not built into the kernel's crypto API. Also, tests
1485 that access the raw block device (e.g. generic/399, generic/548,
1486 generic/549, generic/550) will be skipped on UBIFS.
1488 Besides running the "encrypt" group tests, for ext4 and f2fs it's also
1489 possible to run most xfstests with the "test_dummy_encryption" mount
1490 option. This option causes all new files to be automatically
1491 encrypted with a dummy key, without having to make any API calls.
1492 This tests the encrypted I/O paths more thoroughly. To do this with
1493 kvm-xfstests, use the "encrypt" filesystem configuration::
1495 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1496 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1498 Because this runs many more tests than "-g encrypt" does, it takes
1499 much longer to run; so also consider using `gce-xfstests
1500 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1501 instead of kvm-xfstests::
1503 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1504 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt