fscrypt.rst

   1=====================================
   2Filesystem-level encryption (fscrypt)
   3=====================================
   4
   5Introduction
   6============
   7
   8fscrypt is a library which filesystems can hook into to support
   9transparent encryption of files and directories.
  10
  11Note: "fscrypt" in this document refers to the kernel-level portion,
  12implemented in ``fs/crypto/``, as opposed to the userspace tool
  13`fscrypt <https://github.com/google/fscrypt>`_.  This document only
  14covers the kernel-level portion.  For command-line examples of how to
  15use encryption, see the documentation for the userspace tool `fscrypt
  16<https://github.com/google/fscrypt>`_.  Also, it is recommended to use
  17the fscrypt userspace tool, or other existing userspace tools such as
  18`fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key
  19management system
  20<https://source.android.com/security/encryption/file-based>`_, over
  21using the kernel's API directly.  Using existing tools reduces the
  22chance of introducing your own security bugs.  (Nevertheless, for
  23completeness this documentation covers the kernel's API anyway.)
  24
  25Unlike dm-crypt, fscrypt operates at the filesystem level rather than
  26at the block device level.  This allows it to encrypt different files
  27with different keys and to have unencrypted files on the same
  28filesystem.  This is useful for multi-user systems where each user's
  29data-at-rest needs to be cryptographically isolated from the others.
  30However, except for filenames, fscrypt does not encrypt filesystem
  31metadata.
  32
  33Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated
  34directly into supported filesystems --- currently ext4, F2FS, UBIFS,
  35and CephFS.  This allows encrypted files to be read and written
  36without caching both the decrypted and encrypted pages in the
  37pagecache, thereby nearly halving the memory used and bringing it in
  38line with unencrypted files.  Similarly, half as many dentries and
  39inodes are needed.  eCryptfs also limits encrypted filenames to 143
  40bytes, causing application compatibility issues; fscrypt allows the
  41full 255 bytes (NAME_MAX).  Finally, unlike eCryptfs, the fscrypt API
  42can be used by unprivileged users, with no need to mount anything.
  43
  44fscrypt does not support encrypting files in-place.  Instead, it
  45supports marking an empty directory as encrypted.  Then, after
  46userspace provides the key, all regular files, directories, and
  47symbolic links created in that directory tree are transparently
  48encrypted.
  49
  50Threat model
  51============
  52
  53Offline attacks
  54---------------
  55
  56Provided that userspace chooses a strong encryption key, fscrypt
  57protects the confidentiality of file contents and filenames in the
  58event of a single point-in-time permanent offline compromise of the
  59block device content.  fscrypt does not protect the confidentiality of
  60non-filename metadata, e.g. file sizes, file permissions, file
  61timestamps, and extended attributes.  Also, the existence and location
  62of holes (unallocated blocks which logically contain all zeroes) in
  63files is not protected.
  64
  65fscrypt is not guaranteed to protect confidentiality or authenticity
  66if an attacker is able to manipulate the filesystem offline prior to
  67an authorized user later accessing the filesystem.
  68
  69Online attacks
  70--------------
  71
  72fscrypt (and storage encryption in general) can only provide limited
  73protection against online attacks.  In detail:
  74
  75Side-channel attacks
  76~~~~~~~~~~~~~~~~~~~~
  77
  78fscrypt is only resistant to side-channel attacks, such as timing or
  79electromagnetic attacks, to the extent that the underlying Linux
  80Cryptographic API algorithms or inline encryption hardware are.  If a
  81vulnerable algorithm is used, such as a table-based implementation of
  82AES, it may be possible for an attacker to mount a side channel attack
  83against the online system.  Side channel attacks may also be mounted
  84against applications consuming decrypted data.
  85
  86Unauthorized file access
  87~~~~~~~~~~~~~~~~~~~~~~~~
  88
  89After an encryption key has been added, fscrypt does not hide the
  90plaintext file contents or filenames from other users on the same
  91system.  Instead, existing access control mechanisms such as file mode
  92bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose.
  93
  94(For the reasoning behind this, understand that while the key is
  95added, the confidentiality of the data, from the perspective of the
  96system itself, is *not* protected by the mathematical properties of
  97encryption but rather only by the correctness of the kernel.
  98Therefore, any encryption-specific access control checks would merely
  99be enforced by kernel *code* and therefore would be largely redundant
 100with the wide variety of access control mechanisms already available.)
 101
 102Read-only kernel memory compromise
 103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 104
 105Unless `hardware-wrapped keys`_ are used, an attacker who gains the
 106ability to read from arbitrary kernel memory, e.g. by mounting a
 107physical attack or by exploiting a kernel security vulnerability, can
 108compromise all fscrypt keys that are currently in-use.  This also
 109extends to cold boot attacks; if the system is suddenly powered off,
 110keys the system was using may remain in memory for a short time.
 111
 112However, if hardware-wrapped keys are used, then the fscrypt master
 113keys and file contents encryption keys (but not other types of fscrypt
 114subkeys such as filenames encryption keys) are protected from
 115compromises of arbitrary kernel memory.
 116
 117In addition, fscrypt allows encryption keys to be removed from the
 118kernel, which may protect them from later compromise.
 119
 120In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the
 121FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
 122encryption key from kernel memory.  If it does so, it will also try to
 123evict all cached inodes which had been "unlocked" using the key,
 124thereby wiping their per-file keys and making them once again appear
 125"locked", i.e. in ciphertext or encrypted form.
 126
 127However, these ioctls have some limitations:
 128
 129- Per-file keys for in-use files will *not* be removed or wiped.
 130  Therefore, for maximum effect, userspace should close the relevant
 131  encrypted files and directories before removing a master key, as
 132  well as kill any processes whose working directory is in an affected
 133  encrypted directory.
 134
 135- The kernel cannot magically wipe copies of the master key(s) that
 136  userspace might have as well.  Therefore, userspace must wipe all
 137  copies of the master key(s) it makes as well; normally this should
 138  be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting
 139  for FS_IOC_REMOVE_ENCRYPTION_KEY.  Naturally, the same also applies
 140  to all higher levels in the key hierarchy.  Userspace should also
 141  follow other security precautions such as mlock()ing memory
 142  containing keys to prevent it from being swapped out.
 143
 144- In general, decrypted contents and filenames in the kernel VFS
 145  caches are freed but not wiped.  Therefore, portions thereof may be
 146  recoverable from freed memory, even after the corresponding key(s)
 147  were wiped.  To partially solve this, you can add init_on_free=1 to
 148  your kernel command line.  However, this has a performance cost.
 149
 150- Secret keys might still exist in CPU registers or in other places
 151  not explicitly considered here.
 152
 153Full system compromise
 154~~~~~~~~~~~~~~~~~~~~~~
 155
 156An attacker who gains "root" access and/or the ability to execute
 157arbitrary kernel code can freely exfiltrate data that is protected by
 158any in-use fscrypt keys.  Thus, usually fscrypt provides no meaningful
 159protection in this scenario.  (Data that is protected by a key that is
 160absent throughout the entire attack remains protected, modulo the
 161limitations of key removal mentioned above in the case where the key
 162was removed prior to the attack.)
 163
 164However, if `hardware-wrapped keys`_ are used, such attackers will be
 165unable to exfiltrate the master keys or file contents keys in a form
 166that will be usable after the system is powered off.  This may be
 167useful if the attacker is significantly time-limited and/or
 168bandwidth-limited, so they can only exfiltrate some data and need to
 169rely on a later offline attack to exfiltrate the rest of it.
 170
 171Limitations of v1 policies
 172~~~~~~~~~~~~~~~~~~~~~~~~~~
 173
 174v1 encryption policies have some weaknesses with respect to online
 175attacks:
 176
 177- There is no verification that the provided master key is correct.
 178  Therefore, a malicious user can temporarily associate the wrong key
 179  with another user's encrypted files to which they have read-only
 180  access.  Because of filesystem caching, the wrong key will then be
 181  used by the other user's accesses to those files, even if the other
 182  user has the correct key in their own keyring.  This violates the
 183  meaning of "read-only access".
 184
 185- A compromise of a per-file key also compromises the master key from
 186  which it was derived.
 187
 188- Non-root users cannot securely remove encryption keys.
 189
 190All the above problems are fixed with v2 encryption policies.  For
 191this reason among others, it is recommended to use v2 encryption
 192policies on all new encrypted directories.
 193
 194Key hierarchy
 195=============
 196
 197Note: this section assumes the use of raw keys rather than
 198hardware-wrapped keys.  The use of hardware-wrapped keys modifies the
 199key hierarchy slightly.  For details, see `Hardware-wrapped keys`_.
 200
 201Master Keys
 202-----------
 203
 204Each encrypted directory tree is protected by a *master key*.  Master
 205keys can be up to 64 bytes long, and must be at least as long as the
 206greater of the security strength of the contents and filenames
 207encryption modes being used.  For example, if any AES-256 mode is
 208used, the master key must be at least 256 bits, i.e. 32 bytes.  A
 209stricter requirement applies if the key is used by a v1 encryption
 210policy and AES-256-XTS is used; such keys must be 64 bytes.
 211
 212To "unlock" an encrypted directory tree, userspace must provide the
 213appropriate master key.  There can be any number of master keys, each
 214of which protects any number of directory trees on any number of
 215filesystems.
 216
 217Master keys must be real cryptographic keys, i.e. indistinguishable
 218from random bytestrings of the same length.  This implies that users
 219**must not** directly use a password as a master key, zero-pad a
 220shorter key, or repeat a shorter key.  Security cannot be guaranteed
 221if userspace makes any such error, as the cryptographic proofs and
 222analysis would no longer apply.
 223
 224Instead, users should generate master keys either using a
 225cryptographically secure random number generator, or by using a KDF
 226(Key Derivation Function).  The kernel does not do any key stretching;
 227therefore, if userspace derives the key from a low-entropy secret such
 228as a passphrase, it is critical that a KDF designed for this purpose
 229be used, such as scrypt, PBKDF2, or Argon2.
 230
 231Key derivation function
 232-----------------------
 233
 234With one exception, fscrypt never uses the master key(s) for
 235encryption directly.  Instead, they are only used as input to a KDF
 236(Key Derivation Function) to derive the actual keys.
 237
 238The KDF used for a particular master key differs depending on whether
 239the key is used for v1 encryption policies or for v2 encryption
 240policies.  Users **must not** use the same key for both v1 and v2
 241encryption policies.  (No real-world attack is currently known on this
 242specific case of key reuse, but its security cannot be guaranteed
 243since the cryptographic proofs and analysis would no longer apply.)
 244
 245For v1 encryption policies, the KDF only supports deriving per-file
 246encryption keys.  It works by encrypting the master key with
 247AES-128-ECB, using the file's 16-byte nonce as the AES key.  The
 248resulting ciphertext is used as the derived key.  If the ciphertext is
 249longer than needed, then it is truncated to the needed length.
 250
 251For v2 encryption policies, the KDF is HKDF-SHA512.  The master key is
 252passed as the "input keying material", no salt is used, and a distinct
 253"application-specific information string" is used for each distinct
 254key to be derived.  For example, when a per-file encryption key is
 255derived, the application-specific information string is the file's
 256nonce prefixed with "fscrypt\\0" and a context byte.  Different
 257context bytes are used for other types of derived keys.
 258
 259HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
 260HKDF is more flexible, is nonreversible, and evenly distributes
 261entropy from the master key.  HKDF is also standardized and widely
 262used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
 263
 264Per-file encryption keys
 265------------------------
 266
 267Since each master key can protect many files, it is necessary to
 268"tweak" the encryption of each file so that the same plaintext in two
 269files doesn't map to the same ciphertext, or vice versa.  In most
 270cases, fscrypt does this by deriving per-file keys.  When a new
 271encrypted inode (regular file, directory, or symlink) is created,
 272fscrypt randomly generates a 16-byte nonce and stores it in the
 273inode's encryption xattr.  Then, it uses a KDF (as described in `Key
 274derivation function`_) to derive the file's key from the master key
 275and nonce.
 276
 277Key derivation was chosen over key wrapping because wrapped keys would
 278require larger xattrs which would be less likely to fit in-line in the
 279filesystem's inode table, and there didn't appear to be any
 280significant advantages to key wrapping.  In particular, currently
 281there is no requirement to support unlocking a file with multiple
 282alternative master keys or to support rotating master keys.  Instead,
 283the master keys may be wrapped in userspace, e.g. as is done by the
 284`fscrypt <https://github.com/google/fscrypt>`_ tool.
 285
 286DIRECT_KEY policies
 287-------------------
 288
 289The Adiantum encryption mode (see `Encryption modes and usage`_) is
 290suitable for both contents and filenames encryption, and it accepts
 291long IVs --- long enough to hold both an 8-byte data unit index and a
 29216-byte per-file nonce.  Also, the overhead of each Adiantum key is
 293greater than that of an AES-256-XTS key.
 294
 295Therefore, to improve performance and save memory, for Adiantum a
 296"direct key" configuration is supported.  When the user has enabled
 297this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
 298per-file encryption keys are not used.  Instead, whenever any data
 299(contents or filenames) is encrypted, the file's 16-byte nonce is
 300included in the IV.  Moreover:
 301
 302- For v1 encryption policies, the encryption is done directly with the
 303  master key.  Because of this, users **must not** use the same master
 304  key for any other purpose, even for other v1 policies.
 305
 306- For v2 encryption policies, the encryption is done with a per-mode
 307  key derived using the KDF.  Users may use the same master key for
 308  other v2 encryption policies.
 309
 310IV_INO_LBLK_64 policies
 311-----------------------
 312
 313When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy,
 314the encryption keys are derived from the master key, encryption mode
 315number, and filesystem UUID.  This normally results in all files
 316protected by the same master key sharing a single contents encryption
 317key and a single filenames encryption key.  To still encrypt different
 318files' data differently, inode numbers are included in the IVs.
 319Consequently, shrinking the filesystem may not be allowed.
 320
 321This format is optimized for use with inline encryption hardware
 322compliant with the UFS standard, which supports only 64 IV bits per
 323I/O request and may have only a small number of keyslots.
 324
 325IV_INO_LBLK_32 policies
 326-----------------------
 327
 328IV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for
 329IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
 330SipHash key is derived from the master key) and added to the file data
 331unit index mod 2^32 to produce a 32-bit IV.
 332
 333This format is optimized for use with inline encryption hardware
 334compliant with the eMMC v5.2 standard, which supports only 32 IV bits
 335per I/O request and may have only a small number of keyslots.  This
 336format results in some level of IV reuse, so it should only be used
 337when necessary due to hardware limitations.
 338
 339Key identifiers
 340---------------
 341
 342For master keys used for v2 encryption policies, a unique 16-byte "key
 343identifier" is also derived using the KDF.  This value is stored in
 344the clear, since it is needed to reliably identify the key itself.
 345
 346Dirhash keys
 347------------
 348
 349For directories that are indexed using a secret-keyed dirhash over the
 350plaintext filenames, the KDF is also used to derive a 128-bit
 351SipHash-2-4 key per directory in order to hash filenames.  This works
 352just like deriving a per-file encryption key, except that a different
 353KDF context is used.  Currently, only casefolded ("case-insensitive")
 354encrypted directories use this style of hashing.
 355
 356Encryption modes and usage
 357==========================
 358
 359fscrypt allows one encryption mode to be specified for file contents
 360and one encryption mode to be specified for filenames.  Different
 361directory trees are permitted to use different encryption modes.
 362
 363Supported modes
 364---------------
 365
 366Currently, the following pairs of encryption modes are supported:
 367
 368- AES-256-XTS for contents and AES-256-CBC-CTS for filenames
 369- AES-256-XTS for contents and AES-256-HCTR2 for filenames
 370- Adiantum for both contents and filenames
 371- AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames
 372- SM4-XTS for contents and SM4-CBC-CTS for filenames
 373
 374Note: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS.
 375So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.
 376
 377Authenticated encryption modes are not currently supported because of
 378the difficulty of dealing with ciphertext expansion.  Therefore,
 379contents encryption uses a block cipher in `XTS mode
 380<https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or
 381`CBC-ESSIV mode
 382<https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_,
 383or a wide-block cipher.  Filenames encryption uses a
 384block cipher in `CBC-CTS mode
 385<https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
 386cipher.
 387
 388The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default.
 389It is also the only option that is *guaranteed* to always be supported
 390if the kernel supports fscrypt at all; see `Kernel config options`_.
 391
 392The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
 393upgrades the filenames encryption to use a wide-block cipher.  (A
 394*wide-block cipher*, also called a tweakable super-pseudorandom
 395permutation, has the property that changing one bit scrambles the
 396entire result.)  As described in `Filenames encryption`_, a wide-block
 397cipher is the ideal mode for the problem domain, though CBC-CTS is the
 398"least bad" choice among the alternatives.  For more information about
 399HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_.
 400
 401Adiantum is recommended on systems where AES is too slow due to lack
 402of hardware acceleration for AES.  Adiantum is a wide-block cipher
 403that uses XChaCha12 and AES-256 as its underlying components.  Most of
 404the work is done by XChaCha12, which is much faster than AES when AES
 405acceleration is unavailable.  For more information about Adiantum, see
 406`the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_.
 407
 408The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair was added to try to
 409provide a more efficient option for systems that lack AES instructions
 410in the CPU but do have a non-inline crypto engine such as CAAM or CESA
 411that supports AES-CBC (and not AES-XTS).  This is deprecated.  It has
 412been shown that just doing AES on the CPU is actually faster.
 413Moreover, Adiantum is faster still and is recommended on such systems.
 414
 415The remaining mode pairs are the "national pride ciphers":
 416
 417- (SM4-XTS, SM4-CBC-CTS)
 418
 419Generally speaking, these ciphers aren't "bad" per se, but they
 420receive limited security review compared to the usual choices such as
 421AES and ChaCha.  They also don't bring much new to the table.  It is
 422suggested to only use these ciphers where their use is mandated.
 423
 424Kernel config options
 425---------------------
 426
 427Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in
 428only the basic support from the crypto API needed to use AES-256-XTS
 429and AES-256-CBC-CTS encryption.  For optimal performance, it is
 430strongly recommended to also enable any available platform-specific
 431kconfig options that provide acceleration for the algorithm(s) you
 432wish to use.  Support for any "non-default" encryption modes typically
 433requires extra kconfig options as well.
 434
 435Below, some relevant options are listed by encryption mode.  Note,
 436acceleration options not listed below may be available for your
 437platform; refer to the kconfig menus.  File contents encryption can
 438also be configured to use inline encryption hardware instead of the
 439kernel crypto API (see `Inline encryption support`_); in that case,
 440the file contents mode doesn't need to supported in the kernel crypto
 441API, but the filenames mode still does.
 442
 443- AES-256-XTS and AES-256-CBC-CTS
 444    - Recommended:
 445        - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
 446        - x86: CONFIG_CRYPTO_AES_NI_INTEL
 447
 448- AES-256-HCTR2
 449    - Mandatory:
 450        - CONFIG_CRYPTO_HCTR2
 451    - Recommended:
 452        - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
 453        - x86: CONFIG_CRYPTO_AES_NI_INTEL
 454
 455- Adiantum
 456    - Mandatory:
 457        - CONFIG_CRYPTO_ADIANTUM
 458    - Recommended:
 459        - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
 460        - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
 461        - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
 462        - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
 463
 464- AES-128-CBC-ESSIV and AES-128-CBC-CTS:
 465    - Mandatory:
 466        - CONFIG_CRYPTO_ESSIV
 467        - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
 468    - Recommended:
 469        - AES-CBC acceleration
 470
 471Contents encryption
 472-------------------
 473
 474For contents encryption, each file's contents is divided into "data
 475units".  Each data unit is encrypted independently.  The IV for each
 476data unit incorporates the zero-based index of the data unit within
 477the file.  This ensures that each data unit within a file is encrypted
 478differently, which is essential to prevent leaking information.
 479
 480Note: the encryption depending on the offset into the file means that
 481operations like "collapse range" and "insert range" that rearrange the
 482extent mapping of files are not supported on encrypted files.
 483
 484There are two cases for the sizes of the data units:
 485
 486* Fixed-size data units.  This is how all filesystems other than UBIFS
 487  work.  A file's data units are all the same size; the last data unit
 488  is zero-padded if needed.  By default, the data unit size is equal
 489  to the filesystem block size.  On some filesystems, users can select
 490  a sub-block data unit size via the ``log2_data_unit_size`` field of
 491  the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_.
 492
 493* Variable-size data units.  This is what UBIFS does.  Each "UBIFS
 494  data node" is treated as a crypto data unit.  Each contains variable
 495  length, possibly compressed data, zero-padded to the next 16-byte
 496  boundary.  Users cannot select a sub-block data unit size on UBIFS.
 497
 498In the case of compression + encryption, the compressed data is
 499encrypted.  UBIFS compression works as described above.  f2fs
 500compression works a bit differently; it compresses a number of
 501filesystem blocks into a smaller number of filesystem blocks.
 502Therefore a f2fs-compressed file still uses fixed-size data units, and
 503it is encrypted in a similar way to a file containing holes.
 504
 505As mentioned in `Key hierarchy`_, the default encryption setting uses
 506per-file keys.  In this case, the IV for each data unit is simply the
 507index of the data unit in the file.  However, users can select an
 508encryption setting that does not use per-file keys.  For these, some
 509kind of file identifier is incorporated into the IVs as follows:
 510
 511- With `DIRECT_KEY policies`_, the data unit index is placed in bits
 512  0-63 of the IV, and the file's nonce is placed in bits 64-191.
 513
 514- With `IV_INO_LBLK_64 policies`_, the data unit index is placed in
 515  bits 0-31 of the IV, and the file's inode number is placed in bits
 516  32-63.  This setting is only allowed when data unit indices and
 517  inode numbers fit in 32 bits.
 518
 519- With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed
 520  and added to the data unit index.  The resulting value is truncated
 521  to 32 bits and placed in bits 0-31 of the IV.  This setting is only
 522  allowed when data unit indices and inode numbers fit in 32 bits.
 523
 524The byte order of the IV is always little endian.
 525
 526If the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an
 527ESSIV layer is automatically included.  In this case, before the IV is
 528passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
 529key is the SHA-256 hash of the file's contents encryption key.
 530
 531Filenames encryption
 532--------------------
 533
 534For filenames, each full filename is encrypted at once.  Because of
 535the requirements to retain support for efficient directory lookups and
 536filenames of up to 255 bytes, the same IV is used for every filename
 537in a directory.
 538
 539However, each encrypted directory still uses a unique key, or
 540alternatively has the file's nonce (for `DIRECT_KEY policies`_) or
 541inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs.
 542Thus, IV reuse is limited to within a single directory.
 543
 544With CBC-CTS, the IV reuse means that when the plaintext filenames share a
 545common prefix at least as long as the cipher block size (16 bytes for AES), the
 546corresponding encrypted filenames will also share a common prefix.  This is
 547undesirable.  Adiantum and HCTR2 do not have this weakness, as they are
 548wide-block encryption modes.
 549
 550All supported filenames encryption modes accept any plaintext length
 551>= 16 bytes; cipher block alignment is not required.  However,
 552filenames shorter than 16 bytes are NUL-padded to 16 bytes before
 553being encrypted.  In addition, to reduce leakage of filename lengths
 554via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
 55516, or 32-byte boundary (configurable).  32 is recommended since this
 556provides the best confidentiality, at the cost of making directory
 557entries consume slightly more space.  Note that since NUL (``\0``) is
 558not otherwise a valid character in filenames, the padding will never
 559produce duplicate plaintexts.
 560
 561Symbolic link targets are considered a type of filename and are
 562encrypted in the same way as filenames in directory entries, except
 563that IV reuse is not a problem as each symlink has its own inode.
 564
 565User API
 566========
 567
 568Setting an encryption policy
 569----------------------------
 570
 571FS_IOC_SET_ENCRYPTION_POLICY
 572~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 573
 574The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
 575empty directory or verifies that a directory or regular file already
 576has the specified encryption policy.  It takes in a pointer to
 577struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
 578follows::
 579
 580    #define FSCRYPT_POLICY_V1               0
 581    #define FSCRYPT_KEY_DESCRIPTOR_SIZE     8
 582    struct fscrypt_policy_v1 {
 583            __u8 version;
 584            __u8 contents_encryption_mode;
 585            __u8 filenames_encryption_mode;
 586            __u8 flags;
 587            __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
 588    };
 589    #define fscrypt_policy  fscrypt_policy_v1
 590
 591    #define FSCRYPT_POLICY_V2               2
 592    #define FSCRYPT_KEY_IDENTIFIER_SIZE     16
 593    struct fscrypt_policy_v2 {
 594            __u8 version;
 595            __u8 contents_encryption_mode;
 596            __u8 filenames_encryption_mode;
 597            __u8 flags;
 598            __u8 log2_data_unit_size;
 599            __u8 __reserved[3];
 600            __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
 601    };
 602
 603This structure must be initialized as follows:
 604
 605- ``version`` must be FSCRYPT_POLICY_V1 (0) if
 606  struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if
 607  struct fscrypt_policy_v2 is used. (Note: we refer to the original
 608  policy version as "v1", though its version code is really 0.)
 609  For new encrypted directories, use v2 policies.
 610
 611- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
 612  be set to constants from ``<linux/fscrypt.h>`` which identify the
 613  encryption modes to use.  If unsure, use FSCRYPT_MODE_AES_256_XTS
 614  (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
 615  (4) for ``filenames_encryption_mode``.  For details, see `Encryption
 616  modes and usage`_.
 617
 618  v1 encryption policies only support three combinations of modes:
 619  (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS),
 620  (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and
 621  (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM).  v2 policies support
 622  all combinations documented in `Supported modes`_.
 623
 624- ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
 625
 626  - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
 627    encrypting filenames.  If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32
 628    (0x3).
 629  - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
 630  - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
 631    policies`_.
 632  - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
 633    policies`_.
 634
 635  v1 encryption policies only support the PAD_* and DIRECT_KEY flags.
 636  The other flags are only supported by v2 encryption policies.
 637
 638  The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are
 639  mutually exclusive.
 640
 641- ``log2_data_unit_size`` is the log2 of the data unit size in bytes,
 642  or 0 to select the default data unit size.  The data unit size is
 643  the granularity of file contents encryption.  For example, setting
 644  ``log2_data_unit_size`` to 12 causes file contents be passed to the
 645  underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
 646  data units, each with its own IV.
 647
 648  Not all filesystems support setting ``log2_data_unit_size``.  ext4
 649  and f2fs support it since Linux v6.7.  On filesystems that support
 650  it, the supported nonzero values are 9 through the log2 of the
 651  filesystem block size, inclusively.  The default value of 0 selects
 652  the filesystem block size.
 653
 654  The main use case for ``log2_data_unit_size`` is for selecting a
 655  data unit size smaller than the filesystem block size for
 656  compatibility with inline encryption hardware that only supports
 657  smaller data unit sizes.  ``/sys/block/$disk/queue/crypto/`` may be
 658  useful for checking which data unit sizes are supported by a
 659  particular system's inline encryption hardware.
 660
 661  Leave this field zeroed unless you are certain you need it.  Using
 662  an unnecessarily small data unit size reduces performance.
 663
 664- For v2 encryption policies, ``__reserved`` must be zeroed.
 665
 666- For v1 encryption policies, ``master_key_descriptor`` specifies how
 667  to find the master key in a keyring; see `Adding keys`_.  It is up
 668  to userspace to choose a unique ``master_key_descriptor`` for each
 669  master key.  The e4crypt and fscrypt tools use the first 8 bytes of
 670  ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
 671  required.  Also, the master key need not be in the keyring yet when
 672  FS_IOC_SET_ENCRYPTION_POLICY is executed.  However, it must be added
 673  before any files can be created in the encrypted directory.
 674
 675  For v2 encryption policies, ``master_key_descriptor`` has been
 676  replaced with ``master_key_identifier``, which is longer and cannot
 677  be arbitrarily chosen.  Instead, the key must first be added using
 678  `FS_IOC_ADD_ENCRYPTION_KEY`_.  Then, the ``key_spec.u.identifier``
 679  the kernel returned in the struct fscrypt_add_key_arg must
 680  be used as the ``master_key_identifier`` in
 681  struct fscrypt_policy_v2.
 682
 683If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
 684verifies that the file is an empty directory.  If so, the specified
 685encryption policy is assigned to the directory, turning it into an
 686encrypted directory.  After that, and after providing the
 687corresponding master key as described in `Adding keys`_, all regular
 688files, directories (recursively), and symlinks created in the
 689directory will be encrypted, inheriting the same encryption policy.
 690The filenames in the directory's entries will be encrypted as well.
 691
 692Alternatively, if the file is already encrypted, then
 693FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
 694policy exactly matches the actual one.  If they match, then the ioctl
 695returns 0.  Otherwise, it fails with EEXIST.  This works on both
 696regular files and directories, including nonempty directories.
 697
 698When a v2 encryption policy is assigned to a directory, it is also
 699required that either the specified key has been added by the current
 700user or that the caller has CAP_FOWNER in the initial user namespace.
 701(This is needed to prevent a user from encrypting their data with
 702another user's key.)  The key must remain added while
 703FS_IOC_SET_ENCRYPTION_POLICY is executing.  However, if the new
 704encrypted directory does not need to be accessed immediately, then the
 705key can be removed right away afterwards.
 706
 707Note that the ext4 filesystem does not allow the root directory to be
 708encrypted, even if it is empty.  Users who want to encrypt an entire
 709filesystem with one key should consider using dm-crypt instead.
 710
 711FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
 712
 713- ``EACCES``: the file is not owned by the process's uid, nor does the
 714  process have the CAP_FOWNER capability in a namespace with the file
 715  owner's uid mapped
 716- ``EEXIST``: the file is already encrypted with an encryption policy
 717  different from the one specified
 718- ``EINVAL``: an invalid encryption policy was specified (invalid
 719  version, mode(s), or flags; or reserved bits were set); or a v1
 720  encryption policy was specified but the directory has the casefold
 721  flag enabled (casefolding is incompatible with v1 policies).
 722- ``ENOKEY``: a v2 encryption policy was specified, but the key with
 723  the specified ``master_key_identifier`` has not been added, nor does
 724  the process have the CAP_FOWNER capability in the initial user
 725  namespace
 726- ``ENOTDIR``: the file is unencrypted and is a regular file, not a
 727  directory
 728- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
 729- ``ENOTTY``: this type of filesystem does not implement encryption
 730- ``EOPNOTSUPP``: the kernel was not configured with encryption
 731  support for filesystems, or the filesystem superblock has not
 732  had encryption enabled on it.  (For example, to use encryption on an
 733  ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the
 734  kernel config, and the superblock must have had the "encrypt"
 735  feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
 736  encrypt``.)
 737- ``EPERM``: this directory may not be encrypted, e.g. because it is
 738  the root directory of an ext4 filesystem
 739- ``EROFS``: the filesystem is readonly
 740
 741Getting an encryption policy
 742----------------------------
 743
 744Two ioctls are available to get a file's encryption policy:
 745
 746- `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
 747- `FS_IOC_GET_ENCRYPTION_POLICY`_
 748
 749The extended (_EX) version of the ioctl is more general and is
 750recommended to use when possible.  However, on older kernels only the
 751original ioctl is available.  Applications should try the extended
 752version, and if it fails with ENOTTY fall back to the original
 753version.
 754
 755FS_IOC_GET_ENCRYPTION_POLICY_EX
 756~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 757
 758The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
 759policy, if any, for a directory or regular file.  No additional
 760permissions are required beyond the ability to open the file.  It
 761takes in a pointer to struct fscrypt_get_policy_ex_arg,
 762defined as follows::
 763
 764    struct fscrypt_get_policy_ex_arg {
 765            __u64 policy_size; /* input/output */
 766            union {
 767                    __u8 version;
 768                    struct fscrypt_policy_v1 v1;
 769                    struct fscrypt_policy_v2 v2;
 770            } policy; /* output */
 771    };
 772
 773The caller must initialize ``policy_size`` to the size available for
 774the policy struct, i.e. ``sizeof(arg.policy)``.
 775
 776On success, the policy struct is returned in ``policy``, and its
 777actual size is returned in ``policy_size``.  ``policy.version`` should
 778be checked to determine the version of policy returned.  Note that the
 779version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
 780
 781FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:
 782
 783- ``EINVAL``: the file is encrypted, but it uses an unrecognized
 784  encryption policy version
 785- ``ENODATA``: the file is not encrypted
 786- ``ENOTTY``: this type of filesystem does not implement encryption,
 787  or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
 788  (try FS_IOC_GET_ENCRYPTION_POLICY instead)
 789- ``EOPNOTSUPP``: the kernel was not configured with encryption
 790  support for this filesystem, or the filesystem superblock has not
 791  had encryption enabled on it
 792- ``EOVERFLOW``: the file is encrypted and uses a recognized
 793  encryption policy version, but the policy struct does not fit into
 794  the provided buffer
 795
 796Note: if you only need to know whether a file is encrypted or not, on
 797most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
 798and check for FS_ENCRYPT_FL, or to use the statx() system call and
 799check for STATX_ATTR_ENCRYPTED in stx_attributes.
 800
 801FS_IOC_GET_ENCRYPTION_POLICY
 802~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 803
 804The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
 805encryption policy, if any, for a directory or regular file.  However,
 806unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
 807FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
 808version.  It takes in a pointer directly to struct fscrypt_policy_v1
 809rather than struct fscrypt_get_policy_ex_arg.
 810
 811The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
 812for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
 813FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
 814encrypted using a newer encryption policy version.
 815
 816Getting the per-filesystem salt
 817-------------------------------
 818
 819Some filesystems, such as ext4 and F2FS, also support the deprecated
 820ioctl FS_IOC_GET_ENCRYPTION_PWSALT.  This ioctl retrieves a randomly
 821generated 16-byte value stored in the filesystem superblock.  This
 822value is intended to used as a salt when deriving an encryption key
 823from a passphrase or other low-entropy user credential.
 824
 825FS_IOC_GET_ENCRYPTION_PWSALT is deprecated.  Instead, prefer to
 826generate and manage any needed salt(s) in userspace.
 827
 828Getting a file's encryption nonce
 829---------------------------------
 830
 831Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported.
 832On encrypted files and directories it gets the inode's 16-byte nonce.
 833On unencrypted files and directories, it fails with ENODATA.
 834
 835This ioctl can be useful for automated tests which verify that the
 836encryption is being done correctly.  It is not needed for normal use
 837of fscrypt.
 838
 839Adding keys
 840-----------
 841
 842FS_IOC_ADD_ENCRYPTION_KEY
 843~~~~~~~~~~~~~~~~~~~~~~~~~
 844
 845The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
 846the filesystem, making all files on the filesystem which were
 847encrypted using that key appear "unlocked", i.e. in plaintext form.
 848It can be executed on any file or directory on the target filesystem,
 849but using the filesystem's root directory is recommended.  It takes in
 850a pointer to struct fscrypt_add_key_arg, defined as follows::
 851
 852    struct fscrypt_add_key_arg {
 853            struct fscrypt_key_specifier key_spec;
 854            __u32 raw_size;
 855            __u32 key_id;
 856    #define FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED 0x00000001
 857            __u32 flags;
 858            __u32 __reserved[7];
 859            __u8 raw[];
 860    };
 861
 862    #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR        1
 863    #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER        2
 864
 865    struct fscrypt_key_specifier {
 866            __u32 type;     /* one of FSCRYPT_KEY_SPEC_TYPE_* */
 867            __u32 __reserved;
 868            union {
 869                    __u8 __reserved[32]; /* reserve some extra space */
 870                    __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
 871                    __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
 872            } u;
 873    };
 874
 875    struct fscrypt_provisioning_key_payload {
 876            __u32 type;
 877            __u32 flags;
 878            __u8 raw[];
 879    };
 880
 881struct fscrypt_add_key_arg must be zeroed, then initialized
 882as follows:
 883
 884- If the key is being added for use by v1 encryption policies, then
 885  ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
 886  ``key_spec.u.descriptor`` must contain the descriptor of the key
 887  being added, corresponding to the value in the
 888  ``master_key_descriptor`` field of struct fscrypt_policy_v1.
 889  To add this type of key, the calling process must have the
 890  CAP_SYS_ADMIN capability in the initial user namespace.
 891
 892  Alternatively, if the key is being added for use by v2 encryption
 893  policies, then ``key_spec.type`` must contain
 894  FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is
 895  an *output* field which the kernel fills in with a cryptographic
 896  hash of the key.  To add this type of key, the calling process does
 897  not need any privileges.  However, the number of keys that can be
 898  added is limited by the user's quota for the keyrings service (see
 899  ``Documentation/security/keys/core.rst``).
 900
 901- ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
 902  Alternatively, if ``key_id`` is nonzero, this field must be 0, since
 903  in that case the size is implied by the specified Linux keyring key.
 904
 905- ``key_id`` is 0 if the key is given directly in the ``raw`` field.
 906  Otherwise ``key_id`` is the ID of a Linux keyring key of type
 907  "fscrypt-provisioning" whose payload is struct
 908  fscrypt_provisioning_key_payload whose ``raw`` field contains the
 909  key, whose ``type`` field matches ``key_spec.type``, and whose
 910  ``flags`` field matches ``flags``.  Since ``raw`` is
 911  variable-length, the total size of this key's payload must be
 912  ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the number
 913  of key bytes.  The process must have Search permission on this key.
 914
 915  Most users should leave this 0 and specify the key directly.  The
 916  support for specifying a Linux keyring key is intended mainly to
 917  allow re-adding keys after a filesystem is unmounted and re-mounted,
 918  without having to store the keys in userspace memory.
 919
 920- ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
 921
 922  - FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED: This denotes that the key is a
 923    hardware-wrapped key.  See `Hardware-wrapped keys`_.  This flag
 924    can't be used if FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR is used.
 925
 926- ``raw`` is a variable-length field which must contain the actual
 927  key, ``raw_size`` bytes long.  Alternatively, if ``key_id`` is
 928  nonzero, then this field is unused.  Note that despite being named
 929  ``raw``, if FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED is specified then it
 930  will contain a wrapped key, not a raw key.
 931
 932For v2 policy keys, the kernel keeps track of which user (identified
 933by effective user ID) added the key, and only allows the key to be
 934removed by that user --- or by "root", if they use
 935`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
 936
 937However, if another user has added the key, it may be desirable to
 938prevent that other user from unexpectedly removing it.  Therefore,
 939FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
 940*again*, even if it's already added by other user(s).  In this case,
 941FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
 942current user, rather than actually add the key again (but the key must
 943still be provided, as a proof of knowledge).
 944
 945FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
 946the key was either added or already exists.
 947
 948FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:
 949
 950- ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
 951  caller does not have the CAP_SYS_ADMIN capability in the initial
 952  user namespace; or the key was specified by Linux key ID but the
 953  process lacks Search permission on the key.
 954- ``EBADMSG``: invalid hardware-wrapped key
 955- ``EDQUOT``: the key quota for this user would be exceeded by adding
 956  the key
 957- ``EINVAL``: invalid key size or key specifier type, or reserved bits
 958  were set
 959- ``EKEYREJECTED``: the key was specified by Linux key ID, but the key
 960  has the wrong type
 961- ``ENOKEY``: the key was specified by Linux key ID, but no key exists
 962  with that ID
 963- ``ENOTTY``: this type of filesystem does not implement encryption
 964- ``EOPNOTSUPP``: the kernel was not configured with encryption
 965  support for this filesystem, or the filesystem superblock has not
 966  had encryption enabled on it; or a hardware wrapped key was specified
 967  but the filesystem does not support inline encryption or the hardware
 968  does not support hardware-wrapped keys
 969
 970Legacy method
 971~~~~~~~~~~~~~
 972
 973For v1 encryption policies, a master encryption key can also be
 974provided by adding it to a process-subscribed keyring, e.g. to a
 975session keyring, or to a user keyring if the user keyring is linked
 976into the session keyring.
 977
 978This method is deprecated (and not supported for v2 encryption
 979policies) for several reasons.  First, it cannot be used in
 980combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
 981so for removing a key a workaround such as keyctl_unlink() in
 982combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would
 983have to be used.  Second, it doesn't match the fact that the
 984locked/unlocked status of encrypted files (i.e. whether they appear to
 985be in plaintext form or in ciphertext form) is global.  This mismatch
 986has caused much confusion as well as real problems when processes
 987running under different UIDs, such as a ``sudo`` command, need to
 988access encrypted files.
 989
 990Nevertheless, to add a key to one of the process-subscribed keyrings,
 991the add_key() system call can be used (see:
 992``Documentation/security/keys/core.rst``).  The key type must be
 993"logon"; keys of this type are kept in kernel memory and cannot be
 994read back by userspace.  The key description must be "fscrypt:"
 995followed by the 16-character lower case hex representation of the
 996``master_key_descriptor`` that was set in the encryption policy.  The
 997key payload must conform to the following structure::
 998
 999    #define FSCRYPT_MAX_KEY_SIZE            64
1000
1001    struct fscrypt_key {
1002            __u32 mode;
1003            __u8 raw[FSCRYPT_MAX_KEY_SIZE];
1004            __u32 size;
1005    };
1006
1007``mode`` is ignored; just set it to 0.  The actual key is provided in
1008``raw`` with ``size`` indicating its size in bytes.  That is, the
1009bytes ``raw[0..size-1]`` (inclusive) are the actual key.
1010
1011The key description prefix "fscrypt:" may alternatively be replaced
1012with a filesystem-specific prefix such as "ext4:".  However, the
1013filesystem-specific prefixes are deprecated and should not be used in
1014new programs.
1015
1016Removing keys
1017-------------
1018
1019Two ioctls are available for removing a key that was added by
1020`FS_IOC_ADD_ENCRYPTION_KEY`_:
1021
1022- `FS_IOC_REMOVE_ENCRYPTION_KEY`_
1023- `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
1024
1025These two ioctls differ only in cases where v2 policy keys are added
1026or removed by non-root users.
1027
1028These ioctls don't work on keys that were added via the legacy
1029process-subscribed keyrings mechanism.
1030
1031Before using these ioctls, read the `Online attacks`_ section for a
1032discussion of the security goals and limitations of these ioctls.
1033
1034FS_IOC_REMOVE_ENCRYPTION_KEY
1035~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1036
1037The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
1038encryption key from the filesystem, and possibly removes the key
1039itself.  It can be executed on any file or directory on the target
1040filesystem, but using the filesystem's root directory is recommended.
1041It takes in a pointer to struct fscrypt_remove_key_arg, defined
1042as follows::
1043
1044    struct fscrypt_remove_key_arg {
1045            struct fscrypt_key_specifier key_spec;
1046    #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY      0x00000001
1047    #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS     0x00000002
1048            __u32 removal_status_flags;     /* output */
1049            __u32 __reserved[5];
1050    };
1051
1052This structure must be zeroed, then initialized as follows:
1053
1054- The key to remove is specified by ``key_spec``:
1055
1056    - To remove a key used by v1 encryption policies, set
1057      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
1058      in ``key_spec.u.descriptor``.  To remove this type of key, the
1059      calling process must have the CAP_SYS_ADMIN capability in the
1060      initial user namespace.
1061
1062    - To remove a key used by v2 encryption policies, set
1063      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
1064      in ``key_spec.u.identifier``.
1065
1066For v2 policy keys, this ioctl is usable by non-root users.  However,
1067to make this possible, it actually just removes the current user's
1068claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
1069Only after all claims are removed is the key really removed.
1070
1071For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000,
1072then the key will be "claimed" by uid 1000, and
1073FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000.  Or, if
1074both uids 1000 and 2000 added the key, then for each uid
1075FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim.  Only
1076once *both* are removed is the key really removed.  (Think of it like
1077unlinking a file that may have hard links.)
1078
1079If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
1080try to "lock" all files that had been unlocked with the key.  It won't
1081lock files that are still in-use, so this ioctl is expected to be used
1082in cooperation with userspace ensuring that none of the files are
1083still open.  However, if necessary, this ioctl can be executed again
1084later to retry locking any remaining files.
1085
1086FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed
1087(but may still have files remaining to be locked), the user's claim to
1088the key was removed, or the key was already removed but had files
1089remaining to be the locked so the ioctl retried locking them.  In any
1090of these cases, ``removal_status_flags`` is filled in with the
1091following informational status flags:
1092
1093- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
1094  are still in-use.  Not guaranteed to be set in the case where only
1095  the user's claim to the key was removed.
1096- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
1097  user's claim to the key was removed, not the key itself
1098
1099FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:
1100
1101- ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
1102  was specified, but the caller does not have the CAP_SYS_ADMIN
1103  capability in the initial user namespace
1104- ``EINVAL``: invalid key specifier type, or reserved bits were set
1105- ``ENOKEY``: the key object was not found at all, i.e. it was never
1106  added in the first place or was already fully removed including all
1107  files locked; or, the user does not have a claim to the key (but
1108  someone else does).
1109- ``ENOTTY``: this type of filesystem does not implement encryption
1110- ``EOPNOTSUPP``: the kernel was not configured with encryption
1111  support for this filesystem, or the filesystem superblock has not
1112  had encryption enabled on it
1113
1114FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
1115~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1116
1117FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
1118`FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
1119ALL_USERS version of the ioctl will remove all users' claims to the
1120key, not just the current user's.  I.e., the key itself will always be
1121removed, no matter how many users have added it.  This difference is
1122only meaningful if non-root users are adding and removing keys.
1123
1124Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires
1125"root", namely the CAP_SYS_ADMIN capability in the initial user
1126namespace.  Otherwise it will fail with EACCES.
1127
1128Getting key status
1129------------------
1130
1131FS_IOC_GET_ENCRYPTION_KEY_STATUS
1132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1133
1134The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
1135master encryption key.  It can be executed on any file or directory on
1136the target filesystem, but using the filesystem's root directory is
1137recommended.  It takes in a pointer to
1138struct fscrypt_get_key_status_arg, defined as follows::
1139
1140    struct fscrypt_get_key_status_arg {
1141            /* input */
1142            struct fscrypt_key_specifier key_spec;
1143            __u32 __reserved[6];
1144
1145            /* output */
1146    #define FSCRYPT_KEY_STATUS_ABSENT               1
1147    #define FSCRYPT_KEY_STATUS_PRESENT              2
1148    #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3
1149            __u32 status;
1150    #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF   0x00000001
1151            __u32 status_flags;
1152            __u32 user_count;
1153            __u32 __out_reserved[13];
1154    };
1155
1156The caller must zero all input fields, then fill in ``key_spec``:
1157
1158    - To get the status of a key for v1 encryption policies, set
1159      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
1160      in ``key_spec.u.descriptor``.
1161
1162    - To get the status of a key for v2 encryption policies, set
1163      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
1164      in ``key_spec.u.identifier``.
1165
1166On success, 0 is returned and the kernel fills in the output fields:
1167
1168- ``status`` indicates whether the key is absent, present, or
1169  incompletely removed.  Incompletely removed means that removal has
1170  been initiated, but some files are still in use; i.e.,
1171  `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational
1172  status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.
1173
1174- ``status_flags`` can contain the following flags:
1175
1176    - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1177      has added by the current user.  This is only set for keys
1178      identified by ``identifier`` rather than by ``descriptor``.
1179
1180- ``user_count`` specifies the number of users who have added the key.
1181  This is only set for keys identified by ``identifier`` rather than
1182  by ``descriptor``.
1183
1184FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:
1185
1186- ``EINVAL``: invalid key specifier type, or reserved bits were set
1187- ``ENOTTY``: this type of filesystem does not implement encryption
1188- ``EOPNOTSUPP``: the kernel was not configured with encryption
1189  support for this filesystem, or the filesystem superblock has not
1190  had encryption enabled on it
1191
1192Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful
1193for determining whether the key for a given encrypted directory needs
1194to be added before prompting the user for the passphrase needed to
1195derive the key.
1196
1197FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
1198the filesystem-level keyring, i.e. the keyring managed by
1199`FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_.  It
1200cannot get the status of a key that has only been added for use by v1
1201encryption policies using the legacy mechanism involving
1202process-subscribed keyrings.
1203
1204Access semantics
1205================
1206
1207With the key
1208------------
1209
1210With the encryption key, encrypted regular files, directories, and
1211symlinks behave very similarly to their unencrypted counterparts ---
1212after all, the encryption is intended to be transparent.  However,
1213astute users may notice some differences in behavior:
1214
1215- Unencrypted files, or files encrypted with a different encryption
1216  policy (i.e. different key, modes, or flags), cannot be renamed or
1217  linked into an encrypted directory; see `Encryption policy
1218  enforcement`_.  Attempts to do so will fail with EXDEV.  However,
1219  encrypted files can be renamed within an encrypted directory, or
1220  into an unencrypted directory.
1221
1222  Note: "moving" an unencrypted file into an encrypted directory, e.g.
1223  with the `mv` program, is implemented in userspace by a copy
1224  followed by a delete.  Be aware that the original unencrypted data
1225  may remain recoverable from free space on the disk; prefer to keep
1226  all files encrypted from the very beginning.  The `shred` program
1227  may be used to overwrite the source files but isn't guaranteed to be
1228  effective on all filesystems and storage devices.
1229
1230- Direct I/O is supported on encrypted files only under some
1231  circumstances.  For details, see `Direct I/O support`_.
1232
1233- The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1234  FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will
1235  fail with EOPNOTSUPP.
1236
1237- Online defragmentation of encrypted files is not supported.  The
1238  EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
1239  EOPNOTSUPP.
1240
1241- The ext4 filesystem does not support data journaling with encrypted
1242  regular files.  It will fall back to ordered data mode instead.
1243
1244- DAX (Direct Access) is not supported on encrypted files.
1245
1246- The maximum length of an encrypted symlink is 2 bytes shorter than
1247  the maximum length of an unencrypted symlink.  For example, on an
1248  EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
1249  to 4095 bytes long, while encrypted symlinks can only be up to 4093
1250  bytes long (both lengths excluding the terminating null).
1251
1252Note that mmap *is* supported.  This is possible because the pagecache
1253for an encrypted file contains the plaintext, not the ciphertext.
1254
1255Without the key
1256---------------
1257
1258Some filesystem operations may be performed on encrypted regular
1259files, directories, and symlinks even before their encryption key has
1260been added, or after their encryption key has been removed:
1261
1262- File metadata may be read, e.g. using stat().
1263
1264- Directories may be listed, in which case the filenames will be
1265  listed in an encoded form derived from their ciphertext.  The
1266  current encoding algorithm is described in `Filename hashing and
1267  encoding`_.  The algorithm is subject to change, but it is
1268  guaranteed that the presented filenames will be no longer than
1269  NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
1270  will uniquely identify directory entries.
1271
1272  The ``.`` and ``..`` directory entries are special.  They are always
1273  present and are not encrypted or encoded.
1274
1275- Files may be deleted.  That is, nondirectory files may be deleted
1276  with unlink() as usual, and empty directories may be deleted with
1277  rmdir() as usual.  Therefore, ``rm`` and ``rm -r`` will work as
1278  expected.
1279
1280- Symlink targets may be read and followed, but they will be presented
1281  in encrypted form, similar to filenames in directories.  Hence, they
1282  are unlikely to point to anywhere useful.
1283
1284Without the key, regular files cannot be opened or truncated.
1285Attempts to do so will fail with ENOKEY.  This implies that any
1286regular file operations that require a file descriptor, such as
1287read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
1288
1289Also without the key, files of any type (including directories) cannot
1290be created or linked into an encrypted directory, nor can a name in an
1291encrypted directory be the source or target of a rename, nor can an
1292O_TMPFILE temporary file be created in an encrypted directory.  All
1293such operations will fail with ENOKEY.
1294
1295It is not currently possible to backup and restore encrypted files
1296without the encryption key.  This would require special APIs which
1297have not yet been implemented.
1298
1299Encryption policy enforcement
1300=============================
1301
1302After an encryption policy has been set on a directory, all regular
1303files, directories, and symbolic links created in that directory
1304(recursively) will inherit that encryption policy.  Special files ---
1305that is, named pipes, device nodes, and UNIX domain sockets --- will
1306not be encrypted.
1307
1308Except for those special files, it is forbidden to have unencrypted
1309files, or files encrypted with a different encryption policy, in an
1310encrypted directory tree.  Attempts to link or rename such a file into
1311an encrypted directory will fail with EXDEV.  This is also enforced
1312during ->lookup() to provide limited protection against offline
1313attacks that try to disable or downgrade encryption in known locations
1314where applications may later write sensitive data.  It is recommended
1315that systems implementing a form of "verified boot" take advantage of
1316this by validating all top-level encryption policies prior to access.
1317
1318Inline encryption support
1319=========================
1320
1321Many newer systems (especially mobile SoCs) have *inline encryption
1322hardware* that can encrypt/decrypt data while it is on its way to/from
1323the storage device.  Linux supports inline encryption through a set of
1324extensions to the block layer called *blk-crypto*.  blk-crypto allows
1325filesystems to attach encryption contexts to bios (I/O requests) to
1326specify how the data will be encrypted or decrypted in-line.  For more
1327information about blk-crypto, see
1328:ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1329
1330On supported filesystems (currently ext4 and f2fs), fscrypt can use
1331blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1332contents.  To enable this, set CONFIG_FS_ENCRYPTION_INLINE_CRYPT=y in
1333the kernel configuration, and specify the "inlinecrypt" mount option
1334when mounting the filesystem.
1335
1336Note that the "inlinecrypt" mount option just specifies to use inline
1337encryption when possible; it doesn't force its use.  fscrypt will
1338still fall back to using the kernel crypto API on files where the
1339inline encryption hardware doesn't have the needed crypto capabilities
1340(e.g. support for the needed encryption algorithm and data unit size)
1341and where blk-crypto-fallback is unusable.  (For blk-crypto-fallback
1342to be usable, it must be enabled in the kernel configuration with
1343CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y, and the file must be
1344protected by a raw key rather than a hardware-wrapped key.)
1345
1346Currently fscrypt always uses the filesystem block size (which is
1347usually 4096 bytes) as the data unit size.  Therefore, it can only use
1348inline encryption hardware that supports that data unit size.
1349
1350Inline encryption doesn't affect the ciphertext or other aspects of
1351the on-disk format, so users may freely switch back and forth between
1352using "inlinecrypt" and not using "inlinecrypt".  An exception is that
1353files that are protected by a hardware-wrapped key can only be
1354encrypted/decrypted by the inline encryption hardware and therefore
1355can only be accessed when the "inlinecrypt" mount option is used.  For
1356more information about hardware-wrapped keys, see below.
1357
1358Hardware-wrapped keys
1359---------------------
1360
1361fscrypt supports using *hardware-wrapped keys* when the inline
1362encryption hardware supports it.  Such keys are only present in kernel
1363memory in wrapped (encrypted) form; they can only be unwrapped
1364(decrypted) by the inline encryption hardware and are temporally bound
1365to the current boot.  This prevents the keys from being compromised if
1366kernel memory is leaked.  This is done without limiting the number of
1367keys that can be used and while still allowing the execution of
1368cryptographic tasks that are tied to the same key but can't use inline
1369encryption hardware, e.g. filenames encryption.
1370
1371Note that hardware-wrapped keys aren't specific to fscrypt; they are a
1372block layer feature (part of *blk-crypto*).  For more details about
1373hardware-wrapped keys, see the block layer documentation at
1374:ref:`Documentation/block/inline-encryption.rst
1375<hardware_wrapped_keys>`.  The rest of this section just focuses on
1376the details of how fscrypt can use hardware-wrapped keys.
1377
1378fscrypt supports hardware-wrapped keys by allowing the fscrypt master
1379keys to be hardware-wrapped keys as an alternative to raw keys.  To
1380add a hardware-wrapped key with `FS_IOC_ADD_ENCRYPTION_KEY`_,
1381userspace must specify FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED in the
1382``flags`` field of struct fscrypt_add_key_arg and also in the
1383``flags`` field of struct fscrypt_provisioning_key_payload when
1384applicable.  The key must be in ephemerally-wrapped form, not
1385long-term wrapped form.
1386
1387Some limitations apply.  First, files protected by a hardware-wrapped
1388key are tied to the system's inline encryption hardware.  Therefore
1389they can only be accessed when the "inlinecrypt" mount option is used,
1390and they can't be included in portable filesystem images.  Second,
1391currently the hardware-wrapped key support is only compatible with
1392`IV_INO_LBLK_64 policies`_ and `IV_INO_LBLK_32 policies`_, as it
1393assumes that there is just one file contents encryption key per
1394fscrypt master key rather than one per file.  Future work may address
1395this limitation by passing per-file nonces down the storage stack to
1396allow the hardware to derive per-file keys.
1397
1398Implementation-wise, to encrypt/decrypt the contents of files that are
1399protected by a hardware-wrapped key, fscrypt uses blk-crypto,
1400attaching the hardware-wrapped key to the bio crypt contexts.  As is
1401the case with raw keys, the block layer will program the key into a
1402keyslot when it isn't already in one.  However, when programming a
1403hardware-wrapped key, the hardware doesn't program the given key
1404directly into a keyslot but rather unwraps it (using the hardware's
1405ephemeral wrapping key) and derives the inline encryption key from it.
1406The inline encryption key is the key that actually gets programmed
1407into a keyslot, and it is never exposed to software.
1408
1409However, fscrypt doesn't just do file contents encryption; it also
1410uses its master keys to derive filenames encryption keys, key
1411identifiers, and sometimes some more obscure types of subkeys such as
1412dirhash keys.  So even with file contents encryption out of the
1413picture, fscrypt still needs a raw key to work with.  To get such a
1414key from a hardware-wrapped key, fscrypt asks the inline encryption
1415hardware to derive a cryptographically isolated "software secret" from
1416the hardware-wrapped key.  fscrypt uses this "software secret" to key
1417its KDF to derive all subkeys other than file contents keys.
1418
1419Note that this implies that the hardware-wrapped key feature only
1420protects the file contents encryption keys.  It doesn't protect other
1421fscrypt subkeys such as filenames encryption keys.
1422
1423Direct I/O support
1424==================
1425
1426For direct I/O on an encrypted file to work, the following conditions
1427must be met (in addition to the conditions for direct I/O on an
1428unencrypted file):
1429
1430* The file must be using inline encryption.  Usually this means that
1431  the filesystem must be mounted with ``-o inlinecrypt`` and inline
1432  encryption hardware must be present.  However, a software fallback
1433  is also available.  For details, see `Inline encryption support`_.
1434
1435* The I/O request must be fully aligned to the filesystem block size.
1436  This means that the file position the I/O is targeting, the lengths
1437  of all I/O segments, and the memory addresses of all I/O buffers
1438  must be multiples of this value.  Note that the filesystem block
1439  size may be greater than the logical block size of the block device.
1440
1441If either of the above conditions is not met, then direct I/O on the
1442encrypted file will fall back to buffered I/O.
1443
1444Implementation details
1445======================
1446
1447Encryption context
1448------------------
1449
1450An encryption policy is represented on-disk by
1451struct fscrypt_context_v1 or struct fscrypt_context_v2.  It is up to
1452individual filesystems to decide where to store it, but normally it
1453would be stored in a hidden extended attribute.  It should *not* be
1454exposed by the xattr-related system calls such as getxattr() and
1455setxattr() because of the special semantics of the encryption xattr.
1456(In particular, there would be much confusion if an encryption policy
1457were to be added to or removed from anything other than an empty
1458directory.)  These structs are defined as follows::
1459
1460    #define FSCRYPT_FILE_NONCE_SIZE 16
1461
1462    #define FSCRYPT_KEY_DESCRIPTOR_SIZE  8
1463    struct fscrypt_context_v1 {
1464            u8 version;
1465            u8 contents_encryption_mode;
1466            u8 filenames_encryption_mode;
1467            u8 flags;
1468            u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
1469            u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
1470    };
1471
1472    #define FSCRYPT_KEY_IDENTIFIER_SIZE  16
1473    struct fscrypt_context_v2 {
1474            u8 version;
1475            u8 contents_encryption_mode;
1476            u8 filenames_encryption_mode;
1477            u8 flags;
1478            u8 log2_data_unit_size;
1479            u8 __reserved[3];
1480            u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
1481            u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
1482    };
1483
1484The context structs contain the same information as the corresponding
1485policy structs (see `Setting an encryption policy`_), except that the
1486context structs also contain a nonce.  The nonce is randomly generated
1487by the kernel and is used as KDF input or as a tweak to cause
1488different files to be encrypted differently; see `Per-file encryption
1489keys`_ and `DIRECT_KEY policies`_.
1490
1491Data path changes
1492-----------------
1493
1494When inline encryption is used, filesystems just need to associate
1495encryption contexts with bios to specify how the block layer or the
1496inline encryption hardware will encrypt/decrypt the file contents.
1497
1498When inline encryption isn't used, filesystems must encrypt/decrypt
1499the file contents themselves, as described below:
1500
1501For the read path (->read_folio()) of regular files, filesystems can
1502read the ciphertext into the page cache and decrypt it in-place.  The
1503folio lock must be held until decryption has finished, to prevent the
1504folio from becoming visible to userspace prematurely.
1505
1506For the write path (->writepages()) of regular files, filesystems
1507cannot encrypt data in-place in the page cache, since the cached
1508plaintext must be preserved.  Instead, filesystems must encrypt into a
1509temporary buffer or "bounce page", then write out the temporary
1510buffer.  Some filesystems, such as UBIFS, already use temporary
1511buffers regardless of encryption.  Other filesystems, such as ext4 and
1512F2FS, have to allocate bounce pages specially for encryption.
1513
1514Filename hashing and encoding
1515-----------------------------
1516
1517Modern filesystems accelerate directory lookups by using indexed
1518directories.  An indexed directory is organized as a tree keyed by
1519filename hashes.  When a ->lookup() is requested, the filesystem
1520normally hashes the filename being looked up so that it can quickly
1521find the corresponding directory entry, if any.
1522
1523With encryption, lookups must be supported and efficient both with and
1524without the encryption key.  Clearly, it would not work to hash the
1525plaintext filenames, since the plaintext filenames are unavailable
1526without the key.  (Hashing the plaintext filenames would also make it
1527impossible for the filesystem's fsck tool to optimize encrypted
1528directories.)  Instead, filesystems hash the ciphertext filenames,
1529i.e. the bytes actually stored on-disk in the directory entries.  When
1530asked to do a ->lookup() with the key, the filesystem just encrypts
1531the user-supplied name to get the ciphertext.
1532
1533Lookups without the key are more complicated.  The raw ciphertext may
1534contain the ``\0`` and ``/`` characters, which are illegal in
1535filenames.  Therefore, readdir() must base64url-encode the ciphertext
1536for presentation.  For most filenames, this works fine; on ->lookup(),
1537the filesystem just base64url-decodes the user-supplied name to get
1538back to the raw ciphertext.
1539
1540However, for very long filenames, base64url encoding would cause the
1541filename length to exceed NAME_MAX.  To prevent this, readdir()
1542actually presents long filenames in an abbreviated form which encodes
1543a strong "hash" of the ciphertext filename, along with the optional
1544filesystem-specific hash(es) needed for directory lookups.  This
1545allows the filesystem to still, with a high degree of confidence, map
1546the filename given in ->lookup() back to a particular directory entry
1547that was previously listed by readdir().  See
1548struct fscrypt_nokey_name in the source for more details.
1549
1550Note that the precise way that filenames are presented to userspace
1551without the key is subject to change in the future.  It is only meant
1552as a way to temporarily present valid filenames so that commands like
1553``rm -r`` work as expected on encrypted directories.
1554
1555Tests
1556=====
1557
1558To test fscrypt, use xfstests, which is Linux's de facto standard
1559filesystem test suite.  First, run all the tests in the "encrypt"
1560group on the relevant filesystem(s).  One can also run the tests
1561with the 'inlinecrypt' mount option to test the implementation for
1562inline encryption support.  For example, to test ext4 and
1563f2fs encryption using `kvm-xfstests
1564<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1565
1566    kvm-xfstests -c ext4,f2fs -g encrypt
1567    kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1568
1569UBIFS encryption can also be tested this way, but it should be done in
1570a separate command, and it takes some time for kvm-xfstests to set up
1571emulated UBI volumes::
1572
1573    kvm-xfstests -c ubifs -g encrypt
1574
1575No tests should fail.  However, tests that use non-default encryption
1576modes (e.g. generic/549 and generic/550) will be skipped if the needed
1577algorithms were not built into the kernel's crypto API.  Also, tests
1578that access the raw block device (e.g. generic/399, generic/548,
1579generic/549, generic/550) will be skipped on UBIFS.
1580
1581Besides running the "encrypt" group tests, for ext4 and f2fs it's also
1582possible to run most xfstests with the "test_dummy_encryption" mount
1583option.  This option causes all new files to be automatically
1584encrypted with a dummy key, without having to make any API calls.
1585This tests the encrypted I/O paths more thoroughly.  To do this with
1586kvm-xfstests, use the "encrypt" filesystem configuration::
1587
1588    kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1589    kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1590
1591Because this runs many more tests than "-g encrypt" does, it takes
1592much longer to run; so also consider using `gce-xfstests
1593<https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1594instead of kvm-xfstests::
1595
1596    gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1597    gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt