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 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 st_size of an encrypted symlink will not necessarily give the 1067 length of the symlink target as required by POSIX. It will actually 1068 give the length of the ciphertext, which will be slightly longer 1069 than the plaintext due to NUL-padding and an extra 2-byte overhead. 1070 1071- The maximum length of an encrypted symlink is 2 bytes shorter than 1072 the maximum length of an unencrypted symlink. For example, on an 1073 EXT4 filesystem with a 4K block size, unencrypted symlinks can be up 1074 to 4095 bytes long, while encrypted symlinks can only be up to 4093 1075 bytes long (both lengths excluding the terminating null). 1076 1077Note that mmap *is* supported. This is possible because the pagecache 1078for an encrypted file contains the plaintext, not the ciphertext. 1079 1080Without the key 1081--------------- 1082 1083Some filesystem operations may be performed on encrypted regular 1084files, directories, and symlinks even before their encryption key has 1085been added, or after their encryption key has been removed: 1086 1087- File metadata may be read, e.g. using stat(). 1088 1089- Directories may be listed, in which case the filenames will be 1090 listed in an encoded form derived from their ciphertext. The 1091 current encoding algorithm is described in `Filename hashing and 1092 encoding`_. The algorithm is subject to change, but it is 1093 guaranteed that the presented filenames will be no longer than 1094 NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and 1095 will uniquely identify directory entries. 1096 1097 The ``.`` and ``..`` directory entries are special. They are always 1098 present and are not encrypted or encoded. 1099 1100- Files may be deleted. That is, nondirectory files may be deleted 1101 with unlink() as usual, and empty directories may be deleted with 1102 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as 1103 expected. 1104 1105- Symlink targets may be read and followed, but they will be presented 1106 in encrypted form, similar to filenames in directories. Hence, they 1107 are unlikely to point to anywhere useful. 1108 1109Without the key, regular files cannot be opened or truncated. 1110Attempts to do so will fail with ENOKEY. This implies that any 1111regular file operations that require a file descriptor, such as 1112read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. 1113 1114Also without the key, files of any type (including directories) cannot 1115be created or linked into an encrypted directory, nor can a name in an 1116encrypted directory be the source or target of a rename, nor can an 1117O_TMPFILE temporary file be created in an encrypted directory. All 1118such operations will fail with ENOKEY. 1119 1120It is not currently possible to backup and restore encrypted files 1121without the encryption key. This would require special APIs which 1122have not yet been implemented. 1123 1124Encryption policy enforcement 1125============================= 1126 1127After an encryption policy has been set on a directory, all regular 1128files, directories, and symbolic links created in that directory 1129(recursively) will inherit that encryption policy. Special files --- 1130that is, named pipes, device nodes, and UNIX domain sockets --- will 1131not be encrypted. 1132 1133Except for those special files, it is forbidden to have unencrypted 1134files, or files encrypted with a different encryption policy, in an 1135encrypted directory tree. Attempts to link or rename such a file into 1136an encrypted directory will fail with EXDEV. This is also enforced 1137during ->lookup() to provide limited protection against offline 1138attacks that try to disable or downgrade encryption in known locations 1139where applications may later write sensitive data. It is recommended 1140that systems implementing a form of "verified boot" take advantage of 1141this by validating all top-level encryption policies prior to access. 1142 1143Implementation details 1144====================== 1145 1146Encryption context 1147------------------ 1148 1149An encryption policy is represented on-disk by 1150struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to 1151individual filesystems to decide where to store it, but normally it 1152would be stored in a hidden extended attribute. It should *not* be 1153exposed by the xattr-related system calls such as getxattr() and 1154setxattr() because of the special semantics of the encryption xattr. 1155(In particular, there would be much confusion if an encryption policy 1156were to be added to or removed from anything other than an empty 1157directory.) These structs are defined as follows:: 1158 1159 #define FSCRYPT_FILE_NONCE_SIZE 16 1160 1161 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 1162 struct fscrypt_context_v1 { 1163 u8 version; 1164 u8 contents_encryption_mode; 1165 u8 filenames_encryption_mode; 1166 u8 flags; 1167 u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; 1168 u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; 1169 }; 1170 1171 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 1172 struct fscrypt_context_v2 { 1173 u8 version; 1174 u8 contents_encryption_mode; 1175 u8 filenames_encryption_mode; 1176 u8 flags; 1177 u8 __reserved[4]; 1178 u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; 1179 u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; 1180 }; 1181 1182The context structs contain the same information as the corresponding 1183policy structs (see `Setting an encryption policy`_), except that the 1184context structs also contain a nonce. The nonce is randomly generated 1185by the kernel and is used as KDF input or as a tweak to cause 1186different files to be encrypted differently; see `Per-file encryption 1187keys`_ and `DIRECT_KEY policies`_. 1188 1189Data path changes 1190----------------- 1191 1192For the read path (->readpage()) of regular files, filesystems can 1193read the ciphertext into the page cache and decrypt it in-place. The 1194page lock must be held until decryption has finished, to prevent the 1195page from becoming visible to userspace prematurely. 1196 1197For the write path (->writepage()) of regular files, filesystems 1198cannot encrypt data in-place in the page cache, since the cached 1199plaintext must be preserved. Instead, filesystems must encrypt into a 1200temporary buffer or "bounce page", then write out the temporary 1201buffer. Some filesystems, such as UBIFS, already use temporary 1202buffers regardless of encryption. Other filesystems, such as ext4 and 1203F2FS, have to allocate bounce pages specially for encryption. 1204 1205Fscrypt is also able to use inline encryption hardware instead of the 1206kernel crypto API for en/decryption of file contents. When possible, 1207and if directed to do so (by specifying the 'inlinecrypt' mount option 1208for an ext4/F2FS filesystem), it adds encryption contexts to bios and 1209uses blk-crypto to perform the en/decryption instead of making use of 1210the above read/write path changes. Of course, even if directed to 1211make use of inline encryption, fscrypt will only be able to do so if 1212either hardware inline encryption support is available for the 1213selected encryption algorithm or CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK 1214is selected. If neither is the case, fscrypt will fall back to using 1215the above mentioned read/write path changes for en/decryption. 1216 1217Filename hashing and encoding 1218----------------------------- 1219 1220Modern filesystems accelerate directory lookups by using indexed 1221directories. An indexed directory is organized as a tree keyed by 1222filename hashes. When a ->lookup() is requested, the filesystem 1223normally hashes the filename being looked up so that it can quickly 1224find the corresponding directory entry, if any. 1225 1226With encryption, lookups must be supported and efficient both with and 1227without the encryption key. Clearly, it would not work to hash the 1228plaintext filenames, since the plaintext filenames are unavailable 1229without the key. (Hashing the plaintext filenames would also make it 1230impossible for the filesystem's fsck tool to optimize encrypted 1231directories.) Instead, filesystems hash the ciphertext filenames, 1232i.e. the bytes actually stored on-disk in the directory entries. When 1233asked to do a ->lookup() with the key, the filesystem just encrypts 1234the user-supplied name to get the ciphertext. 1235 1236Lookups without the key are more complicated. The raw ciphertext may 1237contain the ``\0`` and ``/`` characters, which are illegal in 1238filenames. Therefore, readdir() must base64-encode the ciphertext for 1239presentation. For most filenames, this works fine; on ->lookup(), the 1240filesystem just base64-decodes the user-supplied name to get back to 1241the raw ciphertext. 1242 1243However, for very long filenames, base64 encoding would cause the 1244filename length to exceed NAME_MAX. To prevent this, readdir() 1245actually presents long filenames in an abbreviated form which encodes 1246a strong "hash" of the ciphertext filename, along with the optional 1247filesystem-specific hash(es) needed for directory lookups. This 1248allows the filesystem to still, with a high degree of confidence, map 1249the filename given in ->lookup() back to a particular directory entry 1250that was previously listed by readdir(). See 1251struct fscrypt_nokey_name in the source for more details. 1252 1253Note that the precise way that filenames are presented to userspace 1254without the key is subject to change in the future. It is only meant 1255as a way to temporarily present valid filenames so that commands like 1256``rm -r`` work as expected on encrypted directories. 1257 1258Tests 1259===== 1260 1261To test fscrypt, use xfstests, which is Linux's de facto standard 1262filesystem test suite. First, run all the tests in the "encrypt" 1263group on the relevant filesystem(s). One can also run the tests 1264with the 'inlinecrypt' mount option to test the implementation for 1265inline encryption support. For example, to test ext4 and 1266f2fs encryption using `kvm-xfstests 1267<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: 1268 1269 kvm-xfstests -c ext4,f2fs -g encrypt 1270 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt 1271 1272UBIFS encryption can also be tested this way, but it should be done in 1273a separate command, and it takes some time for kvm-xfstests to set up 1274emulated UBI volumes:: 1275 1276 kvm-xfstests -c ubifs -g encrypt 1277 1278No tests should fail. However, tests that use non-default encryption 1279modes (e.g. generic/549 and generic/550) will be skipped if the needed 1280algorithms were not built into the kernel's crypto API. Also, tests 1281that access the raw block device (e.g. generic/399, generic/548, 1282generic/549, generic/550) will be skipped on UBIFS. 1283 1284Besides running the "encrypt" group tests, for ext4 and f2fs it's also 1285possible to run most xfstests with the "test_dummy_encryption" mount 1286option. This option causes all new files to be automatically 1287encrypted with a dummy key, without having to make any API calls. 1288This tests the encrypted I/O paths more thoroughly. To do this with 1289kvm-xfstests, use the "encrypt" filesystem configuration:: 1290 1291 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 1292 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt 1293 1294Because this runs many more tests than "-g encrypt" does, it takes 1295much longer to run; so also consider using `gce-xfstests 1296<https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_ 1297instead of kvm-xfstests:: 1298 1299 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto 1300 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt 1301