1 =====================================
2 Filesystem-level encryption (fscrypt)
3 =====================================
4
5 Introduction
6 ============
7
8 fscrypt is a library which filesystems can hoo
9 transparent encryption of files and directorie
10
11 Note: "fscrypt" in this document refers to the
12 implemented in ``fs/crypto/``, as opposed to t
13 `fscrypt <https://github.com/google/fscrypt>`_
14 covers the kernel-level portion. For command-
15 use encryption, see the documentation for the
16 <https://github.com/google/fscrypt>`_. Also,
17 the fscrypt userspace tool, or other existing
18 `fscryptctl <https://github.com/google/fscrypt
19 management system
20 <https://source.android.com/security/encryptio
21 using the kernel's API directly. Using existi
22 chance of introducing your own security bugs.
23 completeness this documentation covers the ker
24
25 Unlike dm-crypt, fscrypt operates at the files
26 at the block device level. This allows it to
27 with different keys and to have unencrypted fi
28 filesystem. This is useful for multi-user sys
29 data-at-rest needs to be cryptographically iso
30 However, except for filenames, fscrypt does no
31 metadata.
32
33 Unlike eCryptfs, which is a stacked filesystem
34 directly into supported filesystems --- curren
35 and CephFS. This allows encrypted files to be
36 without caching both the decrypted and encrypt
37 pagecache, thereby nearly halving the memory u
38 line with unencrypted files. Similarly, half
39 inodes are needed. eCryptfs also limits encry
40 bytes, causing application compatibility issue
41 full 255 bytes (NAME_MAX). Finally, unlike eC
42 can be used by unprivileged users, with no nee
43
44 fscrypt does not support encrypting files in-p
45 supports marking an empty directory as encrypt
46 userspace provides the key, all regular files,
47 symbolic links created in that directory tree
48 encrypted.
49
50 Threat model
51 ============
52
53 Offline attacks
54 ---------------
55
56 Provided that userspace chooses a strong encry
57 protects the confidentiality of file contents
58 event of a single point-in-time permanent offl
59 block device content. fscrypt does not protec
60 non-filename metadata, e.g. file sizes, file p
61 timestamps, and extended attributes. Also, th
62 of holes (unallocated blocks which logically c
63 files is not protected.
64
65 fscrypt is not guaranteed to protect confident
66 if an attacker is able to manipulate the files
67 an authorized user later accessing the filesys
68
69 Online attacks
70 --------------
71
72 fscrypt (and storage encryption in general) ca
73 protection, if any at all, against online atta
74
75 Side-channel attacks
76 ~~~~~~~~~~~~~~~~~~~~
77
78 fscrypt is only resistant to side-channel atta
79 electromagnetic attacks, to the extent that th
80 Cryptographic API algorithms or inline encrypt
81 vulnerable algorithm is used, such as a table-
82 AES, it may be possible for an attacker to mou
83 against the online system. Side channel attac
84 against applications consuming decrypted data.
85
86 Unauthorized file access
87 ~~~~~~~~~~~~~~~~~~~~~~~~
88
89 After an encryption key has been added, fscryp
90 plaintext file contents or filenames from othe
91 system. Instead, existing access control mech
92 bits, POSIX ACLs, LSMs, or namespaces should b
93
94 (For the reasoning behind this, understand tha
95 added, the confidentiality of the data, from t
96 system itself, is *not* protected by the mathe
97 encryption but rather only by the correctness
98 Therefore, any encryption-specific access cont
99 be enforced by kernel *code* and therefore wou
100 with the wide variety of access control mechan
101
102 Kernel memory compromise
103 ~~~~~~~~~~~~~~~~~~~~~~~~
104
105 An attacker who compromises the system enough
106 memory, e.g. by mounting a physical attack or
107 security vulnerability, can compromise all enc
108 currently in use.
109
110 However, fscrypt allows encryption keys to be
111 which may protect them from later compromise.
112
113 In more detail, the FS_IOC_REMOVE_ENCRYPTION_K
114 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl)
115 encryption key from kernel memory. If it does
116 evict all cached inodes which had been "unlock
117 thereby wiping their per-file keys and making
118 "locked", i.e. in ciphertext or encrypted form
119
120 However, these ioctls have some limitations:
121
122 - Per-file keys for in-use files will *not* be
123 Therefore, for maximum effect, userspace sho
124 encrypted files and directories before remov
125 well as kill any processes whose working dir
126 encrypted directory.
127
128 - The kernel cannot magically wipe copies of t
129 userspace might have as well. Therefore, us
130 copies of the master key(s) it makes as well
131 be done immediately after FS_IOC_ADD_ENCRYPT
132 for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally
133 to all higher levels in the key hierarchy.
134 follow other security precautions such as ml
135 containing keys to prevent it from being swa
136
137 - In general, decrypted contents and filenames
138 caches are freed but not wiped. Therefore,
139 recoverable from freed memory, even after th
140 were wiped. To partially solve this, you ca
141 CONFIG_PAGE_POISONING=y in your kernel confi
142 to your kernel command line. However, this
143
144 - Secret keys might still exist in CPU registe
145 accelerator hardware (if used by the crypto
146 the algorithms), or in other places not expl
147
148 Limitations of v1 policies
149 ~~~~~~~~~~~~~~~~~~~~~~~~~~
150
151 v1 encryption policies have some weaknesses wi
152 attacks:
153
154 - There is no verification that the provided m
155 Therefore, a malicious user can temporarily
156 with another user's encrypted files to which
157 access. Because of filesystem caching, the
158 used by the other user's accesses to those f
159 user has the correct key in their own keyrin
160 meaning of "read-only access".
161
162 - A compromise of a per-file key also compromi
163 which it was derived.
164
165 - Non-root users cannot securely remove encryp
166
167 All the above problems are fixed with v2 encry
168 this reason among others, it is recommended to
169 policies on all new encrypted directories.
170
171 Key hierarchy
172 =============
173
174 Master Keys
175 -----------
176
177 Each encrypted directory tree is protected by
178 keys can be up to 64 bytes long, and must be a
179 greater of the security strength of the conten
180 encryption modes being used. For example, if
181 used, the master key must be at least 256 bits
182 stricter requirement applies if the key is use
183 policy and AES-256-XTS is used; such keys must
184
185 To "unlock" an encrypted directory tree, users
186 appropriate master key. There can be any numb
187 of which protects any number of directory tree
188 filesystems.
189
190 Master keys must be real cryptographic keys, i
191 from random bytestrings of the same length. T
192 **must not** directly use a password as a mast
193 shorter key, or repeat a shorter key. Securit
194 if userspace makes any such error, as the cryp
195 analysis would no longer apply.
196
197 Instead, users should generate master keys eit
198 cryptographically secure random number generat
199 (Key Derivation Function). The kernel does no
200 therefore, if userspace derives the key from a
201 as a passphrase, it is critical that a KDF des
202 be used, such as scrypt, PBKDF2, or Argon2.
203
204 Key derivation function
205 -----------------------
206
207 With one exception, fscrypt never uses the mas
208 encryption directly. Instead, they are only u
209 (Key Derivation Function) to derive the actual
210
211 The KDF used for a particular master key diffe
212 the key is used for v1 encryption policies or
213 policies. Users **must not** use the same key
214 encryption policies. (No real-world attack is
215 specific case of key reuse, but its security c
216 since the cryptographic proofs and analysis wo
217
218 For v1 encryption policies, the KDF only suppo
219 encryption keys. It works by encrypting the m
220 AES-128-ECB, using the file's 16-byte nonce as
221 resulting ciphertext is used as the derived ke
222 longer than needed, then it is truncated to th
223
224 For v2 encryption policies, the KDF is HKDF-SH
225 passed as the "input keying material", no salt
226 "application-specific information string" is u
227 key to be derived. For example, when a per-fi
228 derived, the application-specific information
229 nonce prefixed with "fscrypt\\0" and a context
230 context bytes are used for other types of deri
231
232 HKDF-SHA512 is preferred to the original AES-1
233 HKDF is more flexible, is nonreversible, and e
234 entropy from the master key. HKDF is also sta
235 used by other software, whereas the AES-128-EC
236
237 Per-file encryption keys
238 ------------------------
239
240 Since each master key can protect many files,
241 "tweak" the encryption of each file so that th
242 files doesn't map to the same ciphertext, or v
243 cases, fscrypt does this by deriving per-file
244 encrypted inode (regular file, directory, or s
245 fscrypt randomly generates a 16-byte nonce and
246 inode's encryption xattr. Then, it uses a KDF
247 derivation function`_) to derive the file's ke
248 and nonce.
249
250 Key derivation was chosen over key wrapping be
251 require larger xattrs which would be less like
252 filesystem's inode table, and there didn't app
253 significant advantages to key wrapping. In pa
254 there is no requirement to support unlocking a
255 alternative master keys or to support rotating
256 the master keys may be wrapped in userspace, e
257 `fscrypt <https://github.com/google/fscrypt>`_
258
259 DIRECT_KEY policies
260 -------------------
261
262 The Adiantum encryption mode (see `Encryption
263 suitable for both contents and filenames encry
264 long IVs --- long enough to hold both an 8-byt
265 16-byte per-file nonce. Also, the overhead of
266 greater than that of an AES-256-XTS key.
267
268 Therefore, to improve performance and save mem
269 "direct key" configuration is supported. When
270 this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY
271 per-file encryption keys are not used. Instea
272 (contents or filenames) is encrypted, the file
273 included in the IV. Moreover:
274
275 - For v1 encryption policies, the encryption i
276 master key. Because of this, users **must n
277 key for any other purpose, even for other v1
278
279 - For v2 encryption policies, the encryption i
280 key derived using the KDF. Users may use th
281 other v2 encryption policies.
282
283 IV_INO_LBLK_64 policies
284 -----------------------
285
286 When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set
287 the encryption keys are derived from the maste
288 number, and filesystem UUID. This normally re
289 protected by the same master key sharing a sin
290 key and a single filenames encryption key. To
291 files' data differently, inode numbers are inc
292 Consequently, shrinking the filesystem may not
293
294 This format is optimized for use with inline e
295 compliant with the UFS standard, which support
296 I/O request and may have only a small number o
297
298 IV_INO_LBLK_32 policies
299 -----------------------
300
301 IV_INO_LBLK_32 policies work like IV_INO_LBLK_
302 IV_INO_LBLK_32, the inode number is hashed wit
303 SipHash key is derived from the master key) an
304 unit index mod 2^32 to produce a 32-bit IV.
305
306 This format is optimized for use with inline e
307 compliant with the eMMC v5.2 standard, which s
308 per I/O request and may have only a small numb
309 format results in some level of IV reuse, so i
310 when necessary due to hardware limitations.
311
312 Key identifiers
313 ---------------
314
315 For master keys used for v2 encryption policie
316 identifier" is also derived using the KDF. Th
317 the clear, since it is needed to reliably iden
318
319 Dirhash keys
320 ------------
321
322 For directories that are indexed using a secre
323 plaintext filenames, the KDF is also used to d
324 SipHash-2-4 key per directory in order to hash
325 just like deriving a per-file encryption key,
326 KDF context is used. Currently, only casefold
327 encrypted directories use this style of hashin
328
329 Encryption modes and usage
330 ==========================
331
332 fscrypt allows one encryption mode to be speci
333 and one encryption mode to be specified for fi
334 directory trees are permitted to use different
335
336 Supported modes
337 ---------------
338
339 Currently, the following pairs of encryption m
340
341 - AES-256-XTS for contents and AES-256-CBC-CTS
342 - AES-256-XTS for contents and AES-256-HCTR2 f
343 - Adiantum for both contents and filenames
344 - AES-128-CBC-ESSIV for contents and AES-128-C
345 - SM4-XTS for contents and SM4-CBC-CTS for fil
346
347 Note: in the API, "CBC" means CBC-ESSIV, and "
348 So, for example, FSCRYPT_MODE_AES_256_CTS mean
349
350 Authenticated encryption modes are not current
351 the difficulty of dealing with ciphertext expa
352 contents encryption uses a block cipher in `XT
353 <https://en.wikipedia.org/wiki/Disk_encryption
354 `CBC-ESSIV mode
355 <https://en.wikipedia.org/wiki/Disk_encryption
356 or a wide-block cipher. Filenames encryption
357 block cipher in `CBC-CTS mode
358 <https://en.wikipedia.org/wiki/Ciphertext_stea
359 cipher.
360
361 The (AES-256-XTS, AES-256-CBC-CTS) pair is the
362 It is also the only option that is *guaranteed
363 if the kernel supports fscrypt at all; see `Ke
364
365 The (AES-256-XTS, AES-256-HCTR2) pair is also
366 upgrades the filenames encryption to use a wid
367 *wide-block cipher*, also called a tweakable s
368 permutation, has the property that changing on
369 entire result.) As described in `Filenames en
370 cipher is the ideal mode for the problem domai
371 "least bad" choice among the alternatives. Fo
372 HCTR2, see `the HCTR2 paper <https://eprint.ia
373
374 Adiantum is recommended on systems where AES i
375 of hardware acceleration for AES. Adiantum is
376 that uses XChaCha12 and AES-256 as its underly
377 the work is done by XChaCha12, which is much f
378 acceleration is unavailable. For more informa
379 `the Adiantum paper <https://eprint.iacr.org/2
380
381 The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair
382 systems whose only form of AES acceleration is
383 accelerator such as CAAM or CESA that does not
384
385 The remaining mode pairs are the "national pri
386
387 - (SM4-XTS, SM4-CBC-CTS)
388
389 Generally speaking, these ciphers aren't "bad"
390 receive limited security review compared to th
391 AES and ChaCha. They also don't bring much ne
392 suggested to only use these ciphers where thei
393
394 Kernel config options
395 ---------------------
396
397 Enabling fscrypt support (CONFIG_FS_ENCRYPTION
398 only the basic support from the crypto API nee
399 and AES-256-CBC-CTS encryption. For optimal p
400 strongly recommended to also enable any availa
401 kconfig options that provide acceleration for
402 wish to use. Support for any "non-default" en
403 requires extra kconfig options as well.
404
405 Below, some relevant options are listed by enc
406 acceleration options not listed below may be a
407 platform; refer to the kconfig menus. File co
408 also be configured to use inline encryption ha
409 kernel crypto API (see `Inline encryption supp
410 the file contents mode doesn't need to support
411 API, but the filenames mode still does.
412
413 - AES-256-XTS and AES-256-CBC-CTS
414 - Recommended:
415 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BL
416 - x86: CONFIG_CRYPTO_AES_NI_INTEL
417
418 - AES-256-HCTR2
419 - Mandatory:
420 - CONFIG_CRYPTO_HCTR2
421 - Recommended:
422 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BL
423 - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_C
424 - x86: CONFIG_CRYPTO_AES_NI_INTEL
425 - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI
426
427 - Adiantum
428 - Mandatory:
429 - CONFIG_CRYPTO_ADIANTUM
430 - Recommended:
431 - arm32: CONFIG_CRYPTO_CHACHA20_NEON
432 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
433 - arm64: CONFIG_CRYPTO_CHACHA20_NEON
434 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
435 - x86: CONFIG_CRYPTO_CHACHA20_X86_64
436 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
437 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
438
439 - AES-128-CBC-ESSIV and AES-128-CBC-CTS:
440 - Mandatory:
441 - CONFIG_CRYPTO_ESSIV
442 - CONFIG_CRYPTO_SHA256 or another SHA-
443 - Recommended:
444 - AES-CBC acceleration
445
446 fscrypt also uses HMAC-SHA512 for key derivati
447 acceleration is recommended:
448
449 - SHA-512
450 - Recommended:
451 - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
452 - x86: CONFIG_CRYPTO_SHA512_SSSE3
453
454 Contents encryption
455 -------------------
456
457 For contents encryption, each file's contents
458 units". Each data unit is encrypted independe
459 data unit incorporates the zero-based index of
460 the file. This ensures that each data unit wi
461 differently, which is essential to prevent lea
462
463 Note: the encryption depending on the offset i
464 operations like "collapse range" and "insert r
465 extent mapping of files are not supported on e
466
467 There are two cases for the sizes of the data
468
469 * Fixed-size data units. This is how all file
470 work. A file's data units are all the same
471 is zero-padded if needed. By default, the d
472 to the filesystem block size. On some files
473 a sub-block data unit size via the ``log2_da
474 the encryption policy; see `FS_IOC_SET_ENCRY
475
476 * Variable-size data units. This is what UBIF
477 data node" is treated as a crypto data unit.
478 length, possibly compressed data, zero-padde
479 boundary. Users cannot select a sub-block d
480
481 In the case of compression + encryption, the c
482 encrypted. UBIFS compression works as describ
483 compression works a bit differently; it compre
484 filesystem blocks into a smaller number of fil
485 Therefore a f2fs-compressed file still uses fi
486 it is encrypted in a similar way to a file con
487
488 As mentioned in `Key hierarchy`_, the default
489 per-file keys. In this case, the IV for each
490 index of the data unit in the file. However,
491 encryption setting that does not use per-file
492 kind of file identifier is incorporated into t
493
494 - With `DIRECT_KEY policies`_, the data unit i
495 0-63 of the IV, and the file's nonce is plac
496
497 - With `IV_INO_LBLK_64 policies`_, the data un
498 bits 0-31 of the IV, and the file's inode nu
499 32-63. This setting is only allowed when da
500 inode numbers fit in 32 bits.
501
502 - With `IV_INO_LBLK_32 policies`_, the file's
503 and added to the data unit index. The resul
504 to 32 bits and placed in bits 0-31 of the IV
505 allowed when data unit indices and inode num
506
507 The byte order of the IV is always little endi
508
509 If the user selects FSCRYPT_MODE_AES_128_CBC f
510 ESSIV layer is automatically included. In thi
511 passed to AES-128-CBC, it is encrypted with AE
512 key is the SHA-256 hash of the file's contents
513
514 Filenames encryption
515 --------------------
516
517 For filenames, each full filename is encrypted
518 the requirements to retain support for efficie
519 filenames of up to 255 bytes, the same IV is u
520 in a directory.
521
522 However, each encrypted directory still uses a
523 alternatively has the file's nonce (for `DIREC
524 inode number (for `IV_INO_LBLK_64 policies`_)
525 Thus, IV reuse is limited to within a single d
526
527 With CBC-CTS, the IV reuse means that when the
528 common prefix at least as long as the cipher b
529 corresponding encrypted filenames will also sh
530 undesirable. Adiantum and HCTR2 do not have t
531 wide-block encryption modes.
532
533 All supported filenames encryption modes accep
534 >= 16 bytes; cipher block alignment is not req
535 filenames shorter than 16 bytes are NUL-padded
536 being encrypted. In addition, to reduce leaka
537 via their ciphertexts, all filenames are NUL-p
538 16, or 32-byte boundary (configurable). 32 is
539 provides the best confidentiality, at the cost
540 entries consume slightly more space. Note tha
541 not otherwise a valid character in filenames,
542 produce duplicate plaintexts.
543
544 Symbolic link targets are considered a type of
545 encrypted in the same way as filenames in dire
546 that IV reuse is not a problem as each symlink
547
548 User API
549 ========
550
551 Setting an encryption policy
552 ----------------------------
553
554 FS_IOC_SET_ENCRYPTION_POLICY
555 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
556
557 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an
558 empty directory or verifies that a directory o
559 has the specified encryption policy. It takes
560 struct fscrypt_policy_v1 or struct fscrypt_pol
561 follows::
562
563 #define FSCRYPT_POLICY_V1 0
564 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
565 struct fscrypt_policy_v1 {
566 __u8 version;
567 __u8 contents_encryption_mode;
568 __u8 filenames_encryption_mode;
569 __u8 flags;
570 __u8 master_key_descriptor[FSCRYPT
571 };
572 #define fscrypt_policy fscrypt_policy_v1
573
574 #define FSCRYPT_POLICY_V2 2
575 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
576 struct fscrypt_policy_v2 {
577 __u8 version;
578 __u8 contents_encryption_mode;
579 __u8 filenames_encryption_mode;
580 __u8 flags;
581 __u8 log2_data_unit_size;
582 __u8 __reserved[3];
583 __u8 master_key_identifier[FSCRYPT
584 };
585
586 This structure must be initialized as follows:
587
588 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
589 struct fscrypt_policy_v1 is used or FSCRYPT_
590 struct fscrypt_policy_v2 is used. (Note: we
591 policy version as "v1", though its version c
592 For new encrypted directories, use v2 polici
593
594 - ``contents_encryption_mode`` and ``filenames
595 be set to constants from ``<linux/fscrypt.h>
596 encryption modes to use. If unsure, use FSC
597 (1) for ``contents_encryption_mode`` and FSC
598 (4) for ``filenames_encryption_mode``. For
599 modes and usage`_.
600
601 v1 encryption policies only support three co
602 (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_
603 (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_
604 (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTU
605 all combinations documented in `Supported mo
606
607 - ``flags`` contains optional flags from ``<li
608
609 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of
610 encrypting filenames. If unsure, use FSCR
611 (0x3).
612 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIREC
613 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `I
614 policies`_.
615 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `I
616 policies`_.
617
618 v1 encryption policies only support the PAD_
619 The other flags are only supported by v2 enc
620
621 The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_L
622 mutually exclusive.
623
624 - ``log2_data_unit_size`` is the log2 of the d
625 or 0 to select the default data unit size.
626 the granularity of file contents encryption.
627 ``log2_data_unit_size`` to 12 causes file co
628 underlying encryption algorithm (such as AES
629 data units, each with its own IV.
630
631 Not all filesystems support setting ``log2_d
632 and f2fs support it since Linux v6.7. On fi
633 it, the supported nonzero values are 9 throu
634 filesystem block size, inclusively. The def
635 the filesystem block size.
636
637 The main use case for ``log2_data_unit_size`
638 data unit size smaller than the filesystem b
639 compatibility with inline encryption hardwar
640 smaller data unit sizes. ``/sys/block/$disk
641 useful for checking which data unit sizes ar
642 particular system's inline encryption hardwa
643
644 Leave this field zeroed unless you are certa
645 an unnecessarily small data unit size reduce
646
647 - For v2 encryption policies, ``__reserved`` m
648
649 - For v1 encryption policies, ``master_key_des
650 to find the master key in a keyring; see `Ad
651 to userspace to choose a unique ``master_key
652 master key. The e4crypt and fscrypt tools u
653 ``SHA-512(SHA-512(master_key))``, but this p
654 required. Also, the master key need not be
655 FS_IOC_SET_ENCRYPTION_POLICY is executed. H
656 before any files can be created in the encry
657
658 For v2 encryption policies, ``master_key_des
659 replaced with ``master_key_identifier``, whi
660 be arbitrarily chosen. Instead, the key mus
661 `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``k
662 the kernel returned in the struct fscrypt_ad
663 be used as the ``master_key_identifier`` in
664 struct fscrypt_policy_v2.
665
666 If the file is not yet encrypted, then FS_IOC_
667 verifies that the file is an empty directory.
668 encryption policy is assigned to the directory
669 encrypted directory. After that, and after pr
670 corresponding master key as described in `Addi
671 files, directories (recursively), and symlinks
672 directory will be encrypted, inheriting the sa
673 The filenames in the directory's entries will
674
675 Alternatively, if the file is already encrypte
676 FS_IOC_SET_ENCRYPTION_POLICY validates that th
677 policy exactly matches the actual one. If the
678 returns 0. Otherwise, it fails with EEXIST.
679 regular files and directories, including nonem
680
681 When a v2 encryption policy is assigned to a d
682 required that either the specified key has bee
683 user or that the caller has CAP_FOWNER in the
684 (This is needed to prevent a user from encrypt
685 another user's key.) The key must remain adde
686 FS_IOC_SET_ENCRYPTION_POLICY is executing. Ho
687 encrypted directory does not need to be access
688 key can be removed right away afterwards.
689
690 Note that the ext4 filesystem does not allow t
691 encrypted, even if it is empty. Users who wan
692 filesystem with one key should consider using
693
694 FS_IOC_SET_ENCRYPTION_POLICY can fail with the
695
696 - ``EACCES``: the file is not owned by the pro
697 process have the CAP_FOWNER capability in a
698 owner's uid mapped
699 - ``EEXIST``: the file is already encrypted wi
700 different from the one specified
701 - ``EINVAL``: an invalid encryption policy was
702 version, mode(s), or flags; or reserved bits
703 encryption policy was specified but the dire
704 flag enabled (casefolding is incompatible wi
705 - ``ENOKEY``: a v2 encryption policy was speci
706 the specified ``master_key_identifier`` has
707 the process have the CAP_FOWNER capability i
708 namespace
709 - ``ENOTDIR``: the file is unencrypted and is
710 directory
711 - ``ENOTEMPTY``: the file is unencrypted and i
712 - ``ENOTTY``: this type of filesystem does not
713 - ``EOPNOTSUPP``: the kernel was not configure
714 support for filesystems, or the filesystem s
715 had encryption enabled on it. (For example,
716 ext4 filesystem, CONFIG_FS_ENCRYPTION must b
717 kernel config, and the superblock must have
718 feature flag enabled using ``tune2fs -O encr
719 encrypt``.)
720 - ``EPERM``: this directory may not be encrypt
721 the root directory of an ext4 filesystem
722 - ``EROFS``: the filesystem is readonly
723
724 Getting an encryption policy
725 ----------------------------
726
727 Two ioctls are available to get a file's encry
728
729 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
730 - `FS_IOC_GET_ENCRYPTION_POLICY`_
731
732 The extended (_EX) version of the ioctl is mor
733 recommended to use when possible. However, on
734 original ioctl is available. Applications sho
735 version, and if it fails with ENOTTY fall back
736 version.
737
738 FS_IOC_GET_ENCRYPTION_POLICY_EX
739 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
740
741 The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retr
742 policy, if any, for a directory or regular fil
743 permissions are required beyond the ability to
744 takes in a pointer to struct fscrypt_get_polic
745 defined as follows::
746
747 struct fscrypt_get_policy_ex_arg {
748 __u64 policy_size; /* input/output
749 union {
750 __u8 version;
751 struct fscrypt_policy_v1 v
752 struct fscrypt_policy_v2 v
753 } policy; /* output */
754 };
755
756 The caller must initialize ``policy_size`` to
757 the policy struct, i.e. ``sizeof(arg.policy)``
758
759 On success, the policy struct is returned in `
760 actual size is returned in ``policy_size``. `
761 be checked to determine the version of policy
762 version code for the "v1" policy is actually 0
763
764 FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with
765
766 - ``EINVAL``: the file is encrypted, but it us
767 encryption policy version
768 - ``ENODATA``: the file is not encrypted
769 - ``ENOTTY``: this type of filesystem does not
770 or this kernel is too old to support FS_IOC_
771 (try FS_IOC_GET_ENCRYPTION_POLICY instead)
772 - ``EOPNOTSUPP``: the kernel was not configure
773 support for this filesystem, or the filesyst
774 had encryption enabled on it
775 - ``EOVERFLOW``: the file is encrypted and use
776 encryption policy version, but the policy st
777 the provided buffer
778
779 Note: if you only need to know whether a file
780 most filesystems it is also possible to use th
781 and check for FS_ENCRYPT_FL, or to use the sta
782 check for STATX_ATTR_ENCRYPTED in stx_attribut
783
784 FS_IOC_GET_ENCRYPTION_POLICY
785 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
786
787 The FS_IOC_GET_ENCRYPTION_POLICY ioctl can als
788 encryption policy, if any, for a directory or
789 unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
790 FS_IOC_GET_ENCRYPTION_POLICY only supports the
791 version. It takes in a pointer directly to st
792 rather than struct fscrypt_get_policy_ex_arg.
793
794 The error codes for FS_IOC_GET_ENCRYPTION_POLI
795 for FS_IOC_GET_ENCRYPTION_POLICY_EX, except th
796 FS_IOC_GET_ENCRYPTION_POLICY also returns ``EI
797 encrypted using a newer encryption policy vers
798
799 Getting the per-filesystem salt
800 -------------------------------
801
802 Some filesystems, such as ext4 and F2FS, also
803 ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioct
804 generated 16-byte value stored in the filesyst
805 value is intended to used as a salt when deriv
806 from a passphrase or other low-entropy user cr
807
808 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. I
809 generate and manage any needed salt(s) in user
810
811 Getting a file's encryption nonce
812 ---------------------------------
813
814 Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPT
815 On encrypted files and directories it gets the
816 On unencrypted files and directories, it fails
817
818 This ioctl can be useful for automated tests w
819 encryption is being done correctly. It is not
820 of fscrypt.
821
822 Adding keys
823 -----------
824
825 FS_IOC_ADD_ENCRYPTION_KEY
826 ~~~~~~~~~~~~~~~~~~~~~~~~~
827
828 The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a mas
829 the filesystem, making all files on the filesy
830 encrypted using that key appear "unlocked", i.
831 It can be executed on any file or directory on
832 but using the filesystem's root directory is r
833 a pointer to struct fscrypt_add_key_arg, defin
834
835 struct fscrypt_add_key_arg {
836 struct fscrypt_key_specifier key_s
837 __u32 raw_size;
838 __u32 key_id;
839 __u32 __reserved[8];
840 __u8 raw[];
841 };
842
843 #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR
844 #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER
845
846 struct fscrypt_key_specifier {
847 __u32 type; /* one of FSCRYPT_
848 __u32 __reserved;
849 union {
850 __u8 __reserved[32]; /* re
851 __u8 descriptor[FSCRYPT_KE
852 __u8 identifier[FSCRYPT_KE
853 } u;
854 };
855
856 struct fscrypt_provisioning_key_payload {
857 __u32 type;
858 __u32 __reserved;
859 __u8 raw[];
860 };
861
862 struct fscrypt_add_key_arg must be zeroed, the
863 as follows:
864
865 - If the key is being added for use by v1 encr
866 ``key_spec.type`` must contain FSCRYPT_KEY_S
867 ``key_spec.u.descriptor`` must contain the d
868 being added, corresponding to the value in t
869 ``master_key_descriptor`` field of struct fs
870 To add this type of key, the calling process
871 CAP_SYS_ADMIN capability in the initial user
872
873 Alternatively, if the key is being added for
874 policies, then ``key_spec.type`` must contai
875 FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_
876 an *output* field which the kernel fills in
877 hash of the key. To add this type of key, t
878 not need any privileges. However, the numbe
879 added is limited by the user's quota for the
880 ``Documentation/security/keys/core.rst``).
881
882 - ``raw_size`` must be the size of the ``raw``
883 Alternatively, if ``key_id`` is nonzero, thi
884 in that case the size is implied by the spec
885
886 - ``key_id`` is 0 if the raw key is given dire
887 field. Otherwise ``key_id`` is the ID of a
888 type "fscrypt-provisioning" whose payload is
889 struct fscrypt_provisioning_key_payload whos
890 the raw key and whose ``type`` field matches
891 Since ``raw`` is variable-length, the total
892 payload must be ``sizeof(struct fscrypt_prov
893 plus the raw key size. The process must hav
894 this key.
895
896 Most users should leave this 0 and specify t
897 The support for specifying a Linux keyring k
898 allow re-adding keys after a filesystem is u
899 without having to store the raw keys in user
900
901 - ``raw`` is a variable-length field which mus
902 key, ``raw_size`` bytes long. Alternatively
903 nonzero, then this field is unused.
904
905 For v2 policy keys, the kernel keeps track of
906 by effective user ID) added the key, and only
907 removed by that user --- or by "root", if they
908 `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
909
910 However, if another user has added the key, it
911 prevent that other user from unexpectedly remo
912 FS_IOC_ADD_ENCRYPTION_KEY may also be used to
913 *again*, even if it's already added by other u
914 FS_IOC_ADD_ENCRYPTION_KEY will just install a
915 current user, rather than actually add the key
916 must still be provided, as a proof of knowledg
917
918 FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either
919 the key was either added or already exists.
920
921 FS_IOC_ADD_ENCRYPTION_KEY can fail with the fo
922
923 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR
924 caller does not have the CAP_SYS_ADMIN capab
925 user namespace; or the raw key was specified
926 process lacks Search permission on the key.
927 - ``EDQUOT``: the key quota for this user woul
928 the key
929 - ``EINVAL``: invalid key size or key specifie
930 were set
931 - ``EKEYREJECTED``: the raw key was specified
932 key has the wrong type
933 - ``ENOKEY``: the raw key was specified by Lin
934 exists with that ID
935 - ``ENOTTY``: this type of filesystem does not
936 - ``EOPNOTSUPP``: the kernel was not configure
937 support for this filesystem, or the filesyst
938 had encryption enabled on it
939
940 Legacy method
941 ~~~~~~~~~~~~~
942
943 For v1 encryption policies, a master encryptio
944 provided by adding it to a process-subscribed
945 session keyring, or to a user keyring if the u
946 into the session keyring.
947
948 This method is deprecated (and not supported f
949 policies) for several reasons. First, it cann
950 combination with FS_IOC_REMOVE_ENCRYPTION_KEY
951 so for removing a key a workaround such as key
952 combination with ``sync; echo 2 > /proc/sys/vm
953 have to be used. Second, it doesn't match the
954 locked/unlocked status of encrypted files (i.e
955 be in plaintext form or in ciphertext form) is
956 has caused much confusion as well as real prob
957 running under different UIDs, such as a ``sudo
958 access encrypted files.
959
960 Nevertheless, to add a key to one of the proce
961 the add_key() system call can be used (see:
962 ``Documentation/security/keys/core.rst``). Th
963 "logon"; keys of this type are kept in kernel
964 read back by userspace. The key description m
965 followed by the 16-character lower case hex re
966 ``master_key_descriptor`` that was set in the
967 key payload must conform to the following stru
968
969 #define FSCRYPT_MAX_KEY_SIZE 64
970
971 struct fscrypt_key {
972 __u32 mode;
973 __u8 raw[FSCRYPT_MAX_KEY_SIZE];
974 __u32 size;
975 };
976
977 ``mode`` is ignored; just set it to 0. The ac
978 ``raw`` with ``size`` indicating its size in b
979 bytes ``raw[0..size-1]`` (inclusive) are the a
980
981 The key description prefix "fscrypt:" may alte
982 with a filesystem-specific prefix such as "ext
983 filesystem-specific prefixes are deprecated an
984 new programs.
985
986 Removing keys
987 -------------
988
989 Two ioctls are available for removing a key th
990 `FS_IOC_ADD_ENCRYPTION_KEY`_:
991
992 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
993 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
994
995 These two ioctls differ only in cases where v2
996 or removed by non-root users.
997
998 These ioctls don't work on keys that were adde
999 process-subscribed keyrings mechanism.
1000
1001 Before using these ioctls, read the `Kernel m
1002 section for a discussion of the security goal
1003 these ioctls.
1004
1005 FS_IOC_REMOVE_ENCRYPTION_KEY
1006 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1007
1008 The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl remove
1009 encryption key from the filesystem, and possi
1010 itself. It can be executed on any file or di
1011 filesystem, but using the filesystem's root d
1012 It takes in a pointer to struct fscrypt_remov
1013 as follows::
1014
1015 struct fscrypt_remove_key_arg {
1016 struct fscrypt_key_specifier key_
1017 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_F
1018 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_O
1019 __u32 removal_status_flags; /
1020 __u32 __reserved[5];
1021 };
1022
1023 This structure must be zeroed, then initializ
1024
1025 - The key to remove is specified by ``key_spe
1026
1027 - To remove a key used by v1 encryption p
1028 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T
1029 in ``key_spec.u.descriptor``. To remov
1030 calling process must have the CAP_SYS_A
1031 initial user namespace.
1032
1033 - To remove a key used by v2 encryption p
1034 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T
1035 in ``key_spec.u.identifier``.
1036
1037 For v2 policy keys, this ioctl is usable by n
1038 to make this possible, it actually just remov
1039 claim to the key, undoing a single call to FS
1040 Only after all claims are removed is the key
1041
1042 For example, if FS_IOC_ADD_ENCRYPTION_KEY was
1043 then the key will be "claimed" by uid 1000, a
1044 FS_IOC_REMOVE_ENCRYPTION_KEY will only succee
1045 both uids 1000 and 2000 added the key, then f
1046 FS_IOC_REMOVE_ENCRYPTION_KEY will only remove
1047 once *both* are removed is the key really rem
1048 unlinking a file that may have hard links.)
1049
1050 If FS_IOC_REMOVE_ENCRYPTION_KEY really remove
1051 try to "lock" all files that had been unlocke
1052 lock files that are still in-use, so this ioc
1053 in cooperation with userspace ensuring that n
1054 still open. However, if necessary, this ioct
1055 later to retry locking any remaining files.
1056
1057 FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if eit
1058 (but may still have files remaining to be loc
1059 the key was removed, or the key was already r
1060 remaining to be the locked so the ioctl retri
1061 of these cases, ``removal_status_flags`` is f
1062 following informational status flags:
1063
1064 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUS
1065 are still in-use. Not guaranteed to be set
1066 the user's claim to the key was removed.
1067 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USE
1068 user's claim to the key was removed, not th
1069
1070 FS_IOC_REMOVE_ENCRYPTION_KEY can fail with th
1071
1072 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCR
1073 was specified, but the caller does not have
1074 capability in the initial user namespace
1075 - ``EINVAL``: invalid key specifier type, or
1076 - ``ENOKEY``: the key object was not found at
1077 added in the first place or was already ful
1078 files locked; or, the user does not have a
1079 someone else does).
1080 - ``ENOTTY``: this type of filesystem does no
1081 - ``EOPNOTSUPP``: the kernel was not configur
1082 support for this filesystem, or the filesys
1083 had encryption enabled on it
1084
1085 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
1086 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1087
1088 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exa
1089 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that
1090 ALL_USERS version of the ioctl will remove al
1091 key, not just the current user's. I.e., the
1092 removed, no matter how many users have added
1093 only meaningful if non-root users are adding
1094
1095 Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY
1096 "root", namely the CAP_SYS_ADMIN capability i
1097 namespace. Otherwise it will fail with EACCE
1098
1099 Getting key status
1100 ------------------
1101
1102 FS_IOC_GET_ENCRYPTION_KEY_STATUS
1103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1104
1105 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl re
1106 master encryption key. It can be executed on
1107 the target filesystem, but using the filesyst
1108 recommended. It takes in a pointer to
1109 struct fscrypt_get_key_status_arg, defined as
1110
1111 struct fscrypt_get_key_status_arg {
1112 /* input */
1113 struct fscrypt_key_specifier key_
1114 __u32 __reserved[6];
1115
1116 /* output */
1117 #define FSCRYPT_KEY_STATUS_ABSENT
1118 #define FSCRYPT_KEY_STATUS_PRESENT
1119 #define FSCRYPT_KEY_STATUS_INCOMPLETELY_R
1120 __u32 status;
1121 #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_
1122 __u32 status_flags;
1123 __u32 user_count;
1124 __u32 __out_reserved[13];
1125 };
1126
1127 The caller must zero all input fields, then f
1128
1129 - To get the status of a key for v1 encry
1130 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T
1131 in ``key_spec.u.descriptor``.
1132
1133 - To get the status of a key for v2 encry
1134 ``key_spec.type`` to FSCRYPT_KEY_SPEC_T
1135 in ``key_spec.u.identifier``.
1136
1137 On success, 0 is returned and the kernel fill
1138
1139 - ``status`` indicates whether the key is abs
1140 incompletely removed. Incompletely removed
1141 been initiated, but some files are still in
1142 `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0
1143 status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG
1144
1145 - ``status_flags`` can contain the following
1146
1147 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF
1148 has added by the current user. This is
1149 identified by ``identifier`` rather tha
1150
1151 - ``user_count`` specifies the number of user
1152 This is only set for keys identified by ``i
1153 by ``descriptor``.
1154
1155 FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail wit
1156
1157 - ``EINVAL``: invalid key specifier type, or
1158 - ``ENOTTY``: this type of filesystem does no
1159 - ``EOPNOTSUPP``: the kernel was not configur
1160 support for this filesystem, or the filesys
1161 had encryption enabled on it
1162
1163 Among other use cases, FS_IOC_GET_ENCRYPTION_
1164 for determining whether the key for a given e
1165 to be added before prompting the user for the
1166 derive the key.
1167
1168 FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get
1169 the filesystem-level keyring, i.e. the keyrin
1170 `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMO
1171 cannot get the status of a key that has only
1172 encryption policies using the legacy mechanis
1173 process-subscribed keyrings.
1174
1175 Access semantics
1176 ================
1177
1178 With the key
1179 ------------
1180
1181 With the encryption key, encrypted regular fi
1182 symlinks behave very similarly to their unenc
1183 after all, the encryption is intended to be t
1184 astute users may notice some differences in b
1185
1186 - Unencrypted files, or files encrypted with
1187 policy (i.e. different key, modes, or flags
1188 linked into an encrypted directory; see `En
1189 enforcement`_. Attempts to do so will fail
1190 encrypted files can be renamed within an en
1191 into an unencrypted directory.
1192
1193 Note: "moving" an unencrypted file into an
1194 with the `mv` program, is implemented in us
1195 followed by a delete. Be aware that the or
1196 may remain recoverable from free space on t
1197 all files encrypted from the very beginning
1198 may be used to overwrite the source files b
1199 effective on all filesystems and storage de
1200
1201 - Direct I/O is supported on encrypted files
1202 circumstances. For details, see `Direct I/
1203
1204 - The fallocate operations FALLOC_FL_COLLAPSE
1205 FALLOC_FL_INSERT_RANGE are not supported on
1206 fail with EOPNOTSUPP.
1207
1208 - Online defragmentation of encrypted files i
1209 EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE i
1210 EOPNOTSUPP.
1211
1212 - The ext4 filesystem does not support data j
1213 regular files. It will fall back to ordere
1214
1215 - DAX (Direct Access) is not supported on enc
1216
1217 - The maximum length of an encrypted symlink
1218 the maximum length of an unencrypted symlin
1219 EXT4 filesystem with a 4K block size, unenc
1220 to 4095 bytes long, while encrypted symlink
1221 bytes long (both lengths excluding the term
1222
1223 Note that mmap *is* supported. This is possi
1224 for an encrypted file contains the plaintext,
1225
1226 Without the key
1227 ---------------
1228
1229 Some filesystem operations may be performed o
1230 files, directories, and symlinks even before
1231 been added, or after their encryption key has
1232
1233 - File metadata may be read, e.g. using stat(
1234
1235 - Directories may be listed, in which case th
1236 listed in an encoded form derived from thei
1237 current encoding algorithm is described in
1238 encoding`_. The algorithm is subject to ch
1239 guaranteed that the presented filenames wil
1240 NAME_MAX bytes, will not contain the ``/``
1241 will uniquely identify directory entries.
1242
1243 The ``.`` and ``..`` directory entries are
1244 present and are not encrypted or encoded.
1245
1246 - Files may be deleted. That is, nondirector
1247 with unlink() as usual, and empty directori
1248 rmdir() as usual. Therefore, ``rm`` and ``
1249 expected.
1250
1251 - Symlink targets may be read and followed, b
1252 in encrypted form, similar to filenames in
1253 are unlikely to point to anywhere useful.
1254
1255 Without the key, regular files cannot be open
1256 Attempts to do so will fail with ENOKEY. Thi
1257 regular file operations that require a file d
1258 read(), write(), mmap(), fallocate(), and ioc
1259
1260 Also without the key, files of any type (incl
1261 be created or linked into an encrypted direct
1262 encrypted directory be the source or target o
1263 O_TMPFILE temporary file be created in an enc
1264 such operations will fail with ENOKEY.
1265
1266 It is not currently possible to backup and re
1267 without the encryption key. This would requi
1268 have not yet been implemented.
1269
1270 Encryption policy enforcement
1271 =============================
1272
1273 After an encryption policy has been set on a
1274 files, directories, and symbolic links create
1275 (recursively) will inherit that encryption po
1276 that is, named pipes, device nodes, and UNIX
1277 not be encrypted.
1278
1279 Except for those special files, it is forbidd
1280 files, or files encrypted with a different en
1281 encrypted directory tree. Attempts to link o
1282 an encrypted directory will fail with EXDEV.
1283 during ->lookup() to provide limited protecti
1284 attacks that try to disable or downgrade encr
1285 where applications may later write sensitive
1286 that systems implementing a form of "verified
1287 this by validating all top-level encryption p
1288
1289 Inline encryption support
1290 =========================
1291
1292 By default, fscrypt uses the kernel crypto AP
1293 operations (other than HKDF, which fscrypt pa
1294 itself). The kernel crypto API supports hard
1295 but only ones that work in the traditional wa
1296 outputs (e.g. plaintexts and ciphertexts) are
1297 take advantage of such hardware, but the trad
1298 model isn't particularly efficient and fscryp
1299 for it.
1300
1301 Instead, many newer systems (especially mobil
1302 encryption hardware* that can encrypt/decrypt
1303 way to/from the storage device. Linux suppor
1304 through a set of extensions to the block laye
1305 blk-crypto allows filesystems to attach encry
1306 (I/O requests) to specify how the data will b
1307 in-line. For more information about blk-cryp
1308 :ref:`Documentation/block/inline-encryption.r
1309
1310 On supported filesystems (currently ext4 and
1311 blk-crypto instead of the kernel crypto API t
1312 contents. To enable this, set CONFIG_FS_ENCR
1313 the kernel configuration, and specify the "in
1314 when mounting the filesystem.
1315
1316 Note that the "inlinecrypt" mount option just
1317 encryption when possible; it doesn't force it
1318 still fall back to using the kernel crypto AP
1319 inline encryption hardware doesn't have the n
1320 (e.g. support for the needed encryption algor
1321 and where blk-crypto-fallback is unusable. (
1322 to be usable, it must be enabled in the kerne
1323 CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y.)
1324
1325 Currently fscrypt always uses the filesystem
1326 usually 4096 bytes) as the data unit size. T
1327 inline encryption hardware that supports that
1328
1329 Inline encryption doesn't affect the cipherte
1330 the on-disk format, so users may freely switc
1331 using "inlinecrypt" and not using "inlinecryp
1332
1333 Direct I/O support
1334 ==================
1335
1336 For direct I/O on an encrypted file to work,
1337 must be met (in addition to the conditions fo
1338 unencrypted file):
1339
1340 * The file must be using inline encryption.
1341 the filesystem must be mounted with ``-o in
1342 encryption hardware must be present. Howev
1343 is also available. For details, see `Inlin
1344
1345 * The I/O request must be fully aligned to th
1346 This means that the file position the I/O i
1347 of all I/O segments, and the memory address
1348 must be multiples of this value. Note that
1349 size may be greater than the logical block
1350
1351 If either of the above conditions is not met,
1352 encrypted file will fall back to buffered I/O
1353
1354 Implementation details
1355 ======================
1356
1357 Encryption context
1358 ------------------
1359
1360 An encryption policy is represented on-disk b
1361 struct fscrypt_context_v1 or struct fscrypt_c
1362 individual filesystems to decide where to sto
1363 would be stored in a hidden extended attribut
1364 exposed by the xattr-related system calls suc
1365 setxattr() because of the special semantics o
1366 (In particular, there would be much confusion
1367 were to be added to or removed from anything
1368 directory.) These structs are defined as fol
1369
1370 #define FSCRYPT_FILE_NONCE_SIZE 16
1371
1372 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
1373 struct fscrypt_context_v1 {
1374 u8 version;
1375 u8 contents_encryption_mode;
1376 u8 filenames_encryption_mode;
1377 u8 flags;
1378 u8 master_key_descriptor[FSCRYPT_
1379 u8 nonce[FSCRYPT_FILE_NONCE_SIZE]
1380 };
1381
1382 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
1383 struct fscrypt_context_v2 {
1384 u8 version;
1385 u8 contents_encryption_mode;
1386 u8 filenames_encryption_mode;
1387 u8 flags;
1388 u8 log2_data_unit_size;
1389 u8 __reserved[3];
1390 u8 master_key_identifier[FSCRYPT_
1391 u8 nonce[FSCRYPT_FILE_NONCE_SIZE]
1392 };
1393
1394 The context structs contain the same informat
1395 policy structs (see `Setting an encryption po
1396 context structs also contain a nonce. The no
1397 by the kernel and is used as KDF input or as
1398 different files to be encrypted differently;
1399 keys`_ and `DIRECT_KEY policies`_.
1400
1401 Data path changes
1402 -----------------
1403
1404 When inline encryption is used, filesystems j
1405 encryption contexts with bios to specify how
1406 inline encryption hardware will encrypt/decry
1407
1408 When inline encryption isn't used, filesystem
1409 the file contents themselves, as described be
1410
1411 For the read path (->read_folio()) of regular
1412 read the ciphertext into the page cache and d
1413 folio lock must be held until decryption has
1414 folio from becoming visible to userspace prem
1415
1416 For the write path (->writepage()) of regular
1417 cannot encrypt data in-place in the page cach
1418 plaintext must be preserved. Instead, filesy
1419 temporary buffer or "bounce page", then write
1420 buffer. Some filesystems, such as UBIFS, alr
1421 buffers regardless of encryption. Other file
1422 F2FS, have to allocate bounce pages specially
1423
1424 Filename hashing and encoding
1425 -----------------------------
1426
1427 Modern filesystems accelerate directory looku
1428 directories. An indexed directory is organiz
1429 filename hashes. When a ->lookup() is reques
1430 normally hashes the filename being looked up
1431 find the corresponding directory entry, if an
1432
1433 With encryption, lookups must be supported an
1434 without the encryption key. Clearly, it woul
1435 plaintext filenames, since the plaintext file
1436 without the key. (Hashing the plaintext file
1437 impossible for the filesystem's fsck tool to
1438 directories.) Instead, filesystems hash the
1439 i.e. the bytes actually stored on-disk in the
1440 asked to do a ->lookup() with the key, the fi
1441 the user-supplied name to get the ciphertext.
1442
1443 Lookups without the key are more complicated.
1444 contain the ``\0`` and ``/`` characters, whic
1445 filenames. Therefore, readdir() must base64u
1446 for presentation. For most filenames, this w
1447 the filesystem just base64url-decodes the use
1448 back to the raw ciphertext.
1449
1450 However, for very long filenames, base64url e
1451 filename length to exceed NAME_MAX. To preve
1452 actually presents long filenames in an abbrev
1453 a strong "hash" of the ciphertext filename, a
1454 filesystem-specific hash(es) needed for direc
1455 allows the filesystem to still, with a high d
1456 the filename given in ->lookup() back to a pa
1457 that was previously listed by readdir(). See
1458 struct fscrypt_nokey_name in the source for m
1459
1460 Note that the precise way that filenames are
1461 without the key is subject to change in the f
1462 as a way to temporarily present valid filenam
1463 ``rm -r`` work as expected on encrypted direc
1464
1465 Tests
1466 =====
1467
1468 To test fscrypt, use xfstests, which is Linux
1469 filesystem test suite. First, run all the te
1470 group on the relevant filesystem(s). One can
1471 with the 'inlinecrypt' mount option to test t
1472 inline encryption support. For example, to t
1473 f2fs encryption using `kvm-xfstests
1474 <https://github.com/tytso/xfstests-bld/blob/m
1475
1476 kvm-xfstests -c ext4,f2fs -g encrypt
1477 kvm-xfstests -c ext4,f2fs -g encrypt -m i
1478
1479 UBIFS encryption can also be tested this way,
1480 a separate command, and it takes some time fo
1481 emulated UBI volumes::
1482
1483 kvm-xfstests -c ubifs -g encrypt
1484
1485 No tests should fail. However, tests that us
1486 modes (e.g. generic/549 and generic/550) will
1487 algorithms were not built into the kernel's c
1488 that access the raw block device (e.g. generi
1489 generic/549, generic/550) will be skipped on
1490
1491 Besides running the "encrypt" group tests, fo
1492 possible to run most xfstests with the "test_
1493 option. This option causes all new files to
1494 encrypted with a dummy key, without having to
1495 This tests the encrypted I/O paths more thoro
1496 kvm-xfstests, use the "encrypt" filesystem co
1497
1498 kvm-xfstests -c ext4/encrypt,f2fs/encrypt
1499 kvm-xfstests -c ext4/encrypt,f2fs/encrypt
1500
1501 Because this runs many more tests than "-g en
1502 much longer to run; so also consider using `g
1503 <https://github.com/tytso/xfstests-bld/blob/m
1504 instead of kvm-xfstests::
1505
1506 gce-xfstests -c ext4/encrypt,f2fs/encrypt
1507 gce-xfstests -c ext4/encrypt,f2fs/encrypt
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.