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