1f4f864c1SEric Biggers===================================== 2f4f864c1SEric BiggersFilesystem-level encryption (fscrypt) 3f4f864c1SEric Biggers===================================== 4f4f864c1SEric Biggers 5f4f864c1SEric BiggersIntroduction 6f4f864c1SEric Biggers============ 7f4f864c1SEric Biggers 8f4f864c1SEric Biggersfscrypt is a library which filesystems can hook into to support 9f4f864c1SEric Biggerstransparent encryption of files and directories. 10f4f864c1SEric Biggers 11f4f864c1SEric BiggersNote: "fscrypt" in this document refers to the kernel-level portion, 12f4f864c1SEric Biggersimplemented in ``fs/crypto/``, as opposed to the userspace tool 13f4f864c1SEric Biggers`fscrypt <https://github.com/google/fscrypt>`_. This document only 14f4f864c1SEric Biggerscovers the kernel-level portion. For command-line examples of how to 15f4f864c1SEric Biggersuse encryption, see the documentation for the userspace tool `fscrypt 16f4f864c1SEric Biggers<https://github.com/google/fscrypt>`_. Also, it is recommended to use 17f4f864c1SEric Biggersthe fscrypt userspace tool, or other existing userspace tools such as 18f4f864c1SEric Biggers`fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key 19f4f864c1SEric Biggersmanagement system 20f4f864c1SEric Biggers<https://source.android.com/security/encryption/file-based>`_, over 21f4f864c1SEric Biggersusing the kernel's API directly. Using existing tools reduces the 22f4f864c1SEric Biggerschance of introducing your own security bugs. (Nevertheless, for 23f4f864c1SEric Biggerscompleteness this documentation covers the kernel's API anyway.) 24f4f864c1SEric Biggers 25f4f864c1SEric BiggersUnlike dm-crypt, fscrypt operates at the filesystem level rather than 26f4f864c1SEric Biggersat the block device level. This allows it to encrypt different files 27f4f864c1SEric Biggerswith different keys and to have unencrypted files on the same 28f4f864c1SEric Biggersfilesystem. This is useful for multi-user systems where each user's 29f4f864c1SEric Biggersdata-at-rest needs to be cryptographically isolated from the others. 30f4f864c1SEric BiggersHowever, except for filenames, fscrypt does not encrypt filesystem 31f4f864c1SEric Biggersmetadata. 32f4f864c1SEric Biggers 33f4f864c1SEric BiggersUnlike eCryptfs, which is a stacked filesystem, fscrypt is integrated 34f4f864c1SEric Biggersdirectly into supported filesystems --- currently ext4, F2FS, and 35f4f864c1SEric BiggersUBIFS. This allows encrypted files to be read and written without 36f4f864c1SEric Biggerscaching both the decrypted and encrypted pages in the pagecache, 37f4f864c1SEric Biggersthereby nearly halving the memory used and bringing it in line with 38f4f864c1SEric Biggersunencrypted files. Similarly, half as many dentries and inodes are 39f4f864c1SEric Biggersneeded. eCryptfs also limits encrypted filenames to 143 bytes, 40f4f864c1SEric Biggerscausing application compatibility issues; fscrypt allows the full 255 41f4f864c1SEric Biggersbytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be 42f4f864c1SEric Biggersused by unprivileged users, with no need to mount anything. 43f4f864c1SEric Biggers 44f4f864c1SEric Biggersfscrypt does not support encrypting files in-place. Instead, it 45f4f864c1SEric Biggerssupports marking an empty directory as encrypted. Then, after 46f4f864c1SEric Biggersuserspace provides the key, all regular files, directories, and 47f4f864c1SEric Biggerssymbolic links created in that directory tree are transparently 48f4f864c1SEric Biggersencrypted. 49f4f864c1SEric Biggers 50f4f864c1SEric BiggersThreat model 51f4f864c1SEric Biggers============ 52f4f864c1SEric Biggers 53f4f864c1SEric BiggersOffline attacks 54f4f864c1SEric Biggers--------------- 55f4f864c1SEric Biggers 56f4f864c1SEric BiggersProvided that userspace chooses a strong encryption key, fscrypt 57f4f864c1SEric Biggersprotects the confidentiality of file contents and filenames in the 58f4f864c1SEric Biggersevent of a single point-in-time permanent offline compromise of the 59f4f864c1SEric Biggersblock device content. fscrypt does not protect the confidentiality of 60f4f864c1SEric Biggersnon-filename metadata, e.g. file sizes, file permissions, file 61f4f864c1SEric Biggerstimestamps, and extended attributes. Also, the existence and location 62f4f864c1SEric Biggersof holes (unallocated blocks which logically contain all zeroes) in 63f4f864c1SEric Biggersfiles is not protected. 64f4f864c1SEric Biggers 65f4f864c1SEric Biggersfscrypt is not guaranteed to protect confidentiality or authenticity 66f4f864c1SEric Biggersif an attacker is able to manipulate the filesystem offline prior to 67f4f864c1SEric Biggersan authorized user later accessing the filesystem. 68f4f864c1SEric Biggers 69f4f864c1SEric BiggersOnline attacks 70f4f864c1SEric Biggers-------------- 71f4f864c1SEric Biggers 72f4f864c1SEric Biggersfscrypt (and storage encryption in general) can only provide limited 73f4f864c1SEric Biggersprotection, if any at all, against online attacks. In detail: 74f4f864c1SEric Biggers 75f4f864c1SEric Biggersfscrypt is only resistant to side-channel attacks, such as timing or 76f4f864c1SEric Biggerselectromagnetic attacks, to the extent that the underlying Linux 77f4f864c1SEric BiggersCryptographic API algorithms are. If a vulnerable algorithm is used, 78f4f864c1SEric Biggerssuch as a table-based implementation of AES, it may be possible for an 79f4f864c1SEric Biggersattacker to mount a side channel attack against the online system. 80f4f864c1SEric BiggersSide channel attacks may also be mounted against applications 81f4f864c1SEric Biggersconsuming decrypted data. 82f4f864c1SEric Biggers 83f4f864c1SEric BiggersAfter an encryption key has been provided, fscrypt is not designed to 84f4f864c1SEric Biggershide the plaintext file contents or filenames from other users on the 85f4f864c1SEric Biggerssame system, regardless of the visibility of the keyring key. 86f4f864c1SEric BiggersInstead, existing access control mechanisms such as file mode bits, 87f4f864c1SEric BiggersPOSIX ACLs, LSMs, or mount namespaces should be used for this purpose. 88f4f864c1SEric BiggersAlso note that as long as the encryption keys are *anywhere* in 89f4f864c1SEric Biggersmemory, an online attacker can necessarily compromise them by mounting 90f4f864c1SEric Biggersa physical attack or by exploiting any kernel security vulnerability 91f4f864c1SEric Biggerswhich provides an arbitrary memory read primitive. 92f4f864c1SEric Biggers 93f4f864c1SEric BiggersWhile it is ostensibly possible to "evict" keys from the system, 94f4f864c1SEric Biggersrecently accessed encrypted files will remain accessible at least 95f4f864c1SEric Biggersuntil the filesystem is unmounted or the VFS caches are dropped, e.g. 96f4f864c1SEric Biggersusing ``echo 2 > /proc/sys/vm/drop_caches``. Even after that, if the 97f4f864c1SEric BiggersRAM is compromised before being powered off, it will likely still be 98f4f864c1SEric Biggerspossible to recover portions of the plaintext file contents, if not 99f4f864c1SEric Biggerssome of the encryption keys as well. (Since Linux v4.12, all 100f4f864c1SEric Biggersin-kernel keys related to fscrypt are sanitized before being freed. 101f4f864c1SEric BiggersHowever, userspace would need to do its part as well.) 102f4f864c1SEric Biggers 103f4f864c1SEric BiggersCurrently, fscrypt does not prevent a user from maliciously providing 104f4f864c1SEric Biggersan incorrect key for another user's existing encrypted files. A 105f4f864c1SEric Biggersprotection against this is planned. 106f4f864c1SEric Biggers 107f4f864c1SEric BiggersKey hierarchy 108f4f864c1SEric Biggers============= 109f4f864c1SEric Biggers 110f4f864c1SEric BiggersMaster Keys 111f4f864c1SEric Biggers----------- 112f4f864c1SEric Biggers 113f4f864c1SEric BiggersEach encrypted directory tree is protected by a *master key*. Master 114f4f864c1SEric Biggerskeys can be up to 64 bytes long, and must be at least as long as the 115f4f864c1SEric Biggersgreater of the key length needed by the contents and filenames 116f4f864c1SEric Biggersencryption modes being used. For example, if AES-256-XTS is used for 117f4f864c1SEric Biggerscontents encryption, the master key must be 64 bytes (512 bits). Note 118f4f864c1SEric Biggersthat the XTS mode is defined to require a key twice as long as that 119f4f864c1SEric Biggersrequired by the underlying block cipher. 120f4f864c1SEric Biggers 121f4f864c1SEric BiggersTo "unlock" an encrypted directory tree, userspace must provide the 122f4f864c1SEric Biggersappropriate master key. There can be any number of master keys, each 123f4f864c1SEric Biggersof which protects any number of directory trees on any number of 124f4f864c1SEric Biggersfilesystems. 125f4f864c1SEric Biggers 126f4f864c1SEric BiggersUserspace should generate master keys either using a cryptographically 127f4f864c1SEric Biggerssecure random number generator, or by using a KDF (Key Derivation 128f4f864c1SEric BiggersFunction). Note that whenever a KDF is used to "stretch" a 129f4f864c1SEric Biggerslower-entropy secret such as a passphrase, it is critical that a KDF 130f4f864c1SEric Biggersdesigned for this purpose be used, such as scrypt, PBKDF2, or Argon2. 131f4f864c1SEric Biggers 132f4f864c1SEric BiggersPer-file keys 133f4f864c1SEric Biggers------------- 134f4f864c1SEric Biggers 1358094c3ceSEric BiggersSince each master key can protect many files, it is necessary to 1368094c3ceSEric Biggers"tweak" the encryption of each file so that the same plaintext in two 1378094c3ceSEric Biggersfiles doesn't map to the same ciphertext, or vice versa. In most 1388094c3ceSEric Biggerscases, fscrypt does this by deriving per-file keys. When a new 1398094c3ceSEric Biggersencrypted inode (regular file, directory, or symlink) is created, 1408094c3ceSEric Biggersfscrypt randomly generates a 16-byte nonce and stores it in the 1418094c3ceSEric Biggersinode's encryption xattr. Then, it uses a KDF (Key Derivation 1428094c3ceSEric BiggersFunction) to derive the file's key from the master key and nonce. 143f4f864c1SEric Biggers 1448094c3ceSEric BiggersThe Adiantum encryption mode (see `Encryption modes and usage`_) is 1458094c3ceSEric Biggersspecial, since it accepts longer IVs and is suitable for both contents 1468094c3ceSEric Biggersand filenames encryption. For it, a "direct key" option is offered 1478094c3ceSEric Biggerswhere the file's nonce is included in the IVs and the master key is 1488094c3ceSEric Biggersused for encryption directly. This improves performance; however, 1498094c3ceSEric Biggersusers must not use the same master key for any other encryption mode. 150f4f864c1SEric Biggers 1518094c3ceSEric BiggersBelow, the KDF and design considerations are described in more detail. 152f4f864c1SEric Biggers 1538094c3ceSEric BiggersThe current KDF works by encrypting the master key with AES-128-ECB, 1548094c3ceSEric Biggersusing the file's nonce as the AES key. The output is used as the 1558094c3ceSEric Biggersderived key. If the output is longer than needed, then it is 1568094c3ceSEric Biggerstruncated to the needed length. 157f4f864c1SEric Biggers 158f4f864c1SEric BiggersNote: this KDF meets the primary security requirement, which is to 159f4f864c1SEric Biggersproduce unique derived keys that preserve the entropy of the master 160f4f864c1SEric Biggerskey, assuming that the master key is already a good pseudorandom key. 161f4f864c1SEric BiggersHowever, it is nonstandard and has some problems such as being 162f4f864c1SEric Biggersreversible, so it is generally considered to be a mistake! It may be 163f4f864c1SEric Biggersreplaced with HKDF or another more standard KDF in the future. 164f4f864c1SEric Biggers 1658094c3ceSEric BiggersKey derivation was chosen over key wrapping because wrapped keys would 1668094c3ceSEric Biggersrequire larger xattrs which would be less likely to fit in-line in the 1678094c3ceSEric Biggersfilesystem's inode table, and there didn't appear to be any 1688094c3ceSEric Biggerssignificant advantages to key wrapping. In particular, currently 1698094c3ceSEric Biggersthere is no requirement to support unlocking a file with multiple 1708094c3ceSEric Biggersalternative master keys or to support rotating master keys. Instead, 1718094c3ceSEric Biggersthe master keys may be wrapped in userspace, e.g. as is done by the 1728094c3ceSEric Biggers`fscrypt <https://github.com/google/fscrypt>`_ tool. 1738094c3ceSEric Biggers 1748094c3ceSEric BiggersIncluding the inode number in the IVs was considered. However, it was 1758094c3ceSEric Biggersrejected as it would have prevented ext4 filesystems from being 1768094c3ceSEric Biggersresized, and by itself still wouldn't have been sufficient to prevent 1778094c3ceSEric Biggersthe same key from being directly reused for both XTS and CTS-CBC. 1788094c3ceSEric Biggers 179f4f864c1SEric BiggersEncryption modes and usage 180f4f864c1SEric Biggers========================== 181f4f864c1SEric Biggers 182f4f864c1SEric Biggersfscrypt allows one encryption mode to be specified for file contents 183f4f864c1SEric Biggersand one encryption mode to be specified for filenames. Different 184f4f864c1SEric Biggersdirectory trees are permitted to use different encryption modes. 185f4f864c1SEric BiggersCurrently, the following pairs of encryption modes are supported: 186f4f864c1SEric Biggers 187f4f864c1SEric Biggers- AES-256-XTS for contents and AES-256-CTS-CBC for filenames 188f4f864c1SEric Biggers- AES-128-CBC for contents and AES-128-CTS-CBC for filenames 1898094c3ceSEric Biggers- Adiantum for both contents and filenames 190f4f864c1SEric Biggers 1918094c3ceSEric BiggersIf unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. 1928094c3ceSEric Biggers 193f4f864c1SEric BiggersAES-128-CBC was added only for low-powered embedded devices with 194f4f864c1SEric Biggerscrypto accelerators such as CAAM or CESA that do not support XTS. 195f4f864c1SEric Biggers 1968094c3ceSEric BiggersAdiantum is a (primarily) stream cipher-based mode that is fast even 1978094c3ceSEric Biggerson CPUs without dedicated crypto instructions. It's also a true 1988094c3ceSEric Biggerswide-block mode, unlike XTS. It can also eliminate the need to derive 1998094c3ceSEric Biggersper-file keys. However, it depends on the security of two primitives, 2008094c3ceSEric BiggersXChaCha12 and AES-256, rather than just one. See the paper 2018094c3ceSEric Biggers"Adiantum: length-preserving encryption for entry-level processors" 2028094c3ceSEric Biggers(https://eprint.iacr.org/2018/720.pdf) for more details. To use 2038094c3ceSEric BiggersAdiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast 2048094c3ceSEric Biggersimplementations of ChaCha and NHPoly1305 should be enabled, e.g. 2058094c3ceSEric BiggersCONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. 2068094c3ceSEric Biggers 207f4f864c1SEric BiggersNew encryption modes can be added relatively easily, without changes 208f4f864c1SEric Biggersto individual filesystems. However, authenticated encryption (AE) 209f4f864c1SEric Biggersmodes are not currently supported because of the difficulty of dealing 210f4f864c1SEric Biggerswith ciphertext expansion. 211f4f864c1SEric Biggers 2128094c3ceSEric BiggersContents encryption 2138094c3ceSEric Biggers------------------- 2148094c3ceSEric Biggers 215f4f864c1SEric BiggersFor file contents, each filesystem block is encrypted independently. 216f4f864c1SEric BiggersCurrently, only the case where the filesystem block size is equal to 2178094c3ceSEric Biggersthe system's page size (usually 4096 bytes) is supported. 218f4f864c1SEric Biggers 2198094c3ceSEric BiggersEach block's IV is set to the logical block number within the file as 2208094c3ceSEric Biggersa little endian number, except that: 221f4f864c1SEric Biggers 2228094c3ceSEric Biggers- With CBC mode encryption, ESSIV is also used. Specifically, each IV 2238094c3ceSEric Biggers is encrypted with AES-256 where the AES-256 key is the SHA-256 hash 2248094c3ceSEric Biggers of the file's data encryption key. 2258094c3ceSEric Biggers 2268094c3ceSEric Biggers- In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in 2278094c3ceSEric Biggers the fscrypt_policy), the file's nonce is also appended to the IV. 2288094c3ceSEric Biggers Currently this is only allowed with the Adiantum encryption mode. 2298094c3ceSEric Biggers 2308094c3ceSEric BiggersFilenames encryption 2318094c3ceSEric Biggers-------------------- 2328094c3ceSEric Biggers 2338094c3ceSEric BiggersFor filenames, each full filename is encrypted at once. Because of 2348094c3ceSEric Biggersthe requirements to retain support for efficient directory lookups and 2358094c3ceSEric Biggersfilenames of up to 255 bytes, the same IV is used for every filename 2368094c3ceSEric Biggersin a directory. 2378094c3ceSEric Biggers 2388094c3ceSEric BiggersHowever, each encrypted directory still uses a unique key; or 2398094c3ceSEric Biggersalternatively (for the "direct key" configuration) has the file's 2408094c3ceSEric Biggersnonce included in the IVs. Thus, IV reuse is limited to within a 2418094c3ceSEric Biggerssingle directory. 2428094c3ceSEric Biggers 2438094c3ceSEric BiggersWith CTS-CBC, the IV reuse means that when the plaintext filenames 2448094c3ceSEric Biggersshare a common prefix at least as long as the cipher block size (16 2458094c3ceSEric Biggersbytes for AES), the corresponding encrypted filenames will also share 2468094c3ceSEric Biggersa common prefix. This is undesirable. Adiantum does not have this 2478094c3ceSEric Biggersweakness, as it is a wide-block encryption mode. 2488094c3ceSEric Biggers 2498094c3ceSEric BiggersAll supported filenames encryption modes accept any plaintext length 2508094c3ceSEric Biggers>= 16 bytes; cipher block alignment is not required. However, 2518094c3ceSEric Biggersfilenames shorter than 16 bytes are NUL-padded to 16 bytes before 2528094c3ceSEric Biggersbeing encrypted. In addition, to reduce leakage of filename lengths 2538094c3ceSEric Biggersvia their ciphertexts, all filenames are NUL-padded to the next 4, 8, 2548094c3ceSEric Biggers16, or 32-byte boundary (configurable). 32 is recommended since this 2558094c3ceSEric Biggersprovides the best confidentiality, at the cost of making directory 2568094c3ceSEric Biggersentries consume slightly more space. Note that since NUL (``\0``) is 2578094c3ceSEric Biggersnot otherwise a valid character in filenames, the padding will never 2588094c3ceSEric Biggersproduce duplicate plaintexts. 259f4f864c1SEric Biggers 260f4f864c1SEric BiggersSymbolic link targets are considered a type of filename and are 2618094c3ceSEric Biggersencrypted in the same way as filenames in directory entries, except 2628094c3ceSEric Biggersthat IV reuse is not a problem as each symlink has its own inode. 263f4f864c1SEric Biggers 264f4f864c1SEric BiggersUser API 265f4f864c1SEric Biggers======== 266f4f864c1SEric Biggers 267f4f864c1SEric BiggersSetting an encryption policy 268f4f864c1SEric Biggers---------------------------- 269f4f864c1SEric Biggers 270f4f864c1SEric BiggersThe FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an 271f4f864c1SEric Biggersempty directory or verifies that a directory or regular file already 272f4f864c1SEric Biggershas the specified encryption policy. It takes in a pointer to a 273f4f864c1SEric Biggers:c:type:`struct fscrypt_policy`, defined as follows:: 274f4f864c1SEric Biggers 275f4f864c1SEric Biggers #define FS_KEY_DESCRIPTOR_SIZE 8 276f4f864c1SEric Biggers 277f4f864c1SEric Biggers struct fscrypt_policy { 278f4f864c1SEric Biggers __u8 version; 279f4f864c1SEric Biggers __u8 contents_encryption_mode; 280f4f864c1SEric Biggers __u8 filenames_encryption_mode; 281f4f864c1SEric Biggers __u8 flags; 282f4f864c1SEric Biggers __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; 283f4f864c1SEric Biggers }; 284f4f864c1SEric Biggers 285f4f864c1SEric BiggersThis structure must be initialized as follows: 286f4f864c1SEric Biggers 287f4f864c1SEric Biggers- ``version`` must be 0. 288f4f864c1SEric Biggers 289f4f864c1SEric Biggers- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must 290f4f864c1SEric Biggers be set to constants from ``<linux/fs.h>`` which identify the 291f4f864c1SEric Biggers encryption modes to use. If unsure, use 292f4f864c1SEric Biggers FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` 293f4f864c1SEric Biggers and FS_ENCRYPTION_MODE_AES_256_CTS (4) for 294f4f864c1SEric Biggers ``filenames_encryption_mode``. 295f4f864c1SEric Biggers 2968094c3ceSEric Biggers- ``flags`` must contain a value from ``<linux/fs.h>`` which 297f4f864c1SEric Biggers identifies the amount of NUL-padding to use when encrypting 298f4f864c1SEric Biggers filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3). 2998094c3ceSEric Biggers In addition, if the chosen encryption modes are both 3008094c3ceSEric Biggers FS_ENCRYPTION_MODE_ADIANTUM, this can contain 3018094c3ceSEric Biggers FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be 3028094c3ceSEric Biggers used directly, without key derivation. 303f4f864c1SEric Biggers 304f4f864c1SEric Biggers- ``master_key_descriptor`` specifies how to find the master key in 305f4f864c1SEric Biggers the keyring; see `Adding keys`_. It is up to userspace to choose a 306f4f864c1SEric Biggers unique ``master_key_descriptor`` for each master key. The e4crypt 307f4f864c1SEric Biggers and fscrypt tools use the first 8 bytes of 308f4f864c1SEric Biggers ``SHA-512(SHA-512(master_key))``, but this particular scheme is not 309f4f864c1SEric Biggers required. Also, the master key need not be in the keyring yet when 310f4f864c1SEric Biggers FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added 311f4f864c1SEric Biggers before any files can be created in the encrypted directory. 312f4f864c1SEric Biggers 313f4f864c1SEric BiggersIf the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY 314f4f864c1SEric Biggersverifies that the file is an empty directory. If so, the specified 315f4f864c1SEric Biggersencryption policy is assigned to the directory, turning it into an 316f4f864c1SEric Biggersencrypted directory. After that, and after providing the 317f4f864c1SEric Biggerscorresponding master key as described in `Adding keys`_, all regular 318f4f864c1SEric Biggersfiles, directories (recursively), and symlinks created in the 319f4f864c1SEric Biggersdirectory will be encrypted, inheriting the same encryption policy. 320f4f864c1SEric BiggersThe filenames in the directory's entries will be encrypted as well. 321f4f864c1SEric Biggers 322f4f864c1SEric BiggersAlternatively, if the file is already encrypted, then 323f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption 324f4f864c1SEric Biggerspolicy exactly matches the actual one. If they match, then the ioctl 325f4f864c1SEric Biggersreturns 0. Otherwise, it fails with EEXIST. This works on both 326f4f864c1SEric Biggersregular files and directories, including nonempty directories. 327f4f864c1SEric Biggers 328f4f864c1SEric BiggersNote that the ext4 filesystem does not allow the root directory to be 329f4f864c1SEric Biggersencrypted, even if it is empty. Users who want to encrypt an entire 330f4f864c1SEric Biggersfilesystem with one key should consider using dm-crypt instead. 331f4f864c1SEric Biggers 332f4f864c1SEric BiggersFS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: 333f4f864c1SEric Biggers 334f4f864c1SEric Biggers- ``EACCES``: the file is not owned by the process's uid, nor does the 335f4f864c1SEric Biggers process have the CAP_FOWNER capability in a namespace with the file 336f4f864c1SEric Biggers owner's uid mapped 337f4f864c1SEric Biggers- ``EEXIST``: the file is already encrypted with an encryption policy 338f4f864c1SEric Biggers different from the one specified 339f4f864c1SEric Biggers- ``EINVAL``: an invalid encryption policy was specified (invalid 340f4f864c1SEric Biggers version, mode(s), or flags) 341f4f864c1SEric Biggers- ``ENOTDIR``: the file is unencrypted and is a regular file, not a 342f4f864c1SEric Biggers directory 343f4f864c1SEric Biggers- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory 344f4f864c1SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 345f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 346643fa961SChandan Rajendra support for filesystems, or the filesystem superblock has not 347f4f864c1SEric Biggers had encryption enabled on it. (For example, to use encryption on an 348643fa961SChandan Rajendra ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the 349f4f864c1SEric Biggers kernel config, and the superblock must have had the "encrypt" 350f4f864c1SEric Biggers feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O 351f4f864c1SEric Biggers encrypt``.) 352f4f864c1SEric Biggers- ``EPERM``: this directory may not be encrypted, e.g. because it is 353f4f864c1SEric Biggers the root directory of an ext4 filesystem 354f4f864c1SEric Biggers- ``EROFS``: the filesystem is readonly 355f4f864c1SEric Biggers 356f4f864c1SEric BiggersGetting an encryption policy 357f4f864c1SEric Biggers---------------------------- 358f4f864c1SEric Biggers 359f4f864c1SEric BiggersThe FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct 360f4f864c1SEric Biggersfscrypt_policy`, if any, for a directory or regular file. See above 361f4f864c1SEric Biggersfor the struct definition. No additional permissions are required 362f4f864c1SEric Biggersbeyond the ability to open the file. 363f4f864c1SEric Biggers 364f4f864c1SEric BiggersFS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors: 365f4f864c1SEric Biggers 366f4f864c1SEric Biggers- ``EINVAL``: the file is encrypted, but it uses an unrecognized 367f4f864c1SEric Biggers encryption context format 368f4f864c1SEric Biggers- ``ENODATA``: the file is not encrypted 369f4f864c1SEric Biggers- ``ENOTTY``: this type of filesystem does not implement encryption 370f4f864c1SEric Biggers- ``EOPNOTSUPP``: the kernel was not configured with encryption 371f4f864c1SEric Biggers support for this filesystem 372f4f864c1SEric Biggers 373f4f864c1SEric BiggersNote: if you only need to know whether a file is encrypted or not, on 374f4f864c1SEric Biggersmost filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl 375f4f864c1SEric Biggersand check for FS_ENCRYPT_FL, or to use the statx() system call and 376f4f864c1SEric Biggerscheck for STATX_ATTR_ENCRYPTED in stx_attributes. 377f4f864c1SEric Biggers 378f4f864c1SEric BiggersGetting the per-filesystem salt 379f4f864c1SEric Biggers------------------------------- 380f4f864c1SEric Biggers 381f4f864c1SEric BiggersSome filesystems, such as ext4 and F2FS, also support the deprecated 382f4f864c1SEric Biggersioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly 383f4f864c1SEric Biggersgenerated 16-byte value stored in the filesystem superblock. This 384f4f864c1SEric Biggersvalue is intended to used as a salt when deriving an encryption key 385f4f864c1SEric Biggersfrom a passphrase or other low-entropy user credential. 386f4f864c1SEric Biggers 387f4f864c1SEric BiggersFS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to 388f4f864c1SEric Biggersgenerate and manage any needed salt(s) in userspace. 389f4f864c1SEric Biggers 390f4f864c1SEric BiggersAdding keys 391f4f864c1SEric Biggers----------- 392f4f864c1SEric Biggers 393f4f864c1SEric BiggersTo provide a master key, userspace must add it to an appropriate 394f4f864c1SEric Biggerskeyring using the add_key() system call (see: 395f4f864c1SEric Biggers``Documentation/security/keys/core.rst``). The key type must be 396f4f864c1SEric Biggers"logon"; keys of this type are kept in kernel memory and cannot be 397f4f864c1SEric Biggersread back by userspace. The key description must be "fscrypt:" 398f4f864c1SEric Biggersfollowed by the 16-character lower case hex representation of the 399f4f864c1SEric Biggers``master_key_descriptor`` that was set in the encryption policy. The 400f4f864c1SEric Biggerskey payload must conform to the following structure:: 401f4f864c1SEric Biggers 402f4f864c1SEric Biggers #define FS_MAX_KEY_SIZE 64 403f4f864c1SEric Biggers 404f4f864c1SEric Biggers struct fscrypt_key { 405f4f864c1SEric Biggers u32 mode; 406f4f864c1SEric Biggers u8 raw[FS_MAX_KEY_SIZE]; 407f4f864c1SEric Biggers u32 size; 408f4f864c1SEric Biggers }; 409f4f864c1SEric Biggers 410f4f864c1SEric Biggers``mode`` is ignored; just set it to 0. The actual key is provided in 411f4f864c1SEric Biggers``raw`` with ``size`` indicating its size in bytes. That is, the 412f4f864c1SEric Biggersbytes ``raw[0..size-1]`` (inclusive) are the actual key. 413f4f864c1SEric Biggers 414f4f864c1SEric BiggersThe key description prefix "fscrypt:" may alternatively be replaced 415f4f864c1SEric Biggerswith a filesystem-specific prefix such as "ext4:". However, the 416f4f864c1SEric Biggersfilesystem-specific prefixes are deprecated and should not be used in 417f4f864c1SEric Biggersnew programs. 418f4f864c1SEric Biggers 419f4f864c1SEric BiggersThere are several different types of keyrings in which encryption keys 420f4f864c1SEric Biggersmay be placed, such as a session keyring, a user session keyring, or a 421f4f864c1SEric Biggersuser keyring. Each key must be placed in a keyring that is "attached" 422f4f864c1SEric Biggersto all processes that might need to access files encrypted with it, in 423f4f864c1SEric Biggersthe sense that request_key() will find the key. Generally, if only 424f4f864c1SEric Biggersprocesses belonging to a specific user need to access a given 425f4f864c1SEric Biggersencrypted directory and no session keyring has been installed, then 426f4f864c1SEric Biggersthat directory's key should be placed in that user's user session 427f4f864c1SEric Biggerskeyring or user keyring. Otherwise, a session keyring should be 428f4f864c1SEric Biggersinstalled if needed, and the key should be linked into that session 429f4f864c1SEric Biggerskeyring, or in a keyring linked into that session keyring. 430f4f864c1SEric Biggers 431f4f864c1SEric BiggersNote: introducing the complex visibility semantics of keyrings here 432f4f864c1SEric Biggerswas arguably a mistake --- especially given that by design, after any 433f4f864c1SEric Biggersprocess successfully opens an encrypted file (thereby setting up the 434f4f864c1SEric Biggersper-file key), possessing the keyring key is not actually required for 435f4f864c1SEric Biggersany process to read/write the file until its in-memory inode is 436f4f864c1SEric Biggersevicted. In the future there probably should be a way to provide keys 437f4f864c1SEric Biggersdirectly to the filesystem instead, which would make the intended 438f4f864c1SEric Biggerssemantics clearer. 439f4f864c1SEric Biggers 440f4f864c1SEric BiggersAccess semantics 441f4f864c1SEric Biggers================ 442f4f864c1SEric Biggers 443f4f864c1SEric BiggersWith the key 444f4f864c1SEric Biggers------------ 445f4f864c1SEric Biggers 446f4f864c1SEric BiggersWith the encryption key, encrypted regular files, directories, and 447f4f864c1SEric Biggerssymlinks behave very similarly to their unencrypted counterparts --- 448f4f864c1SEric Biggersafter all, the encryption is intended to be transparent. However, 449f4f864c1SEric Biggersastute users may notice some differences in behavior: 450f4f864c1SEric Biggers 451f4f864c1SEric Biggers- Unencrypted files, or files encrypted with a different encryption 452f4f864c1SEric Biggers policy (i.e. different key, modes, or flags), cannot be renamed or 453f4f864c1SEric Biggers linked into an encrypted directory; see `Encryption policy 454f5e55e77SEric Biggers enforcement`_. Attempts to do so will fail with EXDEV. However, 455f4f864c1SEric Biggers encrypted files can be renamed within an encrypted directory, or 456f4f864c1SEric Biggers into an unencrypted directory. 457f4f864c1SEric Biggers 458f5e55e77SEric Biggers Note: "moving" an unencrypted file into an encrypted directory, e.g. 459f5e55e77SEric Biggers with the `mv` program, is implemented in userspace by a copy 460f5e55e77SEric Biggers followed by a delete. Be aware that the original unencrypted data 461f5e55e77SEric Biggers may remain recoverable from free space on the disk; prefer to keep 462f5e55e77SEric Biggers all files encrypted from the very beginning. The `shred` program 463f5e55e77SEric Biggers may be used to overwrite the source files but isn't guaranteed to be 464f5e55e77SEric Biggers effective on all filesystems and storage devices. 465f5e55e77SEric Biggers 466f4f864c1SEric Biggers- Direct I/O is not supported on encrypted files. Attempts to use 467f4f864c1SEric Biggers direct I/O on such files will fall back to buffered I/O. 468f4f864c1SEric Biggers 469f4f864c1SEric Biggers- The fallocate operations FALLOC_FL_COLLAPSE_RANGE, 470f4f864c1SEric Biggers FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported 471f4f864c1SEric Biggers on encrypted files and will fail with EOPNOTSUPP. 472f4f864c1SEric Biggers 473f4f864c1SEric Biggers- Online defragmentation of encrypted files is not supported. The 474f4f864c1SEric Biggers EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with 475f4f864c1SEric Biggers EOPNOTSUPP. 476f4f864c1SEric Biggers 477f4f864c1SEric Biggers- The ext4 filesystem does not support data journaling with encrypted 478f4f864c1SEric Biggers regular files. It will fall back to ordered data mode instead. 479f4f864c1SEric Biggers 480f4f864c1SEric Biggers- DAX (Direct Access) is not supported on encrypted files. 481f4f864c1SEric Biggers 482f4f864c1SEric Biggers- The st_size of an encrypted symlink will not necessarily give the 483f4f864c1SEric Biggers length of the symlink target as required by POSIX. It will actually 4842f46a2bcSEric Biggers give the length of the ciphertext, which will be slightly longer 4852f46a2bcSEric Biggers than the plaintext due to NUL-padding and an extra 2-byte overhead. 4862f46a2bcSEric Biggers 4872f46a2bcSEric Biggers- The maximum length of an encrypted symlink is 2 bytes shorter than 4882f46a2bcSEric Biggers the maximum length of an unencrypted symlink. For example, on an 4892f46a2bcSEric Biggers EXT4 filesystem with a 4K block size, unencrypted symlinks can be up 4902f46a2bcSEric Biggers to 4095 bytes long, while encrypted symlinks can only be up to 4093 4912f46a2bcSEric Biggers bytes long (both lengths excluding the terminating null). 492f4f864c1SEric Biggers 493f4f864c1SEric BiggersNote that mmap *is* supported. This is possible because the pagecache 494f4f864c1SEric Biggersfor an encrypted file contains the plaintext, not the ciphertext. 495f4f864c1SEric Biggers 496f4f864c1SEric BiggersWithout the key 497f4f864c1SEric Biggers--------------- 498f4f864c1SEric Biggers 499f4f864c1SEric BiggersSome filesystem operations may be performed on encrypted regular 500f4f864c1SEric Biggersfiles, directories, and symlinks even before their encryption key has 501f4f864c1SEric Biggersbeen provided: 502f4f864c1SEric Biggers 503f4f864c1SEric Biggers- File metadata may be read, e.g. using stat(). 504f4f864c1SEric Biggers 505f4f864c1SEric Biggers- Directories may be listed, in which case the filenames will be 506f4f864c1SEric Biggers listed in an encoded form derived from their ciphertext. The 507f4f864c1SEric Biggers current encoding algorithm is described in `Filename hashing and 508f4f864c1SEric Biggers encoding`_. The algorithm is subject to change, but it is 509f4f864c1SEric Biggers guaranteed that the presented filenames will be no longer than 510f4f864c1SEric Biggers NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and 511f4f864c1SEric Biggers will uniquely identify directory entries. 512f4f864c1SEric Biggers 513f4f864c1SEric Biggers The ``.`` and ``..`` directory entries are special. They are always 514f4f864c1SEric Biggers present and are not encrypted or encoded. 515f4f864c1SEric Biggers 516f4f864c1SEric Biggers- Files may be deleted. That is, nondirectory files may be deleted 517f4f864c1SEric Biggers with unlink() as usual, and empty directories may be deleted with 518f4f864c1SEric Biggers rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as 519f4f864c1SEric Biggers expected. 520f4f864c1SEric Biggers 521f4f864c1SEric Biggers- Symlink targets may be read and followed, but they will be presented 522f4f864c1SEric Biggers in encrypted form, similar to filenames in directories. Hence, they 523f4f864c1SEric Biggers are unlikely to point to anywhere useful. 524f4f864c1SEric Biggers 525f4f864c1SEric BiggersWithout the key, regular files cannot be opened or truncated. 526f4f864c1SEric BiggersAttempts to do so will fail with ENOKEY. This implies that any 527f4f864c1SEric Biggersregular file operations that require a file descriptor, such as 528f4f864c1SEric Biggersread(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. 529f4f864c1SEric Biggers 530f4f864c1SEric BiggersAlso without the key, files of any type (including directories) cannot 531f4f864c1SEric Biggersbe created or linked into an encrypted directory, nor can a name in an 532f4f864c1SEric Biggersencrypted directory be the source or target of a rename, nor can an 533f4f864c1SEric BiggersO_TMPFILE temporary file be created in an encrypted directory. All 534f4f864c1SEric Biggerssuch operations will fail with ENOKEY. 535f4f864c1SEric Biggers 536f4f864c1SEric BiggersIt is not currently possible to backup and restore encrypted files 537f4f864c1SEric Biggerswithout the encryption key. This would require special APIs which 538f4f864c1SEric Biggershave not yet been implemented. 539f4f864c1SEric Biggers 540f4f864c1SEric BiggersEncryption policy enforcement 541f4f864c1SEric Biggers============================= 542f4f864c1SEric Biggers 543f4f864c1SEric BiggersAfter an encryption policy has been set on a directory, all regular 544f4f864c1SEric Biggersfiles, directories, and symbolic links created in that directory 545f4f864c1SEric Biggers(recursively) will inherit that encryption policy. Special files --- 546f4f864c1SEric Biggersthat is, named pipes, device nodes, and UNIX domain sockets --- will 547f4f864c1SEric Biggersnot be encrypted. 548f4f864c1SEric Biggers 549f4f864c1SEric BiggersExcept for those special files, it is forbidden to have unencrypted 550f4f864c1SEric Biggersfiles, or files encrypted with a different encryption policy, in an 551f4f864c1SEric Biggersencrypted directory tree. Attempts to link or rename such a file into 552f5e55e77SEric Biggersan encrypted directory will fail with EXDEV. This is also enforced 553f4f864c1SEric Biggersduring ->lookup() to provide limited protection against offline 554f4f864c1SEric Biggersattacks that try to disable or downgrade encryption in known locations 555f4f864c1SEric Biggerswhere applications may later write sensitive data. It is recommended 556f4f864c1SEric Biggersthat systems implementing a form of "verified boot" take advantage of 557f4f864c1SEric Biggersthis by validating all top-level encryption policies prior to access. 558f4f864c1SEric Biggers 559f4f864c1SEric BiggersImplementation details 560f4f864c1SEric Biggers====================== 561f4f864c1SEric Biggers 562f4f864c1SEric BiggersEncryption context 563f4f864c1SEric Biggers------------------ 564f4f864c1SEric Biggers 565f4f864c1SEric BiggersAn encryption policy is represented on-disk by a :c:type:`struct 566f4f864c1SEric Biggersfscrypt_context`. It is up to individual filesystems to decide where 567f4f864c1SEric Biggersto store it, but normally it would be stored in a hidden extended 568f4f864c1SEric Biggersattribute. It should *not* be exposed by the xattr-related system 569f4f864c1SEric Biggerscalls such as getxattr() and setxattr() because of the special 570f4f864c1SEric Biggerssemantics of the encryption xattr. (In particular, there would be 571f4f864c1SEric Biggersmuch confusion if an encryption policy were to be added to or removed 572f4f864c1SEric Biggersfrom anything other than an empty directory.) The struct is defined 573f4f864c1SEric Biggersas follows:: 574f4f864c1SEric Biggers 575f4f864c1SEric Biggers #define FS_KEY_DESCRIPTOR_SIZE 8 576f4f864c1SEric Biggers #define FS_KEY_DERIVATION_NONCE_SIZE 16 577f4f864c1SEric Biggers 578f4f864c1SEric Biggers struct fscrypt_context { 579f4f864c1SEric Biggers u8 format; 580f4f864c1SEric Biggers u8 contents_encryption_mode; 581f4f864c1SEric Biggers u8 filenames_encryption_mode; 582f4f864c1SEric Biggers u8 flags; 583f4f864c1SEric Biggers u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; 584f4f864c1SEric Biggers u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; 585f4f864c1SEric Biggers }; 586f4f864c1SEric Biggers 587f4f864c1SEric BiggersNote that :c:type:`struct fscrypt_context` contains the same 588f4f864c1SEric Biggersinformation as :c:type:`struct fscrypt_policy` (see `Setting an 589f4f864c1SEric Biggersencryption policy`_), except that :c:type:`struct fscrypt_context` 590f4f864c1SEric Biggersalso contains a nonce. The nonce is randomly generated by the kernel 591f4f864c1SEric Biggersand is used to derive the inode's encryption key as described in 592f4f864c1SEric Biggers`Per-file keys`_. 593f4f864c1SEric Biggers 594f4f864c1SEric BiggersData path changes 595f4f864c1SEric Biggers----------------- 596f4f864c1SEric Biggers 597f4f864c1SEric BiggersFor the read path (->readpage()) of regular files, filesystems can 598f4f864c1SEric Biggersread the ciphertext into the page cache and decrypt it in-place. The 599f4f864c1SEric Biggerspage lock must be held until decryption has finished, to prevent the 600f4f864c1SEric Biggerspage from becoming visible to userspace prematurely. 601f4f864c1SEric Biggers 602f4f864c1SEric BiggersFor the write path (->writepage()) of regular files, filesystems 603f4f864c1SEric Biggerscannot encrypt data in-place in the page cache, since the cached 604f4f864c1SEric Biggersplaintext must be preserved. Instead, filesystems must encrypt into a 605f4f864c1SEric Biggerstemporary buffer or "bounce page", then write out the temporary 606f4f864c1SEric Biggersbuffer. Some filesystems, such as UBIFS, already use temporary 607f4f864c1SEric Biggersbuffers regardless of encryption. Other filesystems, such as ext4 and 608f4f864c1SEric BiggersF2FS, have to allocate bounce pages specially for encryption. 609f4f864c1SEric Biggers 610f4f864c1SEric BiggersFilename hashing and encoding 611f4f864c1SEric Biggers----------------------------- 612f4f864c1SEric Biggers 613f4f864c1SEric BiggersModern filesystems accelerate directory lookups by using indexed 614f4f864c1SEric Biggersdirectories. An indexed directory is organized as a tree keyed by 615f4f864c1SEric Biggersfilename hashes. When a ->lookup() is requested, the filesystem 616f4f864c1SEric Biggersnormally hashes the filename being looked up so that it can quickly 617f4f864c1SEric Biggersfind the corresponding directory entry, if any. 618f4f864c1SEric Biggers 619f4f864c1SEric BiggersWith encryption, lookups must be supported and efficient both with and 620f4f864c1SEric Biggerswithout the encryption key. Clearly, it would not work to hash the 621f4f864c1SEric Biggersplaintext filenames, since the plaintext filenames are unavailable 622f4f864c1SEric Biggerswithout the key. (Hashing the plaintext filenames would also make it 623f4f864c1SEric Biggersimpossible for the filesystem's fsck tool to optimize encrypted 624f4f864c1SEric Biggersdirectories.) Instead, filesystems hash the ciphertext filenames, 625f4f864c1SEric Biggersi.e. the bytes actually stored on-disk in the directory entries. When 626f4f864c1SEric Biggersasked to do a ->lookup() with the key, the filesystem just encrypts 627f4f864c1SEric Biggersthe user-supplied name to get the ciphertext. 628f4f864c1SEric Biggers 629f4f864c1SEric BiggersLookups without the key are more complicated. The raw ciphertext may 630f4f864c1SEric Biggerscontain the ``\0`` and ``/`` characters, which are illegal in 631f4f864c1SEric Biggersfilenames. Therefore, readdir() must base64-encode the ciphertext for 632f4f864c1SEric Biggerspresentation. For most filenames, this works fine; on ->lookup(), the 633f4f864c1SEric Biggersfilesystem just base64-decodes the user-supplied name to get back to 634f4f864c1SEric Biggersthe raw ciphertext. 635f4f864c1SEric Biggers 636f4f864c1SEric BiggersHowever, for very long filenames, base64 encoding would cause the 637f4f864c1SEric Biggersfilename length to exceed NAME_MAX. To prevent this, readdir() 638f4f864c1SEric Biggersactually presents long filenames in an abbreviated form which encodes 639f4f864c1SEric Biggersa strong "hash" of the ciphertext filename, along with the optional 640f4f864c1SEric Biggersfilesystem-specific hash(es) needed for directory lookups. This 641f4f864c1SEric Biggersallows the filesystem to still, with a high degree of confidence, map 642f4f864c1SEric Biggersthe filename given in ->lookup() back to a particular directory entry 643f4f864c1SEric Biggersthat was previously listed by readdir(). See :c:type:`struct 644f4f864c1SEric Biggersfscrypt_digested_name` in the source for more details. 645f4f864c1SEric Biggers 646f4f864c1SEric BiggersNote that the precise way that filenames are presented to userspace 647f4f864c1SEric Biggerswithout the key is subject to change in the future. It is only meant 648f4f864c1SEric Biggersas a way to temporarily present valid filenames so that commands like 649f4f864c1SEric Biggers``rm -r`` work as expected on encrypted directories. 650