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