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