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