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