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