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, and
35 UBIFS. This allows encrypted files to be read and written without
36 caching both the decrypted and encrypted pages in the pagecache,
37 thereby nearly halving the memory used and bringing it in line with
38 unencrypted files. Similarly, half as many dentries and inodes are
39 needed. eCryptfs also limits encrypted filenames to 143 bytes,
40 causing application compatibility issues; fscrypt allows the full 255
41 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be
42 used by unprivileged users, with no need to mount anything.
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 are. If a vulnerable algorithm is used,
81 such as a table-based implementation of AES, it may be possible for an
82 attacker to mount a side channel attack against the online system.
83 Side channel attacks may also be mounted against applications
84 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 key length needed by the contents and filenames
180 encryption modes being used. For example, if AES-256-XTS is used for
181 contents encryption, the master key must be 64 bytes (512 bits). Note
182 that the XTS mode is defined to require a key twice as long as that
183 required by the underlying block cipher.
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 logical block number
265 and a 16-byte per-file nonce. Also, the overhead of each Adiantum key
266 is 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 or eMMC standards, which support only 64 IV
296 bits per I/O request and may have only a small number of keyslots.
301 For master keys used for v2 encryption policies, a unique 16-byte "key
302 identifier" is also derived using the KDF. This value is stored in
303 the clear, since it is needed to reliably identify the key itself.
308 For directories that are indexed using a secret-keyed dirhash over the
309 plaintext filenames, the KDF is also used to derive a 128-bit
310 SipHash-2-4 key per directory in order to hash filenames. This works
311 just like deriving a per-file encryption key, except that a different
312 KDF context is used. Currently, only casefolded ("case-insensitive")
313 encrypted directories use this style of hashing.
315 Encryption modes and usage
316 ==========================
318 fscrypt allows one encryption mode to be specified for file contents
319 and one encryption mode to be specified for filenames. Different
320 directory trees are permitted to use different encryption modes.
321 Currently, the following pairs of encryption modes are supported:
323 - AES-256-XTS for contents and AES-256-CTS-CBC for filenames
324 - AES-128-CBC for contents and AES-128-CTS-CBC for filenames
325 - Adiantum for both contents and filenames
327 If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
329 AES-128-CBC was added only for low-powered embedded devices with
330 crypto accelerators such as CAAM or CESA that do not support XTS. To
331 use AES-128-CBC, CONFIG_CRYPTO_ESSIV and CONFIG_CRYPTO_SHA256 (or
332 another SHA-256 implementation) must be enabled so that ESSIV can be
335 Adiantum is a (primarily) stream cipher-based mode that is fast even
336 on CPUs without dedicated crypto instructions. It's also a true
337 wide-block mode, unlike XTS. It can also eliminate the need to derive
338 per-file encryption keys. However, it depends on the security of two
339 primitives, XChaCha12 and AES-256, rather than just one. See the
340 paper "Adiantum: length-preserving encryption for entry-level
341 processors" (https://eprint.iacr.org/2018/720.pdf) for more details.
342 To use Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast
343 implementations of ChaCha and NHPoly1305 should be enabled, e.g.
344 CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM.
346 New encryption modes can be added relatively easily, without changes
347 to individual filesystems. However, authenticated encryption (AE)
348 modes are not currently supported because of the difficulty of dealing
349 with ciphertext expansion.
354 For file contents, each filesystem block is encrypted independently.
355 Starting from Linux kernel 5.5, encryption of filesystems with block
356 size less than system's page size is supported.
358 Each block's IV is set to the logical block number within the file as
359 a little endian number, except that:
361 - With CBC mode encryption, ESSIV is also used. Specifically, each IV
362 is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
363 of the file's data encryption key.
365 - With `DIRECT_KEY policies`_, the file's nonce is appended to the IV.
366 Currently this is only allowed with the Adiantum encryption mode.
368 - With `IV_INO_LBLK_64 policies`_, the logical block number is limited
369 to 32 bits and is placed in bits 0-31 of the IV. The inode number
370 (which is also limited to 32 bits) is placed in bits 32-63.
372 Note that because file logical block numbers are included in the IVs,
373 filesystems must enforce that blocks are never shifted around within
374 encrypted files, e.g. via "collapse range" or "insert range".
379 For filenames, each full filename is encrypted at once. Because of
380 the requirements to retain support for efficient directory lookups and
381 filenames of up to 255 bytes, the same IV is used for every filename
384 However, each encrypted directory still uses a unique key, or
385 alternatively has the file's nonce (for `DIRECT_KEY policies`_) or
386 inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs.
387 Thus, IV reuse is limited to within a single directory.
389 With CTS-CBC, the IV reuse means that when the plaintext filenames
390 share a common prefix at least as long as the cipher block size (16
391 bytes for AES), the corresponding encrypted filenames will also share
392 a common prefix. This is undesirable. Adiantum does not have this
393 weakness, as it is a wide-block encryption mode.
395 All supported filenames encryption modes accept any plaintext length
396 >= 16 bytes; cipher block alignment is not required. However,
397 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
398 being encrypted. In addition, to reduce leakage of filename lengths
399 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
400 16, or 32-byte boundary (configurable). 32 is recommended since this
401 provides the best confidentiality, at the cost of making directory
402 entries consume slightly more space. Note that since NUL (``\0``) is
403 not otherwise a valid character in filenames, the padding will never
404 produce duplicate plaintexts.
406 Symbolic link targets are considered a type of filename and are
407 encrypted in the same way as filenames in directory entries, except
408 that IV reuse is not a problem as each symlink has its own inode.
413 Setting an encryption policy
414 ----------------------------
416 FS_IOC_SET_ENCRYPTION_POLICY
417 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
419 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
420 empty directory or verifies that a directory or regular file already
421 has the specified encryption policy. It takes in a pointer to a
422 :c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
423 fscrypt_policy_v2`, defined as follows::
425 #define FSCRYPT_POLICY_V1 0
426 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
427 struct fscrypt_policy_v1 {
429 __u8 contents_encryption_mode;
430 __u8 filenames_encryption_mode;
432 __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
434 #define fscrypt_policy fscrypt_policy_v1
436 #define FSCRYPT_POLICY_V2 2
437 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
438 struct fscrypt_policy_v2 {
440 __u8 contents_encryption_mode;
441 __u8 filenames_encryption_mode;
444 __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
447 This structure must be initialized as follows:
449 - ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is
450 :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct
451 is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original
452 policy version as "v1", though its version code is really 0.) For
453 new encrypted directories, use v2 policies.
455 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
456 be set to constants from ``<linux/fscrypt.h>`` which identify the
457 encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS
458 (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
459 (4) for ``filenames_encryption_mode``.
461 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
463 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
464 encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32
466 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
467 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
468 policies`_. This is mutually exclusive with DIRECT_KEY and is not
469 supported on v1 policies.
471 - For v2 encryption policies, ``__reserved`` must be zeroed.
473 - For v1 encryption policies, ``master_key_descriptor`` specifies how
474 to find the master key in a keyring; see `Adding keys`_. It is up
475 to userspace to choose a unique ``master_key_descriptor`` for each
476 master key. The e4crypt and fscrypt tools use the first 8 bytes of
477 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
478 required. Also, the master key need not be in the keyring yet when
479 FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added
480 before any files can be created in the encrypted directory.
482 For v2 encryption policies, ``master_key_descriptor`` has been
483 replaced with ``master_key_identifier``, which is longer and cannot
484 be arbitrarily chosen. Instead, the key must first be added using
485 `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
486 the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
487 be used as the ``master_key_identifier`` in the :c:type:`struct
490 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
491 verifies that the file is an empty directory. If so, the specified
492 encryption policy is assigned to the directory, turning it into an
493 encrypted directory. After that, and after providing the
494 corresponding master key as described in `Adding keys`_, all regular
495 files, directories (recursively), and symlinks created in the
496 directory will be encrypted, inheriting the same encryption policy.
497 The filenames in the directory's entries will be encrypted as well.
499 Alternatively, if the file is already encrypted, then
500 FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
501 policy exactly matches the actual one. If they match, then the ioctl
502 returns 0. Otherwise, it fails with EEXIST. This works on both
503 regular files and directories, including nonempty directories.
505 When a v2 encryption policy is assigned to a directory, it is also
506 required that either the specified key has been added by the current
507 user or that the caller has CAP_FOWNER in the initial user namespace.
508 (This is needed to prevent a user from encrypting their data with
509 another user's key.) The key must remain added while
510 FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new
511 encrypted directory does not need to be accessed immediately, then the
512 key can be removed right away afterwards.
514 Note that the ext4 filesystem does not allow the root directory to be
515 encrypted, even if it is empty. Users who want to encrypt an entire
516 filesystem with one key should consider using dm-crypt instead.
518 FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
520 - ``EACCES``: the file is not owned by the process's uid, nor does the
521 process have the CAP_FOWNER capability in a namespace with the file
523 - ``EEXIST``: the file is already encrypted with an encryption policy
524 different from the one specified
525 - ``EINVAL``: an invalid encryption policy was specified (invalid
526 version, mode(s), or flags; or reserved bits were set); or a v1
527 encryption policy was specified but the directory has the casefold
528 flag enabled (casefolding is incompatible with v1 policies).
529 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
530 the specified ``master_key_identifier`` has not been added, nor does
531 the process have the CAP_FOWNER capability in the initial user
533 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
535 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
536 - ``ENOTTY``: this type of filesystem does not implement encryption
537 - ``EOPNOTSUPP``: the kernel was not configured with encryption
538 support for filesystems, or the filesystem superblock has not
539 had encryption enabled on it. (For example, to use encryption on an
540 ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the
541 kernel config, and the superblock must have had the "encrypt"
542 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
544 - ``EPERM``: this directory may not be encrypted, e.g. because it is
545 the root directory of an ext4 filesystem
546 - ``EROFS``: the filesystem is readonly
548 Getting an encryption policy
549 ----------------------------
551 Two ioctls are available to get a file's encryption policy:
553 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
554 - `FS_IOC_GET_ENCRYPTION_POLICY`_
556 The extended (_EX) version of the ioctl is more general and is
557 recommended to use when possible. However, on older kernels only the
558 original ioctl is available. Applications should try the extended
559 version, and if it fails with ENOTTY fall back to the original
562 FS_IOC_GET_ENCRYPTION_POLICY_EX
563 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
565 The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
566 policy, if any, for a directory or regular file. No additional
567 permissions are required beyond the ability to open the file. It
568 takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
571 struct fscrypt_get_policy_ex_arg {
572 __u64 policy_size; /* input/output */
575 struct fscrypt_policy_v1 v1;
576 struct fscrypt_policy_v2 v2;
577 } policy; /* output */
580 The caller must initialize ``policy_size`` to the size available for
581 the policy struct, i.e. ``sizeof(arg.policy)``.
583 On success, the policy struct is returned in ``policy``, and its
584 actual size is returned in ``policy_size``. ``policy.version`` should
585 be checked to determine the version of policy returned. Note that the
586 version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
588 FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:
590 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
591 encryption policy version
592 - ``ENODATA``: the file is not encrypted
593 - ``ENOTTY``: this type of filesystem does not implement encryption,
594 or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
595 (try FS_IOC_GET_ENCRYPTION_POLICY instead)
596 - ``EOPNOTSUPP``: the kernel was not configured with encryption
597 support for this filesystem, or the filesystem superblock has not
598 had encryption enabled on it
599 - ``EOVERFLOW``: the file is encrypted and uses a recognized
600 encryption policy version, but the policy struct does not fit into
603 Note: if you only need to know whether a file is encrypted or not, on
604 most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
605 and check for FS_ENCRYPT_FL, or to use the statx() system call and
606 check for STATX_ATTR_ENCRYPTED in stx_attributes.
608 FS_IOC_GET_ENCRYPTION_POLICY
609 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
611 The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
612 encryption policy, if any, for a directory or regular file. However,
613 unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
614 FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
615 version. It takes in a pointer directly to a :c:type:`struct
616 fscrypt_policy_v1` rather than a :c:type:`struct
617 fscrypt_get_policy_ex_arg`.
619 The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
620 for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
621 FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
622 encrypted using a newer encryption policy version.
624 Getting the per-filesystem salt
625 -------------------------------
627 Some filesystems, such as ext4 and F2FS, also support the deprecated
628 ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly
629 generated 16-byte value stored in the filesystem superblock. This
630 value is intended to used as a salt when deriving an encryption key
631 from a passphrase or other low-entropy user credential.
633 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to
634 generate and manage any needed salt(s) in userspace.
639 FS_IOC_ADD_ENCRYPTION_KEY
640 ~~~~~~~~~~~~~~~~~~~~~~~~~
642 The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
643 the filesystem, making all files on the filesystem which were
644 encrypted using that key appear "unlocked", i.e. in plaintext form.
645 It can be executed on any file or directory on the target filesystem,
646 but using the filesystem's root directory is recommended. It takes in
647 a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
650 struct fscrypt_add_key_arg {
651 struct fscrypt_key_specifier key_spec;
658 #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1
659 #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2
661 struct fscrypt_key_specifier {
662 __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */
665 __u8 __reserved[32]; /* reserve some extra space */
666 __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
667 __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
671 struct fscrypt_provisioning_key_payload {
677 :c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
680 - If the key is being added for use by v1 encryption policies, then
681 ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
682 ``key_spec.u.descriptor`` must contain the descriptor of the key
683 being added, corresponding to the value in the
684 ``master_key_descriptor`` field of :c:type:`struct
685 fscrypt_policy_v1`. To add this type of key, the calling process
686 must have the CAP_SYS_ADMIN capability in the initial user
689 Alternatively, if the key is being added for use by v2 encryption
690 policies, then ``key_spec.type`` must contain
691 FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is
692 an *output* field which the kernel fills in with a cryptographic
693 hash of the key. To add this type of key, the calling process does
694 not need any privileges. However, the number of keys that can be
695 added is limited by the user's quota for the keyrings service (see
696 ``Documentation/security/keys/core.rst``).
698 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
699 Alternatively, if ``key_id`` is nonzero, this field must be 0, since
700 in that case the size is implied by the specified Linux keyring key.
702 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
703 field. Otherwise ``key_id`` is the ID of a Linux keyring key of
704 type "fscrypt-provisioning" whose payload is a :c:type:`struct
705 fscrypt_provisioning_key_payload` whose ``raw`` field contains the
706 raw key and whose ``type`` field matches ``key_spec.type``. Since
707 ``raw`` is variable-length, the total size of this key's payload
708 must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the
709 raw key size. The process must have Search permission on this key.
711 Most users should leave this 0 and specify the raw key directly.
712 The support for specifying a Linux keyring key is intended mainly to
713 allow re-adding keys after a filesystem is unmounted and re-mounted,
714 without having to store the raw keys in userspace memory.
716 - ``raw`` is a variable-length field which must contain the actual
717 key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is
718 nonzero, then this field is unused.
720 For v2 policy keys, the kernel keeps track of which user (identified
721 by effective user ID) added the key, and only allows the key to be
722 removed by that user --- or by "root", if they use
723 `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
725 However, if another user has added the key, it may be desirable to
726 prevent that other user from unexpectedly removing it. Therefore,
727 FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
728 *again*, even if it's already added by other user(s). In this case,
729 FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
730 current user, rather than actually add the key again (but the raw key
731 must still be provided, as a proof of knowledge).
733 FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
734 the key was either added or already exists.
736 FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:
738 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
739 caller does not have the CAP_SYS_ADMIN capability in the initial
740 user namespace; or the raw key was specified by Linux key ID but the
741 process lacks Search permission on the key.
742 - ``EDQUOT``: the key quota for this user would be exceeded by adding
744 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
746 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
747 key has the wrong type
748 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
750 - ``ENOTTY``: this type of filesystem does not implement encryption
751 - ``EOPNOTSUPP``: the kernel was not configured with encryption
752 support for this filesystem, or the filesystem superblock has not
753 had encryption enabled on it
758 For v1 encryption policies, a master encryption key can also be
759 provided by adding it to a process-subscribed keyring, e.g. to a
760 session keyring, or to a user keyring if the user keyring is linked
761 into the session keyring.
763 This method is deprecated (and not supported for v2 encryption
764 policies) for several reasons. First, it cannot be used in
765 combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
766 so for removing a key a workaround such as keyctl_unlink() in
767 combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would
768 have to be used. Second, it doesn't match the fact that the
769 locked/unlocked status of encrypted files (i.e. whether they appear to
770 be in plaintext form or in ciphertext form) is global. This mismatch
771 has caused much confusion as well as real problems when processes
772 running under different UIDs, such as a ``sudo`` command, need to
773 access encrypted files.
775 Nevertheless, to add a key to one of the process-subscribed keyrings,
776 the add_key() system call can be used (see:
777 ``Documentation/security/keys/core.rst``). The key type must be
778 "logon"; keys of this type are kept in kernel memory and cannot be
779 read back by userspace. The key description must be "fscrypt:"
780 followed by the 16-character lower case hex representation of the
781 ``master_key_descriptor`` that was set in the encryption policy. The
782 key payload must conform to the following structure::
784 #define FSCRYPT_MAX_KEY_SIZE 64
788 __u8 raw[FSCRYPT_MAX_KEY_SIZE];
792 ``mode`` is ignored; just set it to 0. The actual key is provided in
793 ``raw`` with ``size`` indicating its size in bytes. That is, the
794 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
796 The key description prefix "fscrypt:" may alternatively be replaced
797 with a filesystem-specific prefix such as "ext4:". However, the
798 filesystem-specific prefixes are deprecated and should not be used in
804 Two ioctls are available for removing a key that was added by
805 `FS_IOC_ADD_ENCRYPTION_KEY`_:
807 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
808 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
810 These two ioctls differ only in cases where v2 policy keys are added
811 or removed by non-root users.
813 These ioctls don't work on keys that were added via the legacy
814 process-subscribed keyrings mechanism.
816 Before using these ioctls, read the `Kernel memory compromise`_
817 section for a discussion of the security goals and limitations of
820 FS_IOC_REMOVE_ENCRYPTION_KEY
821 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
823 The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
824 encryption key from the filesystem, and possibly removes the key
825 itself. It can be executed on any file or directory on the target
826 filesystem, but using the filesystem's root directory is recommended.
827 It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
830 struct fscrypt_remove_key_arg {
831 struct fscrypt_key_specifier key_spec;
832 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001
833 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002
834 __u32 removal_status_flags; /* output */
838 This structure must be zeroed, then initialized as follows:
840 - The key to remove is specified by ``key_spec``:
842 - To remove a key used by v1 encryption policies, set
843 ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
844 in ``key_spec.u.descriptor``. To remove this type of key, the
845 calling process must have the CAP_SYS_ADMIN capability in the
846 initial user namespace.
848 - To remove a key used by v2 encryption policies, set
849 ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
850 in ``key_spec.u.identifier``.
852 For v2 policy keys, this ioctl is usable by non-root users. However,
853 to make this possible, it actually just removes the current user's
854 claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
855 Only after all claims are removed is the key really removed.
857 For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000,
858 then the key will be "claimed" by uid 1000, and
859 FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if
860 both uids 1000 and 2000 added the key, then for each uid
861 FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only
862 once *both* are removed is the key really removed. (Think of it like
863 unlinking a file that may have hard links.)
865 If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
866 try to "lock" all files that had been unlocked with the key. It won't
867 lock files that are still in-use, so this ioctl is expected to be used
868 in cooperation with userspace ensuring that none of the files are
869 still open. However, if necessary, this ioctl can be executed again
870 later to retry locking any remaining files.
872 FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed
873 (but may still have files remaining to be locked), the user's claim to
874 the key was removed, or the key was already removed but had files
875 remaining to be the locked so the ioctl retried locking them. In any
876 of these cases, ``removal_status_flags`` is filled in with the
877 following informational status flags:
879 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
880 are still in-use. Not guaranteed to be set in the case where only
881 the user's claim to the key was removed.
882 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
883 user's claim to the key was removed, not the key itself
885 FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:
887 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
888 was specified, but the caller does not have the CAP_SYS_ADMIN
889 capability in the initial user namespace
890 - ``EINVAL``: invalid key specifier type, or reserved bits were set
891 - ``ENOKEY``: the key object was not found at all, i.e. it was never
892 added in the first place or was already fully removed including all
893 files locked; or, the user does not have a claim to the key (but
895 - ``ENOTTY``: this type of filesystem does not implement encryption
896 - ``EOPNOTSUPP``: the kernel was not configured with encryption
897 support for this filesystem, or the filesystem superblock has not
898 had encryption enabled on it
900 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
901 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
903 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
904 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
905 ALL_USERS version of the ioctl will remove all users' claims to the
906 key, not just the current user's. I.e., the key itself will always be
907 removed, no matter how many users have added it. This difference is
908 only meaningful if non-root users are adding and removing keys.
910 Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires
911 "root", namely the CAP_SYS_ADMIN capability in the initial user
912 namespace. Otherwise it will fail with EACCES.
917 FS_IOC_GET_ENCRYPTION_KEY_STATUS
918 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
920 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
921 master encryption key. It can be executed on any file or directory on
922 the target filesystem, but using the filesystem's root directory is
923 recommended. It takes in a pointer to a :c:type:`struct
924 fscrypt_get_key_status_arg`, defined as follows::
926 struct fscrypt_get_key_status_arg {
928 struct fscrypt_key_specifier key_spec;
932 #define FSCRYPT_KEY_STATUS_ABSENT 1
933 #define FSCRYPT_KEY_STATUS_PRESENT 2
934 #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3
936 #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001
939 __u32 __out_reserved[13];
942 The caller must zero all input fields, then fill in ``key_spec``:
944 - To get the status of a key for v1 encryption policies, set
945 ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
946 in ``key_spec.u.descriptor``.
948 - To get the status of a key for v2 encryption policies, set
949 ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
950 in ``key_spec.u.identifier``.
952 On success, 0 is returned and the kernel fills in the output fields:
954 - ``status`` indicates whether the key is absent, present, or
955 incompletely removed. Incompletely removed means that the master
956 secret has been removed, but some files are still in use; i.e.,
957 `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational
958 status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.
960 - ``status_flags`` can contain the following flags:
962 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
963 has added by the current user. This is only set for keys
964 identified by ``identifier`` rather than by ``descriptor``.
966 - ``user_count`` specifies the number of users who have added the key.
967 This is only set for keys identified by ``identifier`` rather than
970 FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:
972 - ``EINVAL``: invalid key specifier type, or reserved bits were set
973 - ``ENOTTY``: this type of filesystem does not implement encryption
974 - ``EOPNOTSUPP``: the kernel was not configured with encryption
975 support for this filesystem, or the filesystem superblock has not
976 had encryption enabled on it
978 Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful
979 for determining whether the key for a given encrypted directory needs
980 to be added before prompting the user for the passphrase needed to
983 FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
984 the filesystem-level keyring, i.e. the keyring managed by
985 `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It
986 cannot get the status of a key that has only been added for use by v1
987 encryption policies using the legacy mechanism involving
988 process-subscribed keyrings.
996 With the encryption key, encrypted regular files, directories, and
997 symlinks behave very similarly to their unencrypted counterparts ---
998 after all, the encryption is intended to be transparent. However,
999 astute users may notice some differences in behavior:
1001 - Unencrypted files, or files encrypted with a different encryption
1002 policy (i.e. different key, modes, or flags), cannot be renamed or
1003 linked into an encrypted directory; see `Encryption policy
1004 enforcement`_. Attempts to do so will fail with EXDEV. However,
1005 encrypted files can be renamed within an encrypted directory, or
1006 into an unencrypted directory.
1008 Note: "moving" an unencrypted file into an encrypted directory, e.g.
1009 with the `mv` program, is implemented in userspace by a copy
1010 followed by a delete. Be aware that the original unencrypted data
1011 may remain recoverable from free space on the disk; prefer to keep
1012 all files encrypted from the very beginning. The `shred` program
1013 may be used to overwrite the source files but isn't guaranteed to be
1014 effective on all filesystems and storage devices.
1016 - Direct I/O is not supported on encrypted files. Attempts to use
1017 direct I/O on such files will fall back to buffered I/O.
1019 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1020 FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will
1021 fail with EOPNOTSUPP.
1023 - Online defragmentation of encrypted files is not supported. The
1024 EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
1027 - The ext4 filesystem does not support data journaling with encrypted
1028 regular files. It will fall back to ordered data mode instead.
1030 - DAX (Direct Access) is not supported on encrypted files.
1032 - The st_size of an encrypted symlink will not necessarily give the
1033 length of the symlink target as required by POSIX. It will actually
1034 give the length of the ciphertext, which will be slightly longer
1035 than the plaintext due to NUL-padding and an extra 2-byte overhead.
1037 - The maximum length of an encrypted symlink is 2 bytes shorter than
1038 the maximum length of an unencrypted symlink. For example, on an
1039 EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
1040 to 4095 bytes long, while encrypted symlinks can only be up to 4093
1041 bytes long (both lengths excluding the terminating null).
1043 Note that mmap *is* supported. This is possible because the pagecache
1044 for an encrypted file contains the plaintext, not the ciphertext.
1049 Some filesystem operations may be performed on encrypted regular
1050 files, directories, and symlinks even before their encryption key has
1051 been added, or after their encryption key has been removed:
1053 - File metadata may be read, e.g. using stat().
1055 - Directories may be listed, in which case the filenames will be
1056 listed in an encoded form derived from their ciphertext. The
1057 current encoding algorithm is described in `Filename hashing and
1058 encoding`_. The algorithm is subject to change, but it is
1059 guaranteed that the presented filenames will be no longer than
1060 NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
1061 will uniquely identify directory entries.
1063 The ``.`` and ``..`` directory entries are special. They are always
1064 present and are not encrypted or encoded.
1066 - Files may be deleted. That is, nondirectory files may be deleted
1067 with unlink() as usual, and empty directories may be deleted with
1068 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
1071 - Symlink targets may be read and followed, but they will be presented
1072 in encrypted form, similar to filenames in directories. Hence, they
1073 are unlikely to point to anywhere useful.
1075 Without the key, regular files cannot be opened or truncated.
1076 Attempts to do so will fail with ENOKEY. This implies that any
1077 regular file operations that require a file descriptor, such as
1078 read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
1080 Also without the key, files of any type (including directories) cannot
1081 be created or linked into an encrypted directory, nor can a name in an
1082 encrypted directory be the source or target of a rename, nor can an
1083 O_TMPFILE temporary file be created in an encrypted directory. All
1084 such operations will fail with ENOKEY.
1086 It is not currently possible to backup and restore encrypted files
1087 without the encryption key. This would require special APIs which
1088 have not yet been implemented.
1090 Encryption policy enforcement
1091 =============================
1093 After an encryption policy has been set on a directory, all regular
1094 files, directories, and symbolic links created in that directory
1095 (recursively) will inherit that encryption policy. Special files ---
1096 that is, named pipes, device nodes, and UNIX domain sockets --- will
1099 Except for those special files, it is forbidden to have unencrypted
1100 files, or files encrypted with a different encryption policy, in an
1101 encrypted directory tree. Attempts to link or rename such a file into
1102 an encrypted directory will fail with EXDEV. This is also enforced
1103 during ->lookup() to provide limited protection against offline
1104 attacks that try to disable or downgrade encryption in known locations
1105 where applications may later write sensitive data. It is recommended
1106 that systems implementing a form of "verified boot" take advantage of
1107 this by validating all top-level encryption policies prior to access.
1109 Implementation details
1110 ======================
1115 An encryption policy is represented on-disk by a :c:type:`struct
1116 fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is
1117 up to individual filesystems to decide where to store it, but normally
1118 it would be stored in a hidden extended attribute. It should *not* be
1119 exposed by the xattr-related system calls such as getxattr() and
1120 setxattr() because of the special semantics of the encryption xattr.
1121 (In particular, there would be much confusion if an encryption policy
1122 were to be added to or removed from anything other than an empty
1123 directory.) These structs are defined as follows::
1125 #define FS_KEY_DERIVATION_NONCE_SIZE 16
1127 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
1128 struct fscrypt_context_v1 {
1130 u8 contents_encryption_mode;
1131 u8 filenames_encryption_mode;
1133 u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
1134 u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
1137 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
1138 struct fscrypt_context_v2 {
1140 u8 contents_encryption_mode;
1141 u8 filenames_encryption_mode;
1144 u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
1145 u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
1148 The context structs contain the same information as the corresponding
1149 policy structs (see `Setting an encryption policy`_), except that the
1150 context structs also contain a nonce. The nonce is randomly generated
1151 by the kernel and is used as KDF input or as a tweak to cause
1152 different files to be encrypted differently; see `Per-file encryption
1153 keys`_ and `DIRECT_KEY policies`_.
1158 For the read path (->readpage()) of regular files, filesystems can
1159 read the ciphertext into the page cache and decrypt it in-place. The
1160 page lock must be held until decryption has finished, to prevent the
1161 page from becoming visible to userspace prematurely.
1163 For the write path (->writepage()) of regular files, filesystems
1164 cannot encrypt data in-place in the page cache, since the cached
1165 plaintext must be preserved. Instead, filesystems must encrypt into a
1166 temporary buffer or "bounce page", then write out the temporary
1167 buffer. Some filesystems, such as UBIFS, already use temporary
1168 buffers regardless of encryption. Other filesystems, such as ext4 and
1169 F2FS, have to allocate bounce pages specially for encryption.
1171 Filename hashing and encoding
1172 -----------------------------
1174 Modern filesystems accelerate directory lookups by using indexed
1175 directories. An indexed directory is organized as a tree keyed by
1176 filename hashes. When a ->lookup() is requested, the filesystem
1177 normally hashes the filename being looked up so that it can quickly
1178 find the corresponding directory entry, if any.
1180 With encryption, lookups must be supported and efficient both with and
1181 without the encryption key. Clearly, it would not work to hash the
1182 plaintext filenames, since the plaintext filenames are unavailable
1183 without the key. (Hashing the plaintext filenames would also make it
1184 impossible for the filesystem's fsck tool to optimize encrypted
1185 directories.) Instead, filesystems hash the ciphertext filenames,
1186 i.e. the bytes actually stored on-disk in the directory entries. When
1187 asked to do a ->lookup() with the key, the filesystem just encrypts
1188 the user-supplied name to get the ciphertext.
1190 Lookups without the key are more complicated. The raw ciphertext may
1191 contain the ``\0`` and ``/`` characters, which are illegal in
1192 filenames. Therefore, readdir() must base64-encode the ciphertext for
1193 presentation. For most filenames, this works fine; on ->lookup(), the
1194 filesystem just base64-decodes the user-supplied name to get back to
1197 However, for very long filenames, base64 encoding would cause the
1198 filename length to exceed NAME_MAX. To prevent this, readdir()
1199 actually presents long filenames in an abbreviated form which encodes
1200 a strong "hash" of the ciphertext filename, along with the optional
1201 filesystem-specific hash(es) needed for directory lookups. This
1202 allows the filesystem to still, with a high degree of confidence, map
1203 the filename given in ->lookup() back to a particular directory entry
1204 that was previously listed by readdir(). See :c:type:`struct
1205 fscrypt_nokey_name` in the source for more details.
1207 Note that the precise way that filenames are presented to userspace
1208 without the key is subject to change in the future. It is only meant
1209 as a way to temporarily present valid filenames so that commands like
1210 ``rm -r`` work as expected on encrypted directories.
1215 To test fscrypt, use xfstests, which is Linux's de facto standard
1216 filesystem test suite. First, run all the tests in the "encrypt"
1217 group on the relevant filesystem(s). For example, to test ext4 and
1218 f2fs encryption using `kvm-xfstests
1219 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1221 kvm-xfstests -c ext4,f2fs -g encrypt
1223 UBIFS encryption can also be tested this way, but it should be done in
1224 a separate command, and it takes some time for kvm-xfstests to set up
1225 emulated UBI volumes::
1227 kvm-xfstests -c ubifs -g encrypt
1229 No tests should fail. However, tests that use non-default encryption
1230 modes (e.g. generic/549 and generic/550) will be skipped if the needed
1231 algorithms were not built into the kernel's crypto API. Also, tests
1232 that access the raw block device (e.g. generic/399, generic/548,
1233 generic/549, generic/550) will be skipped on UBIFS.
1235 Besides running the "encrypt" group tests, for ext4 and f2fs it's also
1236 possible to run most xfstests with the "test_dummy_encryption" mount
1237 option. This option causes all new files to be automatically
1238 encrypted with a dummy key, without having to make any API calls.
1239 This tests the encrypted I/O paths more thoroughly. To do this with
1240 kvm-xfstests, use the "encrypt" filesystem configuration::
1242 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1244 Because this runs many more tests than "-g encrypt" does, it takes
1245 much longer to run; so also consider using `gce-xfstests
1246 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1247 instead of kvm-xfstests::
1249 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto