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