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.  To
 195 use AES-128-CBC, CONFIG_CRYPTO_SHA256 (or another SHA-256
 196 implementation) must be enabled so that ESSIV can be used.
 197
 198 Adiantum is a (primarily) stream cipher-based mode that is fast even
 199 on CPUs without dedicated crypto instructions.  It's also a true
 200 wide-block mode, unlike XTS.  It can also eliminate the need to derive
 201 per-file keys.  However, it depends on the security of two primitives,
 202 XChaCha12 and AES-256, rather than just one.  See the paper
 203 "Adiantum: length-preserving encryption for entry-level processors"
 204 (https://eprint.iacr.org/2018/720.pdf) for more details.  To use
 205 Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled.  Also, fast
 206 implementations of ChaCha and NHPoly1305 should be enabled, e.g.
 207 CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM.
 208
 209 New encryption modes can be added relatively easily, without changes
 210 to individual filesystems.  However, authenticated encryption (AE)
 211 modes are not currently supported because of the difficulty of dealing
 212 with ciphertext expansion.
 213
 214 Contents encryption
 215 -------------------
 216
 217 For file contents, each filesystem block is encrypted independently.
 218 Currently, only the case where the filesystem block size is equal to
 219 the system's page size (usually 4096 bytes) is supported.
 220
 221 Each block's IV is set to the logical block number within the file as
 222 a little endian number, except that:
 223
 224 - With CBC mode encryption, ESSIV is also used.  Specifically, each IV
 225   is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
 226   of the file's data encryption key.
 227
 228 - In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in
 229   the fscrypt_policy), the file's nonce is also appended to the IV.
 230   Currently this is only allowed with the Adiantum encryption mode.
 231
 232 Filenames encryption
 233 --------------------
 234
 235 For filenames, each full filename is encrypted at once.  Because of
 236 the requirements to retain support for efficient directory lookups and
 237 filenames of up to 255 bytes, the same IV is used for every filename
 238 in a directory.
 239
 240 However, each encrypted directory still uses a unique key; or
 241 alternatively (for the "direct key" configuration) has the file's
 242 nonce included in the IVs.  Thus, IV reuse is limited to within a
 243 single directory.
 244
 245 With CTS-CBC, the IV reuse means that when the plaintext filenames
 246 share a common prefix at least as long as the cipher block size (16
 247 bytes for AES), the corresponding encrypted filenames will also share
 248 a common prefix.  This is undesirable.  Adiantum does not have this
 249 weakness, as it is a wide-block encryption mode.
 250
 251 All supported filenames encryption modes accept any plaintext length
 252 >= 16 bytes; cipher block alignment is not required.  However,
 253 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
 254 being encrypted.  In addition, to reduce leakage of filename lengths
 255 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
 256 16, or 32-byte boundary (configurable).  32 is recommended since this
 257 provides the best confidentiality, at the cost of making directory
 258 entries consume slightly more space.  Note that since NUL (``\0``) is
 259 not otherwise a valid character in filenames, the padding will never
 260 produce duplicate plaintexts.
 261
 262 Symbolic link targets are considered a type of filename and are
 263 encrypted in the same way as filenames in directory entries, except
 264 that IV reuse is not a problem as each symlink has its own inode.
 265
 266 User API
 267 ========
 268
 269 Setting an encryption policy
 270 ----------------------------
 271
 272 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
 273 empty directory or verifies that a directory or regular file already
 274 has the specified encryption policy.  It takes in a pointer to a
 275 :c:type:`struct fscrypt_policy`, defined as follows::
 276
 277     #define FS_KEY_DESCRIPTOR_SIZE  8
 278
 279     struct fscrypt_policy {
 280             __u8 version;
 281             __u8 contents_encryption_mode;
 282             __u8 filenames_encryption_mode;
 283             __u8 flags;
 284             __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
 285     };
 286
 287 This structure must be initialized as follows:
 288
 289 - ``version`` must be 0.
 290
 291 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
 292   be set to constants from ``<linux/fs.h>`` which identify the
 293   encryption modes to use.  If unsure, use
 294   FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode``
 295   and FS_ENCRYPTION_MODE_AES_256_CTS (4) for
 296   ``filenames_encryption_mode``.
 297
 298 - ``flags`` must contain a value from ``<linux/fs.h>`` which
 299   identifies the amount of NUL-padding to use when encrypting
 300   filenames.  If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3).
 301   In addition, if the chosen encryption modes are both
 302   FS_ENCRYPTION_MODE_ADIANTUM, this can contain
 303   FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be
 304   used directly, without key derivation.
 305
 306 - ``master_key_descriptor`` specifies how to find the master key in
 307   the keyring; see `Adding keys`_.  It is up to userspace to choose a
 308   unique ``master_key_descriptor`` for each master key.  The e4crypt
 309   and fscrypt tools use the first 8 bytes of
 310   ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
 311   required.  Also, the master key need not be in the keyring yet when
 312   FS_IOC_SET_ENCRYPTION_POLICY is executed.  However, it must be added
 313   before any files can be created in the encrypted directory.
 314
 315 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
 316 verifies that the file is an empty directory.  If so, the specified
 317 encryption policy is assigned to the directory, turning it into an
 318 encrypted directory.  After that, and after providing the
 319 corresponding master key as described in `Adding keys`_, all regular
 320 files, directories (recursively), and symlinks created in the
 321 directory will be encrypted, inheriting the same encryption policy.
 322 The filenames in the directory's entries will be encrypted as well.
 323
 324 Alternatively, if the file is already encrypted, then
 325 FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
 326 policy exactly matches the actual one.  If they match, then the ioctl
 327 returns 0.  Otherwise, it fails with EEXIST.  This works on both
 328 regular files and directories, including nonempty directories.
 329
 330 Note that the ext4 filesystem does not allow the root directory to be
 331 encrypted, even if it is empty.  Users who want to encrypt an entire
 332 filesystem with one key should consider using dm-crypt instead.
 333
 334 FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
 335
 336 - ``EACCES``: the file is not owned by the process's uid, nor does the
 337   process have the CAP_FOWNER capability in a namespace with the file
 338   owner's uid mapped
 339 - ``EEXIST``: the file is already encrypted with an encryption policy
 340   different from the one specified
 341 - ``EINVAL``: an invalid encryption policy was specified (invalid
 342   version, mode(s), or flags)
 343 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
 344   directory
 345 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
 346 - ``ENOTTY``: this type of filesystem does not implement encryption
 347 - ``EOPNOTSUPP``: the kernel was not configured with encryption
 348   support for filesystems, or the filesystem superblock has not
 349   had encryption enabled on it.  (For example, to use encryption on an
 350   ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the
 351   kernel config, and the superblock must have had the "encrypt"
 352   feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
 353   encrypt``.)
 354 - ``EPERM``: this directory may not be encrypted, e.g. because it is
 355   the root directory of an ext4 filesystem
 356 - ``EROFS``: the filesystem is readonly
 357
 358 Getting an encryption policy
 359 ----------------------------
 360
 361 The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct
 362 fscrypt_policy`, if any, for a directory or regular file.  See above
 363 for the struct definition.  No additional permissions are required
 364 beyond the ability to open the file.
 365
 366 FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors:
 367
 368 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
 369   encryption context format
 370 - ``ENODATA``: the file is not encrypted
 371 - ``ENOTTY``: this type of filesystem does not implement encryption
 372 - ``EOPNOTSUPP``: the kernel was not configured with encryption
 373   support for this filesystem
 374
 375 Note: if you only need to know whether a file is encrypted or not, on
 376 most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
 377 and check for FS_ENCRYPT_FL, or to use the statx() system call and
 378 check for STATX_ATTR_ENCRYPTED in stx_attributes.
 379
 380 Getting the per-filesystem salt
 381 -------------------------------
 382
 383 Some filesystems, such as ext4 and F2FS, also support the deprecated
 384 ioctl FS_IOC_GET_ENCRYPTION_PWSALT.  This ioctl retrieves a randomly
 385 generated 16-byte value stored in the filesystem superblock.  This
 386 value is intended to used as a salt when deriving an encryption key
 387 from a passphrase or other low-entropy user credential.
 388
 389 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated.  Instead, prefer to
 390 generate and manage any needed salt(s) in userspace.
 391
 392 Adding keys
 393 -----------
 394
 395 To provide a master key, userspace must add it to an appropriate
 396 keyring using the add_key() system call (see:
 397 ``Documentation/security/keys/core.rst``).  The key type must be
 398 "logon"; keys of this type are kept in kernel memory and cannot be
 399 read back by userspace.  The key description must be "fscrypt:"
 400 followed by the 16-character lower case hex representation of the
 401 ``master_key_descriptor`` that was set in the encryption policy.  The
 402 key payload must conform to the following structure::
 403
 404     #define FS_MAX_KEY_SIZE 64
 405
 406     struct fscrypt_key {
 407             u32 mode;
 408             u8 raw[FS_MAX_KEY_SIZE];
 409             u32 size;
 410     };
 411
 412 ``mode`` is ignored; just set it to 0.  The actual key is provided in
 413 ``raw`` with ``size`` indicating its size in bytes.  That is, the
 414 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
 415
 416 The key description prefix "fscrypt:" may alternatively be replaced
 417 with a filesystem-specific prefix such as "ext4:".  However, the
 418 filesystem-specific prefixes are deprecated and should not be used in
 419 new programs.
 420
 421 There are several different types of keyrings in which encryption keys
 422 may be placed, such as a session keyring, a user session keyring, or a
 423 user keyring.  Each key must be placed in a keyring that is "attached"
 424 to all processes that might need to access files encrypted with it, in
 425 the sense that request_key() will find the key.  Generally, if only
 426 processes belonging to a specific user need to access a given
 427 encrypted directory and no session keyring has been installed, then
 428 that directory's key should be placed in that user's user session
 429 keyring or user keyring.  Otherwise, a session keyring should be
 430 installed if needed, and the key should be linked into that session
 431 keyring, or in a keyring linked into that session keyring.
 432
 433 Note: introducing the complex visibility semantics of keyrings here
 434 was arguably a mistake --- especially given that by design, after any
 435 process successfully opens an encrypted file (thereby setting up the
 436 per-file key), possessing the keyring key is not actually required for
 437 any process to read/write the file until its in-memory inode is
 438 evicted.  In the future there probably should be a way to provide keys
 439 directly to the filesystem instead, which would make the intended
 440 semantics clearer.
 441
 442 Access semantics
 443 ================
 444
 445 With the key
 446 ------------
 447
 448 With the encryption key, encrypted regular files, directories, and
 449 symlinks behave very similarly to their unencrypted counterparts ---
 450 after all, the encryption is intended to be transparent.  However,
 451 astute users may notice some differences in behavior:
 452
 453 - Unencrypted files, or files encrypted with a different encryption
 454   policy (i.e. different key, modes, or flags), cannot be renamed or
 455   linked into an encrypted directory; see `Encryption policy
 456   enforcement`_.  Attempts to do so will fail with EXDEV.  However,
 457   encrypted files can be renamed within an encrypted directory, or
 458   into an unencrypted directory.
 459
 460   Note: "moving" an unencrypted file into an encrypted directory, e.g.
 461   with the `mv` program, is implemented in userspace by a copy
 462   followed by a delete.  Be aware that the original unencrypted data
 463   may remain recoverable from free space on the disk; prefer to keep
 464   all files encrypted from the very beginning.  The `shred` program
 465   may be used to overwrite the source files but isn't guaranteed to be
 466   effective on all filesystems and storage devices.
 467
 468 - Direct I/O is not supported on encrypted files.  Attempts to use
 469   direct I/O on such files will fall back to buffered I/O.
 470
 471 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE,
 472   FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported
 473   on encrypted files and will fail with EOPNOTSUPP.
 474
 475 - Online defragmentation of encrypted files is not supported.  The
 476   EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
 477   EOPNOTSUPP.
 478
 479 - The ext4 filesystem does not support data journaling with encrypted
 480   regular files.  It will fall back to ordered data mode instead.
 481
 482 - DAX (Direct Access) is not supported on encrypted files.
 483
 484 - The st_size of an encrypted symlink will not necessarily give the
 485   length of the symlink target as required by POSIX.  It will actually
 486   give the length of the ciphertext, which will be slightly longer
 487   than the plaintext due to NUL-padding and an extra 2-byte overhead.
 488
 489 - The maximum length of an encrypted symlink is 2 bytes shorter than
 490   the maximum length of an unencrypted symlink.  For example, on an
 491   EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
 492   to 4095 bytes long, while encrypted symlinks can only be up to 4093
 493   bytes long (both lengths excluding the terminating null).
 494
 495 Note that mmap *is* supported.  This is possible because the pagecache
 496 for an encrypted file contains the plaintext, not the ciphertext.
 497
 498 Without the key
 499 ---------------
 500
 501 Some filesystem operations may be performed on encrypted regular
 502 files, directories, and symlinks even before their encryption key has
 503 been provided:
 504
 505 - File metadata may be read, e.g. using stat().
 506
 507 - Directories may be listed, in which case the filenames will be
 508   listed in an encoded form derived from their ciphertext.  The
 509   current encoding algorithm is described in `Filename hashing and
 510   encoding`_.  The algorithm is subject to change, but it is
 511   guaranteed that the presented filenames will be no longer than
 512   NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
 513   will uniquely identify directory entries.
 514
 515   The ``.`` and ``..`` directory entries are special.  They are always
 516   present and are not encrypted or encoded.
 517
 518 - Files may be deleted.  That is, nondirectory files may be deleted
 519   with unlink() as usual, and empty directories may be deleted with
 520   rmdir() as usual.  Therefore, ``rm`` and ``rm -r`` will work as
 521   expected.
 522
 523 - Symlink targets may be read and followed, but they will be presented
 524   in encrypted form, similar to filenames in directories.  Hence, they
 525   are unlikely to point to anywhere useful.
 526
 527 Without the key, regular files cannot be opened or truncated.
 528 Attempts to do so will fail with ENOKEY.  This implies that any
 529 regular file operations that require a file descriptor, such as
 530 read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
 531
 532 Also without the key, files of any type (including directories) cannot
 533 be created or linked into an encrypted directory, nor can a name in an
 534 encrypted directory be the source or target of a rename, nor can an
 535 O_TMPFILE temporary file be created in an encrypted directory.  All
 536 such operations will fail with ENOKEY.
 537
 538 It is not currently possible to backup and restore encrypted files
 539 without the encryption key.  This would require special APIs which
 540 have not yet been implemented.
 541
 542 Encryption policy enforcement
 543 =============================
 544
 545 After an encryption policy has been set on a directory, all regular
 546 files, directories, and symbolic links created in that directory
 547 (recursively) will inherit that encryption policy.  Special files ---
 548 that is, named pipes, device nodes, and UNIX domain sockets --- will
 549 not be encrypted.
 550
 551 Except for those special files, it is forbidden to have unencrypted
 552 files, or files encrypted with a different encryption policy, in an
 553 encrypted directory tree.  Attempts to link or rename such a file into
 554 an encrypted directory will fail with EXDEV.  This is also enforced
 555 during ->lookup() to provide limited protection against offline
 556 attacks that try to disable or downgrade encryption in known locations
 557 where applications may later write sensitive data.  It is recommended
 558 that systems implementing a form of "verified boot" take advantage of
 559 this by validating all top-level encryption policies prior to access.
 560
 561 Implementation details
 562 ======================
 563
 564 Encryption context
 565 ------------------
 566
 567 An encryption policy is represented on-disk by a :c:type:`struct
 568 fscrypt_context`.  It is up to individual filesystems to decide where
 569 to store it, but normally it would be stored in a hidden extended
 570 attribute.  It should *not* be exposed by the xattr-related system
 571 calls such as getxattr() and setxattr() because of the special
 572 semantics of the encryption xattr.  (In particular, there would be
 573 much confusion if an encryption policy were to be added to or removed
 574 from anything other than an empty directory.)  The struct is defined
 575 as follows::
 576
 577     #define FS_KEY_DESCRIPTOR_SIZE  8
 578     #define FS_KEY_DERIVATION_NONCE_SIZE 16
 579
 580     struct fscrypt_context {
 581             u8 format;
 582             u8 contents_encryption_mode;
 583             u8 filenames_encryption_mode;
 584             u8 flags;
 585             u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
 586             u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
 587     };
 588
 589 Note that :c:type:`struct fscrypt_context` contains the same
 590 information as :c:type:`struct fscrypt_policy` (see `Setting an
 591 encryption policy`_), except that :c:type:`struct fscrypt_context`
 592 also contains a nonce.  The nonce is randomly generated by the kernel
 593 and is used to derive the inode's encryption key as described in
 594 `Per-file keys`_.
 595
 596 Data path changes
 597 -----------------
 598
 599 For the read path (->readpage()) of regular files, filesystems can
 600 read the ciphertext into the page cache and decrypt it in-place.  The
 601 page lock must be held until decryption has finished, to prevent the
 602 page from becoming visible to userspace prematurely.
 603
 604 For the write path (->writepage()) of regular files, filesystems
 605 cannot encrypt data in-place in the page cache, since the cached
 606 plaintext must be preserved.  Instead, filesystems must encrypt into a
 607 temporary buffer or "bounce page", then write out the temporary
 608 buffer.  Some filesystems, such as UBIFS, already use temporary
 609 buffers regardless of encryption.  Other filesystems, such as ext4 and
 610 F2FS, have to allocate bounce pages specially for encryption.
 611
 612 Filename hashing and encoding
 613 -----------------------------
 614
 615 Modern filesystems accelerate directory lookups by using indexed
 616 directories.  An indexed directory is organized as a tree keyed by
 617 filename hashes.  When a ->lookup() is requested, the filesystem
 618 normally hashes the filename being looked up so that it can quickly
 619 find the corresponding directory entry, if any.
 620
 621 With encryption, lookups must be supported and efficient both with and
 622 without the encryption key.  Clearly, it would not work to hash the
 623 plaintext filenames, since the plaintext filenames are unavailable
 624 without the key.  (Hashing the plaintext filenames would also make it
 625 impossible for the filesystem's fsck tool to optimize encrypted
 626 directories.)  Instead, filesystems hash the ciphertext filenames,
 627 i.e. the bytes actually stored on-disk in the directory entries.  When
 628 asked to do a ->lookup() with the key, the filesystem just encrypts
 629 the user-supplied name to get the ciphertext.
 630
 631 Lookups without the key are more complicated.  The raw ciphertext may
 632 contain the ``\0`` and ``/`` characters, which are illegal in
 633 filenames.  Therefore, readdir() must base64-encode the ciphertext for
 634 presentation.  For most filenames, this works fine; on ->lookup(), the
 635 filesystem just base64-decodes the user-supplied name to get back to
 636 the raw ciphertext.
 637
 638 However, for very long filenames, base64 encoding would cause the
 639 filename length to exceed NAME_MAX.  To prevent this, readdir()
 640 actually presents long filenames in an abbreviated form which encodes
 641 a strong "hash" of the ciphertext filename, along with the optional
 642 filesystem-specific hash(es) needed for directory lookups.  This
 643 allows the filesystem to still, with a high degree of confidence, map
 644 the filename given in ->lookup() back to a particular directory entry
 645 that was previously listed by readdir().  See :c:type:`struct
 646 fscrypt_digested_name` in the source for more details.
 647
 648 Note that the precise way that filenames are presented to userspace
 649 without the key is subject to change in the future.  It is only meant
 650 as a way to temporarily present valid filenames so that commands like
 651 ``rm -r`` work as expected on encrypted directories.
 652
 653 Tests
 654 =====
 655
 656 To test fscrypt, use xfstests, which is Linux's de facto standard
 657 filesystem test suite.  First, run all the tests in the "encrypt"
 658 group on the relevant filesystem(s).  For example, to test ext4 and
 659 f2fs encryption using `kvm-xfstests
 660 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
 661
 662     kvm-xfstests -c ext4,f2fs -g encrypt
 663
 664 UBIFS encryption can also be tested this way, but it should be done in
 665 a separate command, and it takes some time for kvm-xfstests to set up
 666 emulated UBI volumes::
 667
 668     kvm-xfstests -c ubifs -g encrypt
 669
 670 No tests should fail.  However, tests that use non-default encryption
 671 modes (e.g. generic/549 and generic/550) will be skipped if the needed
 672 algorithms were not built into the kernel's crypto API.  Also, tests
 673 that access the raw block device (e.g. generic/399, generic/548,
 674 generic/549, generic/550) will be skipped on UBIFS.
 675
 676 Besides running the "encrypt" group tests, for ext4 and f2fs it's also
 677 possible to run most xfstests with the "test_dummy_encryption" mount
 678 option.  This option causes all new files to be automatically
 679 encrypted with a dummy key, without having to make any API calls.
 680 This tests the encrypted I/O paths more thoroughly.  To do this with
 681 kvm-xfstests, use the "encrypt" filesystem configuration::
 682
 683     kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
 684
 685 Because this runs many more tests than "-g encrypt" does, it takes
 686 much longer to run; so also consider using `gce-xfstests
 687 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
 688 instead of kvm-xfstests::
 689
 690     gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto