Merge tag 'leaks-5.1-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tobin...
[sfrench/cifs-2.6.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 fscrypt is only resistant to side-channel attacks, such as timing or
76 electromagnetic attacks, to the extent that the underlying Linux
77 Cryptographic API algorithms are.  If a vulnerable algorithm is used,
78 such as a table-based implementation of AES, it may be possible for an
79 attacker to mount a side channel attack against the online system.
80 Side channel attacks may also be mounted against applications
81 consuming decrypted data.
82
83 After an encryption key has been provided, fscrypt is not designed to
84 hide the plaintext file contents or filenames from other users on the
85 same system, regardless of the visibility of the keyring key.
86 Instead, existing access control mechanisms such as file mode bits,
87 POSIX ACLs, LSMs, or mount namespaces should be used for this purpose.
88 Also note that as long as the encryption keys are *anywhere* in
89 memory, an online attacker can necessarily compromise them by mounting
90 a physical attack or by exploiting any kernel security vulnerability
91 which provides an arbitrary memory read primitive.
92
93 While it is ostensibly possible to "evict" keys from the system,
94 recently accessed encrypted files will remain accessible at least
95 until the filesystem is unmounted or the VFS caches are dropped, e.g.
96 using ``echo 2 > /proc/sys/vm/drop_caches``.  Even after that, if the
97 RAM is compromised before being powered off, it will likely still be
98 possible to recover portions of the plaintext file contents, if not
99 some of the encryption keys as well.  (Since Linux v4.12, all
100 in-kernel keys related to fscrypt are sanitized before being freed.
101 However, userspace would need to do its part as well.)
102
103 Currently, fscrypt does not prevent a user from maliciously providing
104 an incorrect key for another user's existing encrypted files.  A
105 protection against this is planned.
106
107 Key hierarchy
108 =============
109
110 Master Keys
111 -----------
112
113 Each encrypted directory tree is protected by a *master key*.  Master
114 keys can be up to 64 bytes long, and must be at least as long as the
115 greater of the key length needed by the contents and filenames
116 encryption modes being used.  For example, if AES-256-XTS is used for
117 contents encryption, the master key must be 64 bytes (512 bits).  Note
118 that the XTS mode is defined to require a key twice as long as that
119 required by the underlying block cipher.
120
121 To "unlock" an encrypted directory tree, userspace must provide the
122 appropriate master key.  There can be any number of master keys, each
123 of which protects any number of directory trees on any number of
124 filesystems.
125
126 Userspace should generate master keys either using a cryptographically
127 secure random number generator, or by using a KDF (Key Derivation
128 Function).  Note that whenever a KDF is used to "stretch" a
129 lower-entropy secret such as a passphrase, it is critical that a KDF
130 designed for this purpose be used, such as scrypt, PBKDF2, or Argon2.
131
132 Per-file keys
133 -------------
134
135 Since each master key can protect many files, it is necessary to
136 "tweak" the encryption of each file so that the same plaintext in two
137 files doesn't map to the same ciphertext, or vice versa.  In most
138 cases, fscrypt does this by deriving per-file keys.  When a new
139 encrypted inode (regular file, directory, or symlink) is created,
140 fscrypt randomly generates a 16-byte nonce and stores it in the
141 inode's encryption xattr.  Then, it uses a KDF (Key Derivation
142 Function) to derive the file's key from the master key and nonce.
143
144 The Adiantum encryption mode (see `Encryption modes and usage`_) is
145 special, since it accepts longer IVs and is suitable for both contents
146 and filenames encryption.  For it, a "direct key" option is offered
147 where the file's nonce is included in the IVs and the master key is
148 used for encryption directly.  This improves performance; however,
149 users must not use the same master key for any other encryption mode.
150
151 Below, the KDF and design considerations are described in more detail.
152
153 The current KDF works by encrypting the master key with AES-128-ECB,
154 using the file's nonce as the AES key.  The output is used as the
155 derived key.  If the output is longer than needed, then it is
156 truncated to the needed length.
157
158 Note: this KDF meets the primary security requirement, which is to
159 produce unique derived keys that preserve the entropy of the master
160 key, assuming that the master key is already a good pseudorandom key.
161 However, it is nonstandard and has some problems such as being
162 reversible, so it is generally considered to be a mistake!  It may be
163 replaced with HKDF or another more standard KDF in the future.
164
165 Key derivation was chosen over key wrapping because wrapped keys would
166 require larger xattrs which would be less likely to fit in-line in the
167 filesystem's inode table, and there didn't appear to be any
168 significant advantages to key wrapping.  In particular, currently
169 there is no requirement to support unlocking a file with multiple
170 alternative master keys or to support rotating master keys.  Instead,
171 the master keys may be wrapped in userspace, e.g. as is done by the
172 `fscrypt <https://github.com/google/fscrypt>`_ tool.
173
174 Including the inode number in the IVs was considered.  However, it was
175 rejected as it would have prevented ext4 filesystems from being
176 resized, and by itself still wouldn't have been sufficient to prevent
177 the same key from being directly reused for both XTS and CTS-CBC.
178
179 Encryption modes and usage
180 ==========================
181
182 fscrypt allows one encryption mode to be specified for file contents
183 and one encryption mode to be specified for filenames.  Different
184 directory trees are permitted to use different encryption modes.
185 Currently, the following pairs of encryption modes are supported:
186
187 - AES-256-XTS for contents and AES-256-CTS-CBC for filenames
188 - AES-128-CBC for contents and AES-128-CTS-CBC for filenames
189 - Adiantum for both contents and filenames
190
191 If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
192
193 AES-128-CBC was added only for low-powered embedded devices with
194 crypto accelerators such as CAAM or CESA that do not support XTS.
195
196 Adiantum is a (primarily) stream cipher-based mode that is fast even
197 on CPUs without dedicated crypto instructions.  It's also a true
198 wide-block mode, unlike XTS.  It can also eliminate the need to derive
199 per-file keys.  However, it depends on the security of two primitives,
200 XChaCha12 and AES-256, rather than just one.  See the paper
201 "Adiantum: length-preserving encryption for entry-level processors"
202 (https://eprint.iacr.org/2018/720.pdf) for more details.  To use
203 Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled.  Also, fast
204 implementations of ChaCha and NHPoly1305 should be enabled, e.g.
205 CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM.
206
207 New encryption modes can be added relatively easily, without changes
208 to individual filesystems.  However, authenticated encryption (AE)
209 modes are not currently supported because of the difficulty of dealing
210 with ciphertext expansion.
211
212 Contents encryption
213 -------------------
214
215 For file contents, each filesystem block is encrypted independently.
216 Currently, only the case where the filesystem block size is equal to
217 the system's page size (usually 4096 bytes) is supported.
218
219 Each block's IV is set to the logical block number within the file as
220 a little endian number, except that:
221
222 - With CBC mode encryption, ESSIV is also used.  Specifically, each IV
223   is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
224   of the file's data encryption key.
225
226 - In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in
227   the fscrypt_policy), the file's nonce is also appended to the IV.
228   Currently this is only allowed with the Adiantum encryption mode.
229
230 Filenames encryption
231 --------------------
232
233 For filenames, each full filename is encrypted at once.  Because of
234 the requirements to retain support for efficient directory lookups and
235 filenames of up to 255 bytes, the same IV is used for every filename
236 in a directory.
237
238 However, each encrypted directory still uses a unique key; or
239 alternatively (for the "direct key" configuration) has the file's
240 nonce included in the IVs.  Thus, IV reuse is limited to within a
241 single directory.
242
243 With CTS-CBC, the IV reuse means that when the plaintext filenames
244 share a common prefix at least as long as the cipher block size (16
245 bytes for AES), the corresponding encrypted filenames will also share
246 a common prefix.  This is undesirable.  Adiantum does not have this
247 weakness, as it is a wide-block encryption mode.
248
249 All supported filenames encryption modes accept any plaintext length
250 >= 16 bytes; cipher block alignment is not required.  However,
251 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
252 being encrypted.  In addition, to reduce leakage of filename lengths
253 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
254 16, or 32-byte boundary (configurable).  32 is recommended since this
255 provides the best confidentiality, at the cost of making directory
256 entries consume slightly more space.  Note that since NUL (``\0``) is
257 not otherwise a valid character in filenames, the padding will never
258 produce duplicate plaintexts.
259
260 Symbolic link targets are considered a type of filename and are
261 encrypted in the same way as filenames in directory entries, except
262 that IV reuse is not a problem as each symlink has its own inode.
263
264 User API
265 ========
266
267 Setting an encryption policy
268 ----------------------------
269
270 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
271 empty directory or verifies that a directory or regular file already
272 has the specified encryption policy.  It takes in a pointer to a
273 :c:type:`struct fscrypt_policy`, defined as follows::
274
275     #define FS_KEY_DESCRIPTOR_SIZE  8
276
277     struct fscrypt_policy {
278             __u8 version;
279             __u8 contents_encryption_mode;
280             __u8 filenames_encryption_mode;
281             __u8 flags;
282             __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
283     };
284
285 This structure must be initialized as follows:
286
287 - ``version`` must be 0.
288
289 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
290   be set to constants from ``<linux/fs.h>`` which identify the
291   encryption modes to use.  If unsure, use
292   FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode``
293   and FS_ENCRYPTION_MODE_AES_256_CTS (4) for
294   ``filenames_encryption_mode``.
295
296 - ``flags`` must contain a value from ``<linux/fs.h>`` which
297   identifies the amount of NUL-padding to use when encrypting
298   filenames.  If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3).
299   In addition, if the chosen encryption modes are both
300   FS_ENCRYPTION_MODE_ADIANTUM, this can contain
301   FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be
302   used directly, without key derivation.
303
304 - ``master_key_descriptor`` specifies how to find the master key in
305   the keyring; see `Adding keys`_.  It is up to userspace to choose a
306   unique ``master_key_descriptor`` for each master key.  The e4crypt
307   and fscrypt tools use the first 8 bytes of
308   ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
309   required.  Also, the master key need not be in the keyring yet when
310   FS_IOC_SET_ENCRYPTION_POLICY is executed.  However, it must be added
311   before any files can be created in the encrypted directory.
312
313 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
314 verifies that the file is an empty directory.  If so, the specified
315 encryption policy is assigned to the directory, turning it into an
316 encrypted directory.  After that, and after providing the
317 corresponding master key as described in `Adding keys`_, all regular
318 files, directories (recursively), and symlinks created in the
319 directory will be encrypted, inheriting the same encryption policy.
320 The filenames in the directory's entries will be encrypted as well.
321
322 Alternatively, if the file is already encrypted, then
323 FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
324 policy exactly matches the actual one.  If they match, then the ioctl
325 returns 0.  Otherwise, it fails with EEXIST.  This works on both
326 regular files and directories, including nonempty directories.
327
328 Note that the ext4 filesystem does not allow the root directory to be
329 encrypted, even if it is empty.  Users who want to encrypt an entire
330 filesystem with one key should consider using dm-crypt instead.
331
332 FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
333
334 - ``EACCES``: the file is not owned by the process's uid, nor does the
335   process have the CAP_FOWNER capability in a namespace with the file
336   owner's uid mapped
337 - ``EEXIST``: the file is already encrypted with an encryption policy
338   different from the one specified
339 - ``EINVAL``: an invalid encryption policy was specified (invalid
340   version, mode(s), or flags)
341 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
342   directory
343 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
344 - ``ENOTTY``: this type of filesystem does not implement encryption
345 - ``EOPNOTSUPP``: the kernel was not configured with encryption
346   support for this filesystem, or the filesystem superblock has not
347   had encryption enabled on it.  (For example, to use encryption on an
348   ext4 filesystem, CONFIG_EXT4_ENCRYPTION must be enabled in the
349   kernel config, and the superblock must have had the "encrypt"
350   feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
351   encrypt``.)
352 - ``EPERM``: this directory may not be encrypted, e.g. because it is
353   the root directory of an ext4 filesystem
354 - ``EROFS``: the filesystem is readonly
355
356 Getting an encryption policy
357 ----------------------------
358
359 The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct
360 fscrypt_policy`, if any, for a directory or regular file.  See above
361 for the struct definition.  No additional permissions are required
362 beyond the ability to open the file.
363
364 FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors:
365
366 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
367   encryption context format
368 - ``ENODATA``: the file is not encrypted
369 - ``ENOTTY``: this type of filesystem does not implement encryption
370 - ``EOPNOTSUPP``: the kernel was not configured with encryption
371   support for this filesystem
372
373 Note: if you only need to know whether a file is encrypted or not, on
374 most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
375 and check for FS_ENCRYPT_FL, or to use the statx() system call and
376 check for STATX_ATTR_ENCRYPTED in stx_attributes.
377
378 Getting the per-filesystem salt
379 -------------------------------
380
381 Some filesystems, such as ext4 and F2FS, also support the deprecated
382 ioctl FS_IOC_GET_ENCRYPTION_PWSALT.  This ioctl retrieves a randomly
383 generated 16-byte value stored in the filesystem superblock.  This
384 value is intended to used as a salt when deriving an encryption key
385 from a passphrase or other low-entropy user credential.
386
387 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated.  Instead, prefer to
388 generate and manage any needed salt(s) in userspace.
389
390 Adding keys
391 -----------
392
393 To provide a master key, userspace must add it to an appropriate
394 keyring using the add_key() system call (see:
395 ``Documentation/security/keys/core.rst``).  The key type must be
396 "logon"; keys of this type are kept in kernel memory and cannot be
397 read back by userspace.  The key description must be "fscrypt:"
398 followed by the 16-character lower case hex representation of the
399 ``master_key_descriptor`` that was set in the encryption policy.  The
400 key payload must conform to the following structure::
401
402     #define FS_MAX_KEY_SIZE 64
403
404     struct fscrypt_key {
405             u32 mode;
406             u8 raw[FS_MAX_KEY_SIZE];
407             u32 size;
408     };
409
410 ``mode`` is ignored; just set it to 0.  The actual key is provided in
411 ``raw`` with ``size`` indicating its size in bytes.  That is, the
412 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
413
414 The key description prefix "fscrypt:" may alternatively be replaced
415 with a filesystem-specific prefix such as "ext4:".  However, the
416 filesystem-specific prefixes are deprecated and should not be used in
417 new programs.
418
419 There are several different types of keyrings in which encryption keys
420 may be placed, such as a session keyring, a user session keyring, or a
421 user keyring.  Each key must be placed in a keyring that is "attached"
422 to all processes that might need to access files encrypted with it, in
423 the sense that request_key() will find the key.  Generally, if only
424 processes belonging to a specific user need to access a given
425 encrypted directory and no session keyring has been installed, then
426 that directory's key should be placed in that user's user session
427 keyring or user keyring.  Otherwise, a session keyring should be
428 installed if needed, and the key should be linked into that session
429 keyring, or in a keyring linked into that session keyring.
430
431 Note: introducing the complex visibility semantics of keyrings here
432 was arguably a mistake --- especially given that by design, after any
433 process successfully opens an encrypted file (thereby setting up the
434 per-file key), possessing the keyring key is not actually required for
435 any process to read/write the file until its in-memory inode is
436 evicted.  In the future there probably should be a way to provide keys
437 directly to the filesystem instead, which would make the intended
438 semantics clearer.
439
440 Access semantics
441 ================
442
443 With the key
444 ------------
445
446 With the encryption key, encrypted regular files, directories, and
447 symlinks behave very similarly to their unencrypted counterparts ---
448 after all, the encryption is intended to be transparent.  However,
449 astute users may notice some differences in behavior:
450
451 - Unencrypted files, or files encrypted with a different encryption
452   policy (i.e. different key, modes, or flags), cannot be renamed or
453   linked into an encrypted directory; see `Encryption policy
454   enforcement`_.  Attempts to do so will fail with EPERM.  However,
455   encrypted files can be renamed within an encrypted directory, or
456   into an unencrypted directory.
457
458 - Direct I/O is not supported on encrypted files.  Attempts to use
459   direct I/O on such files will fall back to buffered I/O.
460
461 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE,
462   FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported
463   on encrypted files and will fail with EOPNOTSUPP.
464
465 - Online defragmentation of encrypted files is not supported.  The
466   EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
467   EOPNOTSUPP.
468
469 - The ext4 filesystem does not support data journaling with encrypted
470   regular files.  It will fall back to ordered data mode instead.
471
472 - DAX (Direct Access) is not supported on encrypted files.
473
474 - The st_size of an encrypted symlink will not necessarily give the
475   length of the symlink target as required by POSIX.  It will actually
476   give the length of the ciphertext, which will be slightly longer
477   than the plaintext due to NUL-padding and an extra 2-byte overhead.
478
479 - The maximum length of an encrypted symlink is 2 bytes shorter than
480   the maximum length of an unencrypted symlink.  For example, on an
481   EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
482   to 4095 bytes long, while encrypted symlinks can only be up to 4093
483   bytes long (both lengths excluding the terminating null).
484
485 Note that mmap *is* supported.  This is possible because the pagecache
486 for an encrypted file contains the plaintext, not the ciphertext.
487
488 Without the key
489 ---------------
490
491 Some filesystem operations may be performed on encrypted regular
492 files, directories, and symlinks even before their encryption key has
493 been provided:
494
495 - File metadata may be read, e.g. using stat().
496
497 - Directories may be listed, in which case the filenames will be
498   listed in an encoded form derived from their ciphertext.  The
499   current encoding algorithm is described in `Filename hashing and
500   encoding`_.  The algorithm is subject to change, but it is
501   guaranteed that the presented filenames will be no longer than
502   NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
503   will uniquely identify directory entries.
504
505   The ``.`` and ``..`` directory entries are special.  They are always
506   present and are not encrypted or encoded.
507
508 - Files may be deleted.  That is, nondirectory files may be deleted
509   with unlink() as usual, and empty directories may be deleted with
510   rmdir() as usual.  Therefore, ``rm`` and ``rm -r`` will work as
511   expected.
512
513 - Symlink targets may be read and followed, but they will be presented
514   in encrypted form, similar to filenames in directories.  Hence, they
515   are unlikely to point to anywhere useful.
516
517 Without the key, regular files cannot be opened or truncated.
518 Attempts to do so will fail with ENOKEY.  This implies that any
519 regular file operations that require a file descriptor, such as
520 read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
521
522 Also without the key, files of any type (including directories) cannot
523 be created or linked into an encrypted directory, nor can a name in an
524 encrypted directory be the source or target of a rename, nor can an
525 O_TMPFILE temporary file be created in an encrypted directory.  All
526 such operations will fail with ENOKEY.
527
528 It is not currently possible to backup and restore encrypted files
529 without the encryption key.  This would require special APIs which
530 have not yet been implemented.
531
532 Encryption policy enforcement
533 =============================
534
535 After an encryption policy has been set on a directory, all regular
536 files, directories, and symbolic links created in that directory
537 (recursively) will inherit that encryption policy.  Special files ---
538 that is, named pipes, device nodes, and UNIX domain sockets --- will
539 not be encrypted.
540
541 Except for those special files, it is forbidden to have unencrypted
542 files, or files encrypted with a different encryption policy, in an
543 encrypted directory tree.  Attempts to link or rename such a file into
544 an encrypted directory will fail with EPERM.  This is also enforced
545 during ->lookup() to provide limited protection against offline
546 attacks that try to disable or downgrade encryption in known locations
547 where applications may later write sensitive data.  It is recommended
548 that systems implementing a form of "verified boot" take advantage of
549 this by validating all top-level encryption policies prior to access.
550
551 Implementation details
552 ======================
553
554 Encryption context
555 ------------------
556
557 An encryption policy is represented on-disk by a :c:type:`struct
558 fscrypt_context`.  It is up to individual filesystems to decide where
559 to store it, but normally it would be stored in a hidden extended
560 attribute.  It should *not* be exposed by the xattr-related system
561 calls such as getxattr() and setxattr() because of the special
562 semantics of the encryption xattr.  (In particular, there would be
563 much confusion if an encryption policy were to be added to or removed
564 from anything other than an empty directory.)  The struct is defined
565 as follows::
566
567     #define FS_KEY_DESCRIPTOR_SIZE  8
568     #define FS_KEY_DERIVATION_NONCE_SIZE 16
569
570     struct fscrypt_context {
571             u8 format;
572             u8 contents_encryption_mode;
573             u8 filenames_encryption_mode;
574             u8 flags;
575             u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
576             u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
577     };
578
579 Note that :c:type:`struct fscrypt_context` contains the same
580 information as :c:type:`struct fscrypt_policy` (see `Setting an
581 encryption policy`_), except that :c:type:`struct fscrypt_context`
582 also contains a nonce.  The nonce is randomly generated by the kernel
583 and is used to derive the inode's encryption key as described in
584 `Per-file keys`_.
585
586 Data path changes
587 -----------------
588
589 For the read path (->readpage()) of regular files, filesystems can
590 read the ciphertext into the page cache and decrypt it in-place.  The
591 page lock must be held until decryption has finished, to prevent the
592 page from becoming visible to userspace prematurely.
593
594 For the write path (->writepage()) of regular files, filesystems
595 cannot encrypt data in-place in the page cache, since the cached
596 plaintext must be preserved.  Instead, filesystems must encrypt into a
597 temporary buffer or "bounce page", then write out the temporary
598 buffer.  Some filesystems, such as UBIFS, already use temporary
599 buffers regardless of encryption.  Other filesystems, such as ext4 and
600 F2FS, have to allocate bounce pages specially for encryption.
601
602 Filename hashing and encoding
603 -----------------------------
604
605 Modern filesystems accelerate directory lookups by using indexed
606 directories.  An indexed directory is organized as a tree keyed by
607 filename hashes.  When a ->lookup() is requested, the filesystem
608 normally hashes the filename being looked up so that it can quickly
609 find the corresponding directory entry, if any.
610
611 With encryption, lookups must be supported and efficient both with and
612 without the encryption key.  Clearly, it would not work to hash the
613 plaintext filenames, since the plaintext filenames are unavailable
614 without the key.  (Hashing the plaintext filenames would also make it
615 impossible for the filesystem's fsck tool to optimize encrypted
616 directories.)  Instead, filesystems hash the ciphertext filenames,
617 i.e. the bytes actually stored on-disk in the directory entries.  When
618 asked to do a ->lookup() with the key, the filesystem just encrypts
619 the user-supplied name to get the ciphertext.
620
621 Lookups without the key are more complicated.  The raw ciphertext may
622 contain the ``\0`` and ``/`` characters, which are illegal in
623 filenames.  Therefore, readdir() must base64-encode the ciphertext for
624 presentation.  For most filenames, this works fine; on ->lookup(), the
625 filesystem just base64-decodes the user-supplied name to get back to
626 the raw ciphertext.
627
628 However, for very long filenames, base64 encoding would cause the
629 filename length to exceed NAME_MAX.  To prevent this, readdir()
630 actually presents long filenames in an abbreviated form which encodes
631 a strong "hash" of the ciphertext filename, along with the optional
632 filesystem-specific hash(es) needed for directory lookups.  This
633 allows the filesystem to still, with a high degree of confidence, map
634 the filename given in ->lookup() back to a particular directory entry
635 that was previously listed by readdir().  See :c:type:`struct
636 fscrypt_digested_name` in the source for more details.
637
638 Note that the precise way that filenames are presented to userspace
639 without the key is subject to change in the future.  It is only meant
640 as a way to temporarily present valid filenames so that commands like
641 ``rm -r`` work as expected on encrypted directories.