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

   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, and
  35UBIFS.  This allows encrypted files to be read and written without
  36caching both the decrypted and encrypted pages in the pagecache,
  37thereby nearly halving the memory used and bringing it in line with
  38unencrypted files.  Similarly, half as many dentries and inodes are
  39needed.  eCryptfs also limits encrypted filenames to 143 bytes,
  40causing application compatibility issues; fscrypt allows the full 255
  41bytes (NAME_MAX).  Finally, unlike eCryptfs, the fscrypt API can be
  42used 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, if any at all, 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 are.  If a vulnerable algorithm is used,
  81such as a table-based implementation of AES, it may be possible for an
  82attacker to mount a side channel attack against the online system.
  83Side channel attacks may also be mounted against applications
  84consuming 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
 102Kernel memory compromise
 103~~~~~~~~~~~~~~~~~~~~~~~~
 104
 105An attacker who compromises the system enough to read from arbitrary
 106memory, e.g. by mounting a physical attack or by exploiting a kernel
 107security vulnerability, can compromise all encryption keys that are
 108currently in use.
 109
 110However, fscrypt allows encryption keys to be removed from the kernel,
 111which may protect them from later compromise.
 112
 113In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the
 114FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
 115encryption key from kernel memory.  If it does so, it will also try to
 116evict all cached inodes which had been "unlocked" using the key,
 117thereby wiping their per-file keys and making them once again appear
 118"locked", i.e. in ciphertext or encrypted form.
 119
 120However, these ioctls have some limitations:
 121
 122- Per-file keys for in-use files will *not* be removed or wiped.
 123  Therefore, for maximum effect, userspace should close the relevant
 124  encrypted files and directories before removing a master key, as
 125  well as kill any processes whose working directory is in an affected
 126  encrypted directory.
 127
 128- The kernel cannot magically wipe copies of the master key(s) that
 129  userspace might have as well.  Therefore, userspace must wipe all
 130  copies of the master key(s) it makes as well; normally this should
 131  be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting
 132  for FS_IOC_REMOVE_ENCRYPTION_KEY.  Naturally, the same also applies
 133  to all higher levels in the key hierarchy.  Userspace should also
 134  follow other security precautions such as mlock()ing memory
 135  containing keys to prevent it from being swapped out.
 136
 137- In general, decrypted contents and filenames in the kernel VFS
 138  caches are freed but not wiped.  Therefore, portions thereof may be
 139  recoverable from freed memory, even after the corresponding key(s)
 140  were wiped.  To partially solve this, you can set
 141  CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1
 142  to your kernel command line.  However, this has a performance cost.
 143
 144- Secret keys might still exist in CPU registers, in crypto
 145  accelerator hardware (if used by the crypto API to implement any of
 146  the algorithms), or in other places not explicitly considered here.
 147
 148Limitations of v1 policies
 149~~~~~~~~~~~~~~~~~~~~~~~~~~
 150
 151v1 encryption policies have some weaknesses with respect to online
 152attacks:
 153
 154- There is no verification that the provided master key is correct.
 155  Therefore, a malicious user can temporarily associate the wrong key
 156  with another user's encrypted files to which they have read-only
 157  access.  Because of filesystem caching, the wrong key will then be
 158  used by the other user's accesses to those files, even if the other
 159  user has the correct key in their own keyring.  This violates the
 160  meaning of "read-only access".
 161
 162- A compromise of a per-file key also compromises the master key from
 163  which it was derived.
 164
 165- Non-root users cannot securely remove encryption keys.
 166
 167All the above problems are fixed with v2 encryption policies.  For
 168this reason among others, it is recommended to use v2 encryption
 169policies on all new encrypted directories.
 170
 171Key hierarchy
 172=============
 173
 174Master Keys
 175-----------
 176
 177Each encrypted directory tree is protected by a *master key*.  Master
 178keys can be up to 64 bytes long, and must be at least as long as the
 179greater of the key length needed by the contents and filenames
 180encryption modes being used.  For example, if AES-256-XTS is used for
 181contents encryption, the master key must be 64 bytes (512 bits).  Note
 182that the XTS mode is defined to require a key twice as long as that
 183required by the underlying block cipher.
 184
 185To "unlock" an encrypted directory tree, userspace must provide the
 186appropriate master key.  There can be any number of master keys, each
 187of which protects any number of directory trees on any number of
 188filesystems.
 189
 190Master keys must be real cryptographic keys, i.e. indistinguishable
 191from random bytestrings of the same length.  This implies that users
 192**must not** directly use a password as a master key, zero-pad a
 193shorter key, or repeat a shorter key.  Security cannot be guaranteed
 194if userspace makes any such error, as the cryptographic proofs and
 195analysis would no longer apply.
 196
 197Instead, users should generate master keys either using a
 198cryptographically secure random number generator, or by using a KDF
 199(Key Derivation Function).  The kernel does not do any key stretching;
 200therefore, if userspace derives the key from a low-entropy secret such
 201as a passphrase, it is critical that a KDF designed for this purpose
 202be used, such as scrypt, PBKDF2, or Argon2.
 203
 204Key derivation function
 205-----------------------
 206
 207With one exception, fscrypt never uses the master key(s) for
 208encryption directly.  Instead, they are only used as input to a KDF
 209(Key Derivation Function) to derive the actual keys.
 210
 211The KDF used for a particular master key differs depending on whether
 212the key is used for v1 encryption policies or for v2 encryption
 213policies.  Users **must not** use the same key for both v1 and v2
 214encryption policies.  (No real-world attack is currently known on this
 215specific case of key reuse, but its security cannot be guaranteed
 216since the cryptographic proofs and analysis would no longer apply.)
 217
 218For v1 encryption policies, the KDF only supports deriving per-file
 219encryption keys.  It works by encrypting the master key with
 220AES-128-ECB, using the file's 16-byte nonce as the AES key.  The
 221resulting ciphertext is used as the derived key.  If the ciphertext is
 222longer than needed, then it is truncated to the needed length.
 223
 224For v2 encryption policies, the KDF is HKDF-SHA512.  The master key is
 225passed as the "input keying material", no salt is used, and a distinct
 226"application-specific information string" is used for each distinct
 227key to be derived.  For example, when a per-file encryption key is
 228derived, the application-specific information string is the file's
 229nonce prefixed with "fscrypt\\0" and a context byte.  Different
 230context bytes are used for other types of derived keys.
 231
 232HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
 233HKDF is more flexible, is nonreversible, and evenly distributes
 234entropy from the master key.  HKDF is also standardized and widely
 235used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
 236
 237Per-file keys
 238-------------
 239
 240Since each master key can protect many files, it is necessary to
 241"tweak" the encryption of each file so that the same plaintext in two
 242files doesn't map to the same ciphertext, or vice versa.  In most
 243cases, fscrypt does this by deriving per-file keys.  When a new
 244encrypted inode (regular file, directory, or symlink) is created,
 245fscrypt randomly generates a 16-byte nonce and stores it in the
 246inode's encryption xattr.  Then, it uses a KDF (as described in `Key
 247derivation function`_) to derive the file's key from the master key
 248and nonce.
 249
 250Key derivation was chosen over key wrapping because wrapped keys would
 251require larger xattrs which would be less likely to fit in-line in the
 252filesystem's inode table, and there didn't appear to be any
 253significant advantages to key wrapping.  In particular, currently
 254there is no requirement to support unlocking a file with multiple
 255alternative master keys or to support rotating master keys.  Instead,
 256the master keys may be wrapped in userspace, e.g. as is done by the
 257`fscrypt <https://github.com/google/fscrypt>`_ tool.
 258
 259Including the inode number in the IVs was considered.  However, it was
 260rejected as it would have prevented ext4 filesystems from being
 261resized, and by itself still wouldn't have been sufficient to prevent
 262the same key from being directly reused for both XTS and CTS-CBC.
 263
 264DIRECT_KEY and per-mode keys
 265----------------------------
 266
 267The Adiantum encryption mode (see `Encryption modes and usage`_) is
 268suitable for both contents and filenames encryption, and it accepts
 269long IVs --- long enough to hold both an 8-byte logical block number
 270and a 16-byte per-file nonce.  Also, the overhead of each Adiantum key
 271is greater than that of an AES-256-XTS key.
 272
 273Therefore, to improve performance and save memory, for Adiantum a
 274"direct key" configuration is supported.  When the user has enabled
 275this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
 276per-file keys are not used.  Instead, whenever any data (contents or
 277filenames) is encrypted, the file's 16-byte nonce is included in the
 278IV.  Moreover:
 279
 280- For v1 encryption policies, the encryption is done directly with the
 281  master key.  Because of this, users **must not** use the same master
 282  key for any other purpose, even for other v1 policies.
 283
 284- For v2 encryption policies, the encryption is done with a per-mode
 285  key derived using the KDF.  Users may use the same master key for
 286  other v2 encryption policies.
 287
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 288Key identifiers
 289---------------
 290
 291For master keys used for v2 encryption policies, a unique 16-byte "key
 292identifier" is also derived using the KDF.  This value is stored in
 293the clear, since it is needed to reliably identify the key itself.
 294
 
 
 
 
 
 
 
 
 
 
 295Encryption modes and usage
 296==========================
 297
 298fscrypt allows one encryption mode to be specified for file contents
 299and one encryption mode to be specified for filenames.  Different
 300directory trees are permitted to use different encryption modes.
 
 
 
 
 301Currently, the following pairs of encryption modes are supported:
 302
 303- AES-256-XTS for contents and AES-256-CTS-CBC for filenames
 304- AES-128-CBC for contents and AES-128-CTS-CBC for filenames
 305- Adiantum for both contents and filenames
 
 
 306
 307If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
 
 308
 309AES-128-CBC was added only for low-powered embedded devices with
 310crypto accelerators such as CAAM or CESA that do not support XTS.  To
 311use AES-128-CBC, CONFIG_CRYPTO_SHA256 (or another SHA-256
 312implementation) must be enabled so that ESSIV can be used.
 313
 314Adiantum is a (primarily) stream cipher-based mode that is fast even
 315on CPUs without dedicated crypto instructions.  It's also a true
 316wide-block mode, unlike XTS.  It can also eliminate the need to derive
 317per-file keys.  However, it depends on the security of two primitives,
 318XChaCha12 and AES-256, rather than just one.  See the paper
 319"Adiantum: length-preserving encryption for entry-level processors"
 320(https://eprint.iacr.org/2018/720.pdf) for more details.  To use
 321Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled.  Also, fast
 322implementations of ChaCha and NHPoly1305 should be enabled, e.g.
 323CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM.
 324
 325New encryption modes can be added relatively easily, without changes
 326to individual filesystems.  However, authenticated encryption (AE)
 327modes are not currently supported because of the difficulty of dealing
 328with ciphertext expansion.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 329
 330Contents encryption
 331-------------------
 332
 333For file contents, each filesystem block is encrypted independently.
 334Currently, only the case where the filesystem block size is equal to
 335the system's page size (usually 4096 bytes) is supported.
 336
 337Each block's IV is set to the logical block number within the file as
 338a little endian number, except that:
 339
 340- With CBC mode encryption, ESSIV is also used.  Specifically, each IV
 341  is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
 342  of the file's data encryption key.
 343
 344- In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY
 345  set in the fscrypt_policy), the file's nonce is also appended to the
 346  IV.  Currently this is only allowed with the Adiantum encryption
 347  mode.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 348
 349Filenames encryption
 350--------------------
 351
 352For filenames, each full filename is encrypted at once.  Because of
 353the requirements to retain support for efficient directory lookups and
 354filenames of up to 255 bytes, the same IV is used for every filename
 355in a directory.
 356
 357However, each encrypted directory still uses a unique key; or
 358alternatively (for the "direct key" configuration) has the file's
 359nonce included in the IVs.  Thus, IV reuse is limited to within a
 360single directory.
 361
 362With CTS-CBC, the IV reuse means that when the plaintext filenames
 363share a common prefix at least as long as the cipher block size (16
 364bytes for AES), the corresponding encrypted filenames will also share
 365a common prefix.  This is undesirable.  Adiantum does not have this
 366weakness, as it is a wide-block encryption mode.
 367
 368All supported filenames encryption modes accept any plaintext length
 369>= 16 bytes; cipher block alignment is not required.  However,
 370filenames shorter than 16 bytes are NUL-padded to 16 bytes before
 371being encrypted.  In addition, to reduce leakage of filename lengths
 372via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
 37316, or 32-byte boundary (configurable).  32 is recommended since this
 374provides the best confidentiality, at the cost of making directory
 375entries consume slightly more space.  Note that since NUL (``\0``) is
 376not otherwise a valid character in filenames, the padding will never
 377produce duplicate plaintexts.
 378
 379Symbolic link targets are considered a type of filename and are
 380encrypted in the same way as filenames in directory entries, except
 381that IV reuse is not a problem as each symlink has its own inode.
 382
 383User API
 384========
 385
 386Setting an encryption policy
 387----------------------------
 388
 389FS_IOC_SET_ENCRYPTION_POLICY
 390~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 391
 392The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
 393empty directory or verifies that a directory or regular file already
 394has the specified encryption policy.  It takes in a pointer to a
 395:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
 396fscrypt_policy_v2`, defined as follows::
 397
 398    #define FSCRYPT_POLICY_V1               0
 399    #define FSCRYPT_KEY_DESCRIPTOR_SIZE     8
 400    struct fscrypt_policy_v1 {
 401            __u8 version;
 402            __u8 contents_encryption_mode;
 403            __u8 filenames_encryption_mode;
 404            __u8 flags;
 405            __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
 406    };
 407    #define fscrypt_policy  fscrypt_policy_v1
 408
 409    #define FSCRYPT_POLICY_V2               2
 410    #define FSCRYPT_KEY_IDENTIFIER_SIZE     16
 411    struct fscrypt_policy_v2 {
 412            __u8 version;
 413            __u8 contents_encryption_mode;
 414            __u8 filenames_encryption_mode;
 415            __u8 flags;
 416            __u8 __reserved[4];
 
 417            __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
 418    };
 419
 420This structure must be initialized as follows:
 421
 422- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is
 423  :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct
 424  is :c:type:`fscrypt_policy_v2`.  (Note: we refer to the original
 425  policy version as "v1", though its version code is really 0.)  For
 426  new encrypted directories, use v2 policies.
 427
 428- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
 429  be set to constants from ``<linux/fscrypt.h>`` which identify the
 430  encryption modes to use.  If unsure, use FSCRYPT_MODE_AES_256_XTS
 431  (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
 432  (4) for ``filenames_encryption_mode``.
 
 433
 434- ``flags`` must contain a value from ``<linux/fscrypt.h>`` which
 435  identifies the amount of NUL-padding to use when encrypting
 436  filenames.  If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3).
 437  Additionally, if the encryption modes are both
 438  FSCRYPT_MODE_ADIANTUM, this can contain
 439  FSCRYPT_POLICY_FLAG_DIRECT_KEY; see `DIRECT_KEY and per-mode keys`_.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 440
 441- For v2 encryption policies, ``__reserved`` must be zeroed.
 442
 443- For v1 encryption policies, ``master_key_descriptor`` specifies how
 444  to find the master key in a keyring; see `Adding keys`_.  It is up
 445  to userspace to choose a unique ``master_key_descriptor`` for each
 446  master key.  The e4crypt and fscrypt tools use the first 8 bytes of
 447  ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
 448  required.  Also, the master key need not be in the keyring yet when
 449  FS_IOC_SET_ENCRYPTION_POLICY is executed.  However, it must be added
 450  before any files can be created in the encrypted directory.
 451
 452  For v2 encryption policies, ``master_key_descriptor`` has been
 453  replaced with ``master_key_identifier``, which is longer and cannot
 454  be arbitrarily chosen.  Instead, the key must first be added using
 455  `FS_IOC_ADD_ENCRYPTION_KEY`_.  Then, the ``key_spec.u.identifier``
 456  the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
 457  be used as the ``master_key_identifier`` in the :c:type:`struct
 458  fscrypt_policy_v2`.
 459
 460If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
 461verifies that the file is an empty directory.  If so, the specified
 462encryption policy is assigned to the directory, turning it into an
 463encrypted directory.  After that, and after providing the
 464corresponding master key as described in `Adding keys`_, all regular
 465files, directories (recursively), and symlinks created in the
 466directory will be encrypted, inheriting the same encryption policy.
 467The filenames in the directory's entries will be encrypted as well.
 468
 469Alternatively, if the file is already encrypted, then
 470FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
 471policy exactly matches the actual one.  If they match, then the ioctl
 472returns 0.  Otherwise, it fails with EEXIST.  This works on both
 473regular files and directories, including nonempty directories.
 474
 475When a v2 encryption policy is assigned to a directory, it is also
 476required that either the specified key has been added by the current
 477user or that the caller has CAP_FOWNER in the initial user namespace.
 478(This is needed to prevent a user from encrypting their data with
 479another user's key.)  The key must remain added while
 480FS_IOC_SET_ENCRYPTION_POLICY is executing.  However, if the new
 481encrypted directory does not need to be accessed immediately, then the
 482key can be removed right away afterwards.
 483
 484Note that the ext4 filesystem does not allow the root directory to be
 485encrypted, even if it is empty.  Users who want to encrypt an entire
 486filesystem with one key should consider using dm-crypt instead.
 487
 488FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
 489
 490- ``EACCES``: the file is not owned by the process's uid, nor does the
 491  process have the CAP_FOWNER capability in a namespace with the file
 492  owner's uid mapped
 493- ``EEXIST``: the file is already encrypted with an encryption policy
 494  different from the one specified
 495- ``EINVAL``: an invalid encryption policy was specified (invalid
 496  version, mode(s), or flags; or reserved bits were set)
 
 
 497- ``ENOKEY``: a v2 encryption policy was specified, but the key with
 498  the specified ``master_key_identifier`` has not been added, nor does
 499  the process have the CAP_FOWNER capability in the initial user
 500  namespace
 501- ``ENOTDIR``: the file is unencrypted and is a regular file, not a
 502  directory
 503- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
 504- ``ENOTTY``: this type of filesystem does not implement encryption
 505- ``EOPNOTSUPP``: the kernel was not configured with encryption
 506  support for filesystems, or the filesystem superblock has not
 507  had encryption enabled on it.  (For example, to use encryption on an
 508  ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the
 509  kernel config, and the superblock must have had the "encrypt"
 510  feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
 511  encrypt``.)
 512- ``EPERM``: this directory may not be encrypted, e.g. because it is
 513  the root directory of an ext4 filesystem
 514- ``EROFS``: the filesystem is readonly
 515
 516Getting an encryption policy
 517----------------------------
 518
 519Two ioctls are available to get a file's encryption policy:
 520
 521- `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
 522- `FS_IOC_GET_ENCRYPTION_POLICY`_
 523
 524The extended (_EX) version of the ioctl is more general and is
 525recommended to use when possible.  However, on older kernels only the
 526original ioctl is available.  Applications should try the extended
 527version, and if it fails with ENOTTY fall back to the original
 528version.
 529
 530FS_IOC_GET_ENCRYPTION_POLICY_EX
 531~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 532
 533The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
 534policy, if any, for a directory or regular file.  No additional
 535permissions are required beyond the ability to open the file.  It
 536takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
 537defined as follows::
 538
 539    struct fscrypt_get_policy_ex_arg {
 540            __u64 policy_size; /* input/output */
 541            union {
 542                    __u8 version;
 543                    struct fscrypt_policy_v1 v1;
 544                    struct fscrypt_policy_v2 v2;
 545            } policy; /* output */
 546    };
 547
 548The caller must initialize ``policy_size`` to the size available for
 549the policy struct, i.e. ``sizeof(arg.policy)``.
 550
 551On success, the policy struct is returned in ``policy``, and its
 552actual size is returned in ``policy_size``.  ``policy.version`` should
 553be checked to determine the version of policy returned.  Note that the
 554version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
 555
 556FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:
 557
 558- ``EINVAL``: the file is encrypted, but it uses an unrecognized
 559  encryption policy version
 560- ``ENODATA``: the file is not encrypted
 561- ``ENOTTY``: this type of filesystem does not implement encryption,
 562  or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
 563  (try FS_IOC_GET_ENCRYPTION_POLICY instead)
 564- ``EOPNOTSUPP``: the kernel was not configured with encryption
 565  support for this filesystem, or the filesystem superblock has not
 566  had encryption enabled on it
 567- ``EOVERFLOW``: the file is encrypted and uses a recognized
 568  encryption policy version, but the policy struct does not fit into
 569  the provided buffer
 570
 571Note: if you only need to know whether a file is encrypted or not, on
 572most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
 573and check for FS_ENCRYPT_FL, or to use the statx() system call and
 574check for STATX_ATTR_ENCRYPTED in stx_attributes.
 575
 576FS_IOC_GET_ENCRYPTION_POLICY
 577~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 578
 579The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
 580encryption policy, if any, for a directory or regular file.  However,
 581unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
 582FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
 583version.  It takes in a pointer directly to a :c:type:`struct
 584fscrypt_policy_v1` rather than a :c:type:`struct
 585fscrypt_get_policy_ex_arg`.
 586
 587The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
 588for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
 589FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
 590encrypted using a newer encryption policy version.
 591
 592Getting the per-filesystem salt
 593-------------------------------
 594
 595Some filesystems, such as ext4 and F2FS, also support the deprecated
 596ioctl FS_IOC_GET_ENCRYPTION_PWSALT.  This ioctl retrieves a randomly
 597generated 16-byte value stored in the filesystem superblock.  This
 598value is intended to used as a salt when deriving an encryption key
 599from a passphrase or other low-entropy user credential.
 600
 601FS_IOC_GET_ENCRYPTION_PWSALT is deprecated.  Instead, prefer to
 602generate and manage any needed salt(s) in userspace.
 603
 
 
 
 
 
 
 
 
 
 
 
 604Adding keys
 605-----------
 606
 607FS_IOC_ADD_ENCRYPTION_KEY
 608~~~~~~~~~~~~~~~~~~~~~~~~~
 609
 610The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
 611the filesystem, making all files on the filesystem which were
 612encrypted using that key appear "unlocked", i.e. in plaintext form.
 613It can be executed on any file or directory on the target filesystem,
 614but using the filesystem's root directory is recommended.  It takes in
 615a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
 616follows::
 617
 618    struct fscrypt_add_key_arg {
 619            struct fscrypt_key_specifier key_spec;
 620            __u32 raw_size;
 621            __u32 __reserved[9];
 
 622            __u8 raw[];
 623    };
 624
 625    #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR        1
 626    #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER        2
 627
 628    struct fscrypt_key_specifier {
 629            __u32 type;     /* one of FSCRYPT_KEY_SPEC_TYPE_* */
 630            __u32 __reserved;
 631            union {
 632                    __u8 __reserved[32]; /* reserve some extra space */
 633                    __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
 634                    __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
 635            } u;
 636    };
 637
 638:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
 
 
 
 
 
 
 639as follows:
 640
 641- If the key is being added for use by v1 encryption policies, then
 642  ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
 643  ``key_spec.u.descriptor`` must contain the descriptor of the key
 644  being added, corresponding to the value in the
 645  ``master_key_descriptor`` field of :c:type:`struct
 646  fscrypt_policy_v1`.  To add this type of key, the calling process
 647  must have the CAP_SYS_ADMIN capability in the initial user
 648  namespace.
 649
 650  Alternatively, if the key is being added for use by v2 encryption
 651  policies, then ``key_spec.type`` must contain
 652  FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is
 653  an *output* field which the kernel fills in with a cryptographic
 654  hash of the key.  To add this type of key, the calling process does
 655  not need any privileges.  However, the number of keys that can be
 656  added is limited by the user's quota for the keyrings service (see
 657  ``Documentation/security/keys/core.rst``).
 658
 659- ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 660
 661- ``raw`` is a variable-length field which must contain the actual
 662  key, ``raw_size`` bytes long.
 
 663
 664For v2 policy keys, the kernel keeps track of which user (identified
 665by effective user ID) added the key, and only allows the key to be
 666removed by that user --- or by "root", if they use
 667`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
 668
 669However, if another user has added the key, it may be desirable to
 670prevent that other user from unexpectedly removing it.  Therefore,
 671FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
 672*again*, even if it's already added by other user(s).  In this case,
 673FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
 674current user, rather than actually add the key again (but the raw key
 675must still be provided, as a proof of knowledge).
 676
 677FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
 678the key was either added or already exists.
 679
 680FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:
 681
 682- ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
 683  caller does not have the CAP_SYS_ADMIN capability in the initial
 684  user namespace
 
 685- ``EDQUOT``: the key quota for this user would be exceeded by adding
 686  the key
 687- ``EINVAL``: invalid key size or key specifier type, or reserved bits
 688  were set
 
 
 
 
 689- ``ENOTTY``: this type of filesystem does not implement encryption
 690- ``EOPNOTSUPP``: the kernel was not configured with encryption
 691  support for this filesystem, or the filesystem superblock has not
 692  had encryption enabled on it
 693
 694Legacy method
 695~~~~~~~~~~~~~
 696
 697For v1 encryption policies, a master encryption key can also be
 698provided by adding it to a process-subscribed keyring, e.g. to a
 699session keyring, or to a user keyring if the user keyring is linked
 700into the session keyring.
 701
 702This method is deprecated (and not supported for v2 encryption
 703policies) for several reasons.  First, it cannot be used in
 704combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
 705so for removing a key a workaround such as keyctl_unlink() in
 706combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would
 707have to be used.  Second, it doesn't match the fact that the
 708locked/unlocked status of encrypted files (i.e. whether they appear to
 709be in plaintext form or in ciphertext form) is global.  This mismatch
 710has caused much confusion as well as real problems when processes
 711running under different UIDs, such as a ``sudo`` command, need to
 712access encrypted files.
 713
 714Nevertheless, to add a key to one of the process-subscribed keyrings,
 715the add_key() system call can be used (see:
 716``Documentation/security/keys/core.rst``).  The key type must be
 717"logon"; keys of this type are kept in kernel memory and cannot be
 718read back by userspace.  The key description must be "fscrypt:"
 719followed by the 16-character lower case hex representation of the
 720``master_key_descriptor`` that was set in the encryption policy.  The
 721key payload must conform to the following structure::
 722
 723    #define FSCRYPT_MAX_KEY_SIZE            64
 724
 725    struct fscrypt_key {
 726            __u32 mode;
 727            __u8 raw[FSCRYPT_MAX_KEY_SIZE];
 728            __u32 size;
 729    };
 730
 731``mode`` is ignored; just set it to 0.  The actual key is provided in
 732``raw`` with ``size`` indicating its size in bytes.  That is, the
 733bytes ``raw[0..size-1]`` (inclusive) are the actual key.
 734
 735The key description prefix "fscrypt:" may alternatively be replaced
 736with a filesystem-specific prefix such as "ext4:".  However, the
 737filesystem-specific prefixes are deprecated and should not be used in
 738new programs.
 739
 740Removing keys
 741-------------
 742
 743Two ioctls are available for removing a key that was added by
 744`FS_IOC_ADD_ENCRYPTION_KEY`_:
 745
 746- `FS_IOC_REMOVE_ENCRYPTION_KEY`_
 747- `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
 748
 749These two ioctls differ only in cases where v2 policy keys are added
 750or removed by non-root users.
 751
 752These ioctls don't work on keys that were added via the legacy
 753process-subscribed keyrings mechanism.
 754
 755Before using these ioctls, read the `Kernel memory compromise`_
 756section for a discussion of the security goals and limitations of
 757these ioctls.
 758
 759FS_IOC_REMOVE_ENCRYPTION_KEY
 760~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 761
 762The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
 763encryption key from the filesystem, and possibly removes the key
 764itself.  It can be executed on any file or directory on the target
 765filesystem, but using the filesystem's root directory is recommended.
 766It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
 767defined as follows::
 768
 769    struct fscrypt_remove_key_arg {
 770            struct fscrypt_key_specifier key_spec;
 771    #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY      0x00000001
 772    #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS     0x00000002
 773            __u32 removal_status_flags;     /* output */
 774            __u32 __reserved[5];
 775    };
 776
 777This structure must be zeroed, then initialized as follows:
 778
 779- The key to remove is specified by ``key_spec``:
 780
 781    - To remove a key used by v1 encryption policies, set
 782      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
 783      in ``key_spec.u.descriptor``.  To remove this type of key, the
 784      calling process must have the CAP_SYS_ADMIN capability in the
 785      initial user namespace.
 786
 787    - To remove a key used by v2 encryption policies, set
 788      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
 789      in ``key_spec.u.identifier``.
 790
 791For v2 policy keys, this ioctl is usable by non-root users.  However,
 792to make this possible, it actually just removes the current user's
 793claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
 794Only after all claims are removed is the key really removed.
 795
 796For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000,
 797then the key will be "claimed" by uid 1000, and
 798FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000.  Or, if
 799both uids 1000 and 2000 added the key, then for each uid
 800FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim.  Only
 801once *both* are removed is the key really removed.  (Think of it like
 802unlinking a file that may have hard links.)
 803
 804If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
 805try to "lock" all files that had been unlocked with the key.  It won't
 806lock files that are still in-use, so this ioctl is expected to be used
 807in cooperation with userspace ensuring that none of the files are
 808still open.  However, if necessary, this ioctl can be executed again
 809later to retry locking any remaining files.
 810
 811FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed
 812(but may still have files remaining to be locked), the user's claim to
 813the key was removed, or the key was already removed but had files
 814remaining to be the locked so the ioctl retried locking them.  In any
 815of these cases, ``removal_status_flags`` is filled in with the
 816following informational status flags:
 817
 818- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
 819  are still in-use.  Not guaranteed to be set in the case where only
 820  the user's claim to the key was removed.
 821- ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
 822  user's claim to the key was removed, not the key itself
 823
 824FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:
 825
 826- ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
 827  was specified, but the caller does not have the CAP_SYS_ADMIN
 828  capability in the initial user namespace
 829- ``EINVAL``: invalid key specifier type, or reserved bits were set
 830- ``ENOKEY``: the key object was not found at all, i.e. it was never
 831  added in the first place or was already fully removed including all
 832  files locked; or, the user does not have a claim to the key (but
 833  someone else does).
 834- ``ENOTTY``: this type of filesystem does not implement encryption
 835- ``EOPNOTSUPP``: the kernel was not configured with encryption
 836  support for this filesystem, or the filesystem superblock has not
 837  had encryption enabled on it
 838
 839FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
 840~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 841
 842FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
 843`FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
 844ALL_USERS version of the ioctl will remove all users' claims to the
 845key, not just the current user's.  I.e., the key itself will always be
 846removed, no matter how many users have added it.  This difference is
 847only meaningful if non-root users are adding and removing keys.
 848
 849Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires
 850"root", namely the CAP_SYS_ADMIN capability in the initial user
 851namespace.  Otherwise it will fail with EACCES.
 852
 853Getting key status
 854------------------
 855
 856FS_IOC_GET_ENCRYPTION_KEY_STATUS
 857~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 858
 859The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
 860master encryption key.  It can be executed on any file or directory on
 861the target filesystem, but using the filesystem's root directory is
 862recommended.  It takes in a pointer to a :c:type:`struct
 863fscrypt_get_key_status_arg`, defined as follows::
 864
 865    struct fscrypt_get_key_status_arg {
 866            /* input */
 867            struct fscrypt_key_specifier key_spec;
 868            __u32 __reserved[6];
 869
 870            /* output */
 871    #define FSCRYPT_KEY_STATUS_ABSENT               1
 872    #define FSCRYPT_KEY_STATUS_PRESENT              2
 873    #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3
 874            __u32 status;
 875    #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF   0x00000001
 876            __u32 status_flags;
 877            __u32 user_count;
 878            __u32 __out_reserved[13];
 879    };
 880
 881The caller must zero all input fields, then fill in ``key_spec``:
 882
 883    - To get the status of a key for v1 encryption policies, set
 884      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
 885      in ``key_spec.u.descriptor``.
 886
 887    - To get the status of a key for v2 encryption policies, set
 888      ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
 889      in ``key_spec.u.identifier``.
 890
 891On success, 0 is returned and the kernel fills in the output fields:
 892
 893- ``status`` indicates whether the key is absent, present, or
 894  incompletely removed.  Incompletely removed means that the master
 895  secret has been removed, but some files are still in use; i.e.,
 896  `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational
 897  status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.
 898
 899- ``status_flags`` can contain the following flags:
 900
 901    - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
 902      has added by the current user.  This is only set for keys
 903      identified by ``identifier`` rather than by ``descriptor``.
 904
 905- ``user_count`` specifies the number of users who have added the key.
 906  This is only set for keys identified by ``identifier`` rather than
 907  by ``descriptor``.
 908
 909FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:
 910
 911- ``EINVAL``: invalid key specifier type, or reserved bits were set
 912- ``ENOTTY``: this type of filesystem does not implement encryption
 913- ``EOPNOTSUPP``: the kernel was not configured with encryption
 914  support for this filesystem, or the filesystem superblock has not
 915  had encryption enabled on it
 916
 917Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful
 918for determining whether the key for a given encrypted directory needs
 919to be added before prompting the user for the passphrase needed to
 920derive the key.
 921
 922FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
 923the filesystem-level keyring, i.e. the keyring managed by
 924`FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_.  It
 925cannot get the status of a key that has only been added for use by v1
 926encryption policies using the legacy mechanism involving
 927process-subscribed keyrings.
 928
 929Access semantics
 930================
 931
 932With the key
 933------------
 934
 935With the encryption key, encrypted regular files, directories, and
 936symlinks behave very similarly to their unencrypted counterparts ---
 937after all, the encryption is intended to be transparent.  However,
 938astute users may notice some differences in behavior:
 939
 940- Unencrypted files, or files encrypted with a different encryption
 941  policy (i.e. different key, modes, or flags), cannot be renamed or
 942  linked into an encrypted directory; see `Encryption policy
 943  enforcement`_.  Attempts to do so will fail with EXDEV.  However,
 944  encrypted files can be renamed within an encrypted directory, or
 945  into an unencrypted directory.
 946
 947  Note: "moving" an unencrypted file into an encrypted directory, e.g.
 948  with the `mv` program, is implemented in userspace by a copy
 949  followed by a delete.  Be aware that the original unencrypted data
 950  may remain recoverable from free space on the disk; prefer to keep
 951  all files encrypted from the very beginning.  The `shred` program
 952  may be used to overwrite the source files but isn't guaranteed to be
 953  effective on all filesystems and storage devices.
 954
 955- Direct I/O is not supported on encrypted files.  Attempts to use
 956  direct I/O on such files will fall back to buffered I/O.
 957
 958- The fallocate operations FALLOC_FL_COLLAPSE_RANGE,
 959  FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported
 960  on encrypted files and will fail with EOPNOTSUPP.
 961
 962- Online defragmentation of encrypted files is not supported.  The
 963  EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
 964  EOPNOTSUPP.
 965
 966- The ext4 filesystem does not support data journaling with encrypted
 967  regular files.  It will fall back to ordered data mode instead.
 968
 969- DAX (Direct Access) is not supported on encrypted files.
 970
 971- The st_size of an encrypted symlink will not necessarily give the
 972  length of the symlink target as required by POSIX.  It will actually
 973  give the length of the ciphertext, which will be slightly longer
 974  than the plaintext due to NUL-padding and an extra 2-byte overhead.
 975
 976- The maximum length of an encrypted symlink is 2 bytes shorter than
 977  the maximum length of an unencrypted symlink.  For example, on an
 978  EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
 979  to 4095 bytes long, while encrypted symlinks can only be up to 4093
 980  bytes long (both lengths excluding the terminating null).
 981
 982Note that mmap *is* supported.  This is possible because the pagecache
 983for an encrypted file contains the plaintext, not the ciphertext.
 984
 985Without the key
 986---------------
 987
 988Some filesystem operations may be performed on encrypted regular
 989files, directories, and symlinks even before their encryption key has
 990been added, or after their encryption key has been removed:
 991
 992- File metadata may be read, e.g. using stat().
 993
 994- Directories may be listed, in which case the filenames will be
 995  listed in an encoded form derived from their ciphertext.  The
 996  current encoding algorithm is described in `Filename hashing and
 997  encoding`_.  The algorithm is subject to change, but it is
 998  guaranteed that the presented filenames will be no longer than
 999  NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
1000  will uniquely identify directory entries.
1001
1002  The ``.`` and ``..`` directory entries are special.  They are always
1003  present and are not encrypted or encoded.
1004
1005- Files may be deleted.  That is, nondirectory files may be deleted
1006  with unlink() as usual, and empty directories may be deleted with
1007  rmdir() as usual.  Therefore, ``rm`` and ``rm -r`` will work as
1008  expected.
1009
1010- Symlink targets may be read and followed, but they will be presented
1011  in encrypted form, similar to filenames in directories.  Hence, they
1012  are unlikely to point to anywhere useful.
1013
1014Without the key, regular files cannot be opened or truncated.
1015Attempts to do so will fail with ENOKEY.  This implies that any
1016regular file operations that require a file descriptor, such as
1017read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
1018
1019Also without the key, files of any type (including directories) cannot
1020be created or linked into an encrypted directory, nor can a name in an
1021encrypted directory be the source or target of a rename, nor can an
1022O_TMPFILE temporary file be created in an encrypted directory.  All
1023such operations will fail with ENOKEY.
1024
1025It is not currently possible to backup and restore encrypted files
1026without the encryption key.  This would require special APIs which
1027have not yet been implemented.
1028
1029Encryption policy enforcement
1030=============================
1031
1032After an encryption policy has been set on a directory, all regular
1033files, directories, and symbolic links created in that directory
1034(recursively) will inherit that encryption policy.  Special files ---
1035that is, named pipes, device nodes, and UNIX domain sockets --- will
1036not be encrypted.
1037
1038Except for those special files, it is forbidden to have unencrypted
1039files, or files encrypted with a different encryption policy, in an
1040encrypted directory tree.  Attempts to link or rename such a file into
1041an encrypted directory will fail with EXDEV.  This is also enforced
1042during ->lookup() to provide limited protection against offline
1043attacks that try to disable or downgrade encryption in known locations
1044where applications may later write sensitive data.  It is recommended
1045that systems implementing a form of "verified boot" take advantage of
1046this by validating all top-level encryption policies prior to access.
1047
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1048Implementation details
1049======================
1050
1051Encryption context
1052------------------
1053
1054An encryption policy is represented on-disk by a :c:type:`struct
1055fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`.  It is
1056up to individual filesystems to decide where to store it, but normally
1057it would be stored in a hidden extended attribute.  It should *not* be
1058exposed by the xattr-related system calls such as getxattr() and
1059setxattr() because of the special semantics of the encryption xattr.
1060(In particular, there would be much confusion if an encryption policy
1061were to be added to or removed from anything other than an empty
1062directory.)  These structs are defined as follows::
1063
1064    #define FS_KEY_DERIVATION_NONCE_SIZE 16
1065
1066    #define FSCRYPT_KEY_DESCRIPTOR_SIZE  8
1067    struct fscrypt_context_v1 {
1068            u8 version;
1069            u8 contents_encryption_mode;
1070            u8 filenames_encryption_mode;
1071            u8 flags;
1072            u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
1073            u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
1074    };
1075
1076    #define FSCRYPT_KEY_IDENTIFIER_SIZE  16
1077    struct fscrypt_context_v2 {
1078            u8 version;
1079            u8 contents_encryption_mode;
1080            u8 filenames_encryption_mode;
1081            u8 flags;
1082            u8 __reserved[4];
 
1083            u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
1084            u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
1085    };
1086
1087The context structs contain the same information as the corresponding
1088policy structs (see `Setting an encryption policy`_), except that the
1089context structs also contain a nonce.  The nonce is randomly generated
1090by the kernel and is used as KDF input or as a tweak to cause
1091different files to be encrypted differently; see `Per-file keys`_ and
1092`DIRECT_KEY and per-mode keys`_.
1093
1094Data path changes
1095-----------------
1096
1097For the read path (->readpage()) of regular files, filesystems can
 
 
 
 
 
 
 
1098read the ciphertext into the page cache and decrypt it in-place.  The
1099page lock must be held until decryption has finished, to prevent the
1100page from becoming visible to userspace prematurely.
1101
1102For the write path (->writepage()) of regular files, filesystems
1103cannot encrypt data in-place in the page cache, since the cached
1104plaintext must be preserved.  Instead, filesystems must encrypt into a
1105temporary buffer or "bounce page", then write out the temporary
1106buffer.  Some filesystems, such as UBIFS, already use temporary
1107buffers regardless of encryption.  Other filesystems, such as ext4 and
1108F2FS, have to allocate bounce pages specially for encryption.
1109
1110Filename hashing and encoding
1111-----------------------------
1112
1113Modern filesystems accelerate directory lookups by using indexed
1114directories.  An indexed directory is organized as a tree keyed by
1115filename hashes.  When a ->lookup() is requested, the filesystem
1116normally hashes the filename being looked up so that it can quickly
1117find the corresponding directory entry, if any.
1118
1119With encryption, lookups must be supported and efficient both with and
1120without the encryption key.  Clearly, it would not work to hash the
1121plaintext filenames, since the plaintext filenames are unavailable
1122without the key.  (Hashing the plaintext filenames would also make it
1123impossible for the filesystem's fsck tool to optimize encrypted
1124directories.)  Instead, filesystems hash the ciphertext filenames,
1125i.e. the bytes actually stored on-disk in the directory entries.  When
1126asked to do a ->lookup() with the key, the filesystem just encrypts
1127the user-supplied name to get the ciphertext.
1128
1129Lookups without the key are more complicated.  The raw ciphertext may
1130contain the ``\0`` and ``/`` characters, which are illegal in
1131filenames.  Therefore, readdir() must base64-encode the ciphertext for
1132presentation.  For most filenames, this works fine; on ->lookup(), the
1133filesystem just base64-decodes the user-supplied name to get back to
1134the raw ciphertext.
1135
1136However, for very long filenames, base64 encoding would cause the
1137filename length to exceed NAME_MAX.  To prevent this, readdir()
1138actually presents long filenames in an abbreviated form which encodes
1139a strong "hash" of the ciphertext filename, along with the optional
1140filesystem-specific hash(es) needed for directory lookups.  This
1141allows the filesystem to still, with a high degree of confidence, map
1142the filename given in ->lookup() back to a particular directory entry
1143that was previously listed by readdir().  See :c:type:`struct
1144fscrypt_digested_name` in the source for more details.
1145
1146Note that the precise way that filenames are presented to userspace
1147without the key is subject to change in the future.  It is only meant
1148as a way to temporarily present valid filenames so that commands like
1149``rm -r`` work as expected on encrypted directories.
1150
1151Tests
1152=====
1153
1154To test fscrypt, use xfstests, which is Linux's de facto standard
1155filesystem test suite.  First, run all the tests in the "encrypt"
1156group on the relevant filesystem(s).  For example, to test ext4 and
 
 
1157f2fs encryption using `kvm-xfstests
1158<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1159
1160    kvm-xfstests -c ext4,f2fs -g encrypt
 
1161
1162UBIFS encryption can also be tested this way, but it should be done in
1163a separate command, and it takes some time for kvm-xfstests to set up
1164emulated UBI volumes::
1165
1166    kvm-xfstests -c ubifs -g encrypt
1167
1168No tests should fail.  However, tests that use non-default encryption
1169modes (e.g. generic/549 and generic/550) will be skipped if the needed
1170algorithms were not built into the kernel's crypto API.  Also, tests
1171that access the raw block device (e.g. generic/399, generic/548,
1172generic/549, generic/550) will be skipped on UBIFS.
1173
1174Besides running the "encrypt" group tests, for ext4 and f2fs it's also
1175possible to run most xfstests with the "test_dummy_encryption" mount
1176option.  This option causes all new files to be automatically
1177encrypted with a dummy key, without having to make any API calls.
1178This tests the encrypted I/O paths more thoroughly.  To do this with
1179kvm-xfstests, use the "encrypt" filesystem configuration::
1180
1181    kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
 
1182
1183Because this runs many more tests than "-g encrypt" does, it takes
1184much longer to run; so also consider using `gce-xfstests
1185<https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1186instead of kvm-xfstests::
1187
1188    gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto