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 | |
| 75 | fscrypt is only resistant to side-channel attacks, such as timing or |
| 76 | electromagnetic attacks, to the extent that the underlying Linux |
| 77 | Cryptographic API algorithms are. If a vulnerable algorithm is used, |
| 78 | such as a table-based implementation of AES, it may be possible for an |
| 79 | attacker to mount a side channel attack against the online system. |
| 80 | Side channel attacks may also be mounted against applications |
| 81 | consuming decrypted data. |
| 82 | |
| 83 | After an encryption key has been provided, fscrypt is not designed to |
| 84 | hide the plaintext file contents or filenames from other users on the |
| 85 | same system, regardless of the visibility of the keyring key. |
| 86 | Instead, existing access control mechanisms such as file mode bits, |
| 87 | POSIX ACLs, LSMs, or mount namespaces should be used for this purpose. |
| 88 | Also note that as long as the encryption keys are *anywhere* in |
| 89 | memory, an online attacker can necessarily compromise them by mounting |
| 90 | a physical attack or by exploiting any kernel security vulnerability |
| 91 | which provides an arbitrary memory read primitive. |
| 92 | |
| 93 | While it is ostensibly possible to "evict" keys from the system, |
| 94 | recently accessed encrypted files will remain accessible at least |
| 95 | until the filesystem is unmounted or the VFS caches are dropped, e.g. |
| 96 | using ``echo 2 > /proc/sys/vm/drop_caches``. Even after that, if the |
| 97 | RAM is compromised before being powered off, it will likely still be |
| 98 | possible to recover portions of the plaintext file contents, if not |
| 99 | some of the encryption keys as well. (Since Linux v4.12, all |
| 100 | in-kernel keys related to fscrypt are sanitized before being freed. |
| 101 | However, userspace would need to do its part as well.) |
| 102 | |
| 103 | Currently, fscrypt does not prevent a user from maliciously providing |
| 104 | an incorrect key for another user's existing encrypted files. A |
| 105 | protection against this is planned. |
| 106 | |
| 107 | Key hierarchy |
| 108 | ============= |
| 109 | |
| 110 | Master Keys |
| 111 | ----------- |
| 112 | |
| 113 | Each encrypted directory tree is protected by a *master key*. Master |
| 114 | keys can be up to 64 bytes long, and must be at least as long as the |
| 115 | greater of the key length needed by the contents and filenames |
| 116 | encryption modes being used. For example, if AES-256-XTS is used for |
| 117 | contents encryption, the master key must be 64 bytes (512 bits). Note |
| 118 | that the XTS mode is defined to require a key twice as long as that |
| 119 | required by the underlying block cipher. |
| 120 | |
| 121 | To "unlock" an encrypted directory tree, userspace must provide the |
| 122 | appropriate master key. There can be any number of master keys, each |
| 123 | of which protects any number of directory trees on any number of |
| 124 | filesystems. |
| 125 | |
| 126 | Userspace should generate master keys either using a cryptographically |
| 127 | secure random number generator, or by using a KDF (Key Derivation |
| 128 | Function). Note that whenever a KDF is used to "stretch" a |
| 129 | lower-entropy secret such as a passphrase, it is critical that a KDF |
| 130 | designed for this purpose be used, such as scrypt, PBKDF2, or Argon2. |
| 131 | |
| 132 | Per-file keys |
| 133 | ------------- |
| 134 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 135 | Since each master key can protect many files, it is necessary to |
| 136 | "tweak" the encryption of each file so that the same plaintext in two |
| 137 | files doesn't map to the same ciphertext, or vice versa. In most |
| 138 | cases, fscrypt does this by deriving per-file keys. When a new |
| 139 | encrypted inode (regular file, directory, or symlink) is created, |
| 140 | fscrypt randomly generates a 16-byte nonce and stores it in the |
| 141 | inode's encryption xattr. Then, it uses a KDF (Key Derivation |
| 142 | Function) to derive the file's key from the master key and nonce. |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 143 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 144 | The Adiantum encryption mode (see `Encryption modes and usage`_) is |
| 145 | special, since it accepts longer IVs and is suitable for both contents |
| 146 | and filenames encryption. For it, a "direct key" option is offered |
| 147 | where the file's nonce is included in the IVs and the master key is |
| 148 | used for encryption directly. This improves performance; however, |
| 149 | users must not use the same master key for any other encryption mode. |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 150 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 151 | Below, the KDF and design considerations are described in more detail. |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 152 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 153 | The current KDF works by encrypting the master key with AES-128-ECB, |
| 154 | using the file's nonce as the AES key. The output is used as the |
| 155 | derived key. If the output is longer than needed, then it is |
| 156 | truncated to the needed length. |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 157 | |
| 158 | Note: this KDF meets the primary security requirement, which is to |
| 159 | produce unique derived keys that preserve the entropy of the master |
| 160 | key, assuming that the master key is already a good pseudorandom key. |
| 161 | However, it is nonstandard and has some problems such as being |
| 162 | reversible, so it is generally considered to be a mistake! It may be |
| 163 | replaced with HKDF or another more standard KDF in the future. |
| 164 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 165 | Key derivation was chosen over key wrapping because wrapped keys would |
| 166 | require larger xattrs which would be less likely to fit in-line in the |
| 167 | filesystem's inode table, and there didn't appear to be any |
| 168 | significant advantages to key wrapping. In particular, currently |
| 169 | there is no requirement to support unlocking a file with multiple |
| 170 | alternative master keys or to support rotating master keys. Instead, |
| 171 | the master keys may be wrapped in userspace, e.g. as is done by the |
| 172 | `fscrypt <https://github.com/google/fscrypt>`_ tool. |
| 173 | |
| 174 | Including the inode number in the IVs was considered. However, it was |
| 175 | rejected as it would have prevented ext4 filesystems from being |
| 176 | resized, and by itself still wouldn't have been sufficient to prevent |
| 177 | the same key from being directly reused for both XTS and CTS-CBC. |
| 178 | |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 179 | Encryption modes and usage |
| 180 | ========================== |
| 181 | |
| 182 | fscrypt allows one encryption mode to be specified for file contents |
| 183 | and one encryption mode to be specified for filenames. Different |
| 184 | directory trees are permitted to use different encryption modes. |
| 185 | Currently, the following pairs of encryption modes are supported: |
| 186 | |
| 187 | - AES-256-XTS for contents and AES-256-CTS-CBC for filenames |
| 188 | - AES-128-CBC for contents and AES-128-CTS-CBC for filenames |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 189 | - Adiantum for both contents and filenames |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 190 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 191 | If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. |
| 192 | |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 193 | AES-128-CBC was added only for low-powered embedded devices with |
| 194 | crypto accelerators such as CAAM or CESA that do not support XTS. |
| 195 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 196 | Adiantum is a (primarily) stream cipher-based mode that is fast even |
| 197 | on CPUs without dedicated crypto instructions. It's also a true |
| 198 | wide-block mode, unlike XTS. It can also eliminate the need to derive |
| 199 | per-file keys. However, it depends on the security of two primitives, |
| 200 | XChaCha12 and AES-256, rather than just one. See the paper |
| 201 | "Adiantum: length-preserving encryption for entry-level processors" |
| 202 | (https://eprint.iacr.org/2018/720.pdf) for more details. To use |
| 203 | Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast |
| 204 | implementations of ChaCha and NHPoly1305 should be enabled, e.g. |
| 205 | CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. |
| 206 | |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 207 | New encryption modes can be added relatively easily, without changes |
| 208 | to individual filesystems. However, authenticated encryption (AE) |
| 209 | modes are not currently supported because of the difficulty of dealing |
| 210 | with ciphertext expansion. |
| 211 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 212 | Contents encryption |
| 213 | ------------------- |
| 214 | |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 215 | For file contents, each filesystem block is encrypted independently. |
| 216 | Currently, only the case where the filesystem block size is equal to |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 217 | the system's page size (usually 4096 bytes) is supported. |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 218 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 219 | Each block's IV is set to the logical block number within the file as |
| 220 | a little endian number, except that: |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 221 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 222 | - With CBC mode encryption, ESSIV is also used. Specifically, each IV |
| 223 | is encrypted with AES-256 where the AES-256 key is the SHA-256 hash |
| 224 | of the file's data encryption key. |
| 225 | |
| 226 | - In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in |
| 227 | the fscrypt_policy), the file's nonce is also appended to the IV. |
| 228 | Currently this is only allowed with the Adiantum encryption mode. |
| 229 | |
| 230 | Filenames encryption |
| 231 | -------------------- |
| 232 | |
| 233 | For filenames, each full filename is encrypted at once. Because of |
| 234 | the requirements to retain support for efficient directory lookups and |
| 235 | filenames of up to 255 bytes, the same IV is used for every filename |
| 236 | in a directory. |
| 237 | |
| 238 | However, each encrypted directory still uses a unique key; or |
| 239 | alternatively (for the "direct key" configuration) has the file's |
| 240 | nonce included in the IVs. Thus, IV reuse is limited to within a |
| 241 | single directory. |
| 242 | |
| 243 | With CTS-CBC, the IV reuse means that when the plaintext filenames |
| 244 | share a common prefix at least as long as the cipher block size (16 |
| 245 | bytes for AES), the corresponding encrypted filenames will also share |
| 246 | a common prefix. This is undesirable. Adiantum does not have this |
| 247 | weakness, as it is a wide-block encryption mode. |
| 248 | |
| 249 | All supported filenames encryption modes accept any plaintext length |
| 250 | >= 16 bytes; cipher block alignment is not required. However, |
| 251 | filenames shorter than 16 bytes are NUL-padded to 16 bytes before |
| 252 | being encrypted. In addition, to reduce leakage of filename lengths |
| 253 | via their ciphertexts, all filenames are NUL-padded to the next 4, 8, |
| 254 | 16, or 32-byte boundary (configurable). 32 is recommended since this |
| 255 | provides the best confidentiality, at the cost of making directory |
| 256 | entries consume slightly more space. Note that since NUL (``\0``) is |
| 257 | not otherwise a valid character in filenames, the padding will never |
| 258 | produce duplicate plaintexts. |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 259 | |
| 260 | Symbolic link targets are considered a type of filename and are |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 261 | encrypted in the same way as filenames in directory entries, except |
| 262 | 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] | 263 | |
| 264 | User API |
| 265 | ======== |
| 266 | |
| 267 | Setting an encryption policy |
| 268 | ---------------------------- |
| 269 | |
| 270 | The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an |
| 271 | empty directory or verifies that a directory or regular file already |
| 272 | has the specified encryption policy. It takes in a pointer to a |
| 273 | :c:type:`struct fscrypt_policy`, defined as follows:: |
| 274 | |
| 275 | #define FS_KEY_DESCRIPTOR_SIZE 8 |
| 276 | |
| 277 | struct fscrypt_policy { |
| 278 | __u8 version; |
| 279 | __u8 contents_encryption_mode; |
| 280 | __u8 filenames_encryption_mode; |
| 281 | __u8 flags; |
| 282 | __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; |
| 283 | }; |
| 284 | |
| 285 | This structure must be initialized as follows: |
| 286 | |
| 287 | - ``version`` must be 0. |
| 288 | |
| 289 | - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must |
| 290 | be set to constants from ``<linux/fs.h>`` which identify the |
| 291 | encryption modes to use. If unsure, use |
| 292 | FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` |
| 293 | and FS_ENCRYPTION_MODE_AES_256_CTS (4) for |
| 294 | ``filenames_encryption_mode``. |
| 295 | |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 296 | - ``flags`` must contain a value from ``<linux/fs.h>`` which |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 297 | identifies the amount of NUL-padding to use when encrypting |
| 298 | filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3). |
Eric Biggers | 8094c3c | 2019-01-06 08:36:21 -0500 | [diff] [blame] | 299 | In addition, if the chosen encryption modes are both |
| 300 | FS_ENCRYPTION_MODE_ADIANTUM, this can contain |
| 301 | FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be |
| 302 | used directly, without key derivation. |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 303 | |
| 304 | - ``master_key_descriptor`` specifies how to find the master key in |
| 305 | the keyring; see `Adding keys`_. It is up to userspace to choose a |
| 306 | unique ``master_key_descriptor`` for each master key. The e4crypt |
| 307 | and fscrypt tools use the first 8 bytes of |
| 308 | ``SHA-512(SHA-512(master_key))``, but this particular scheme is not |
| 309 | required. Also, the master key need not be in the keyring yet when |
| 310 | FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added |
| 311 | before any files can be created in the encrypted directory. |
| 312 | |
| 313 | If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY |
| 314 | verifies that the file is an empty directory. If so, the specified |
| 315 | encryption policy is assigned to the directory, turning it into an |
| 316 | encrypted directory. After that, and after providing the |
| 317 | corresponding master key as described in `Adding keys`_, all regular |
| 318 | files, directories (recursively), and symlinks created in the |
| 319 | directory will be encrypted, inheriting the same encryption policy. |
| 320 | The filenames in the directory's entries will be encrypted as well. |
| 321 | |
| 322 | Alternatively, if the file is already encrypted, then |
| 323 | FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption |
| 324 | policy exactly matches the actual one. If they match, then the ioctl |
| 325 | returns 0. Otherwise, it fails with EEXIST. This works on both |
| 326 | regular files and directories, including nonempty directories. |
| 327 | |
| 328 | Note that the ext4 filesystem does not allow the root directory to be |
| 329 | encrypted, even if it is empty. Users who want to encrypt an entire |
| 330 | filesystem with one key should consider using dm-crypt instead. |
| 331 | |
| 332 | FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors: |
| 333 | |
| 334 | - ``EACCES``: the file is not owned by the process's uid, nor does the |
| 335 | process have the CAP_FOWNER capability in a namespace with the file |
| 336 | owner's uid mapped |
| 337 | - ``EEXIST``: the file is already encrypted with an encryption policy |
| 338 | different from the one specified |
| 339 | - ``EINVAL``: an invalid encryption policy was specified (invalid |
| 340 | version, mode(s), or flags) |
| 341 | - ``ENOTDIR``: the file is unencrypted and is a regular file, not a |
| 342 | directory |
| 343 | - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory |
| 344 | - ``ENOTTY``: this type of filesystem does not implement encryption |
| 345 | - ``EOPNOTSUPP``: the kernel was not configured with encryption |
Chandan Rajendra | 643fa96 | 2018-12-12 15:20:12 +0530 | [diff] [blame] | 346 | support for filesystems, or the filesystem superblock has not |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 347 | had encryption enabled on it. (For example, to use encryption on an |
Chandan Rajendra | 643fa96 | 2018-12-12 15:20:12 +0530 | [diff] [blame] | 348 | ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 349 | kernel config, and the superblock must have had the "encrypt" |
| 350 | feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O |
| 351 | encrypt``.) |
| 352 | - ``EPERM``: this directory may not be encrypted, e.g. because it is |
| 353 | the root directory of an ext4 filesystem |
| 354 | - ``EROFS``: the filesystem is readonly |
| 355 | |
| 356 | Getting an encryption policy |
| 357 | ---------------------------- |
| 358 | |
| 359 | The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct |
| 360 | fscrypt_policy`, if any, for a directory or regular file. See above |
| 361 | for the struct definition. No additional permissions are required |
| 362 | beyond the ability to open the file. |
| 363 | |
| 364 | FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors: |
| 365 | |
| 366 | - ``EINVAL``: the file is encrypted, but it uses an unrecognized |
| 367 | encryption context format |
| 368 | - ``ENODATA``: the file is not encrypted |
| 369 | - ``ENOTTY``: this type of filesystem does not implement encryption |
| 370 | - ``EOPNOTSUPP``: the kernel was not configured with encryption |
| 371 | support for this filesystem |
| 372 | |
| 373 | Note: if you only need to know whether a file is encrypted or not, on |
| 374 | most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl |
| 375 | and check for FS_ENCRYPT_FL, or to use the statx() system call and |
| 376 | check for STATX_ATTR_ENCRYPTED in stx_attributes. |
| 377 | |
| 378 | Getting the per-filesystem salt |
| 379 | ------------------------------- |
| 380 | |
| 381 | Some filesystems, such as ext4 and F2FS, also support the deprecated |
| 382 | ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly |
| 383 | generated 16-byte value stored in the filesystem superblock. This |
| 384 | value is intended to used as a salt when deriving an encryption key |
| 385 | from a passphrase or other low-entropy user credential. |
| 386 | |
| 387 | FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to |
| 388 | generate and manage any needed salt(s) in userspace. |
| 389 | |
| 390 | Adding keys |
| 391 | ----------- |
| 392 | |
| 393 | To provide a master key, userspace must add it to an appropriate |
| 394 | keyring using the add_key() system call (see: |
| 395 | ``Documentation/security/keys/core.rst``). The key type must be |
| 396 | "logon"; keys of this type are kept in kernel memory and cannot be |
| 397 | read back by userspace. The key description must be "fscrypt:" |
| 398 | followed by the 16-character lower case hex representation of the |
| 399 | ``master_key_descriptor`` that was set in the encryption policy. The |
| 400 | key payload must conform to the following structure:: |
| 401 | |
| 402 | #define FS_MAX_KEY_SIZE 64 |
| 403 | |
| 404 | struct fscrypt_key { |
| 405 | u32 mode; |
| 406 | u8 raw[FS_MAX_KEY_SIZE]; |
| 407 | u32 size; |
| 408 | }; |
| 409 | |
| 410 | ``mode`` is ignored; just set it to 0. The actual key is provided in |
| 411 | ``raw`` with ``size`` indicating its size in bytes. That is, the |
| 412 | bytes ``raw[0..size-1]`` (inclusive) are the actual key. |
| 413 | |
| 414 | The key description prefix "fscrypt:" may alternatively be replaced |
| 415 | with a filesystem-specific prefix such as "ext4:". However, the |
| 416 | filesystem-specific prefixes are deprecated and should not be used in |
| 417 | new programs. |
| 418 | |
| 419 | There are several different types of keyrings in which encryption keys |
| 420 | may be placed, such as a session keyring, a user session keyring, or a |
| 421 | user keyring. Each key must be placed in a keyring that is "attached" |
| 422 | to all processes that might need to access files encrypted with it, in |
| 423 | the sense that request_key() will find the key. Generally, if only |
| 424 | processes belonging to a specific user need to access a given |
| 425 | encrypted directory and no session keyring has been installed, then |
| 426 | that directory's key should be placed in that user's user session |
| 427 | keyring or user keyring. Otherwise, a session keyring should be |
| 428 | installed if needed, and the key should be linked into that session |
| 429 | keyring, or in a keyring linked into that session keyring. |
| 430 | |
| 431 | Note: introducing the complex visibility semantics of keyrings here |
| 432 | was arguably a mistake --- especially given that by design, after any |
| 433 | process successfully opens an encrypted file (thereby setting up the |
| 434 | per-file key), possessing the keyring key is not actually required for |
| 435 | any process to read/write the file until its in-memory inode is |
| 436 | evicted. In the future there probably should be a way to provide keys |
| 437 | directly to the filesystem instead, which would make the intended |
| 438 | semantics clearer. |
| 439 | |
| 440 | Access semantics |
| 441 | ================ |
| 442 | |
| 443 | With the key |
| 444 | ------------ |
| 445 | |
| 446 | With the encryption key, encrypted regular files, directories, and |
| 447 | symlinks behave very similarly to their unencrypted counterparts --- |
| 448 | after all, the encryption is intended to be transparent. However, |
| 449 | astute users may notice some differences in behavior: |
| 450 | |
| 451 | - Unencrypted files, or files encrypted with a different encryption |
| 452 | policy (i.e. different key, modes, or flags), cannot be renamed or |
| 453 | linked into an encrypted directory; see `Encryption policy |
Eric Biggers | f5e55e7 | 2019-01-22 16:20:21 -0800 | [diff] [blame] | 454 | enforcement`_. Attempts to do so will fail with EXDEV. However, |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 455 | encrypted files can be renamed within an encrypted directory, or |
| 456 | into an unencrypted directory. |
| 457 | |
Eric Biggers | f5e55e7 | 2019-01-22 16:20:21 -0800 | [diff] [blame] | 458 | Note: "moving" an unencrypted file into an encrypted directory, e.g. |
| 459 | with the `mv` program, is implemented in userspace by a copy |
| 460 | followed by a delete. Be aware that the original unencrypted data |
| 461 | may remain recoverable from free space on the disk; prefer to keep |
| 462 | all files encrypted from the very beginning. The `shred` program |
| 463 | may be used to overwrite the source files but isn't guaranteed to be |
| 464 | effective on all filesystems and storage devices. |
| 465 | |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 466 | - Direct I/O is not supported on encrypted files. Attempts to use |
| 467 | direct I/O on such files will fall back to buffered I/O. |
| 468 | |
| 469 | - The fallocate operations FALLOC_FL_COLLAPSE_RANGE, |
| 470 | FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported |
| 471 | on encrypted files and will fail with EOPNOTSUPP. |
| 472 | |
| 473 | - Online defragmentation of encrypted files is not supported. The |
| 474 | EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with |
| 475 | EOPNOTSUPP. |
| 476 | |
| 477 | - The ext4 filesystem does not support data journaling with encrypted |
| 478 | regular files. It will fall back to ordered data mode instead. |
| 479 | |
| 480 | - DAX (Direct Access) is not supported on encrypted files. |
| 481 | |
| 482 | - The st_size of an encrypted symlink will not necessarily give the |
| 483 | length of the symlink target as required by POSIX. It will actually |
Eric Biggers | 2f46a2b | 2018-01-11 23:30:09 -0500 | [diff] [blame] | 484 | give the length of the ciphertext, which will be slightly longer |
| 485 | than the plaintext due to NUL-padding and an extra 2-byte overhead. |
| 486 | |
| 487 | - The maximum length of an encrypted symlink is 2 bytes shorter than |
| 488 | the maximum length of an unencrypted symlink. For example, on an |
| 489 | EXT4 filesystem with a 4K block size, unencrypted symlinks can be up |
| 490 | to 4095 bytes long, while encrypted symlinks can only be up to 4093 |
| 491 | bytes long (both lengths excluding the terminating null). |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 492 | |
| 493 | Note that mmap *is* supported. This is possible because the pagecache |
| 494 | for an encrypted file contains the plaintext, not the ciphertext. |
| 495 | |
| 496 | Without the key |
| 497 | --------------- |
| 498 | |
| 499 | Some filesystem operations may be performed on encrypted regular |
| 500 | files, directories, and symlinks even before their encryption key has |
| 501 | been provided: |
| 502 | |
| 503 | - File metadata may be read, e.g. using stat(). |
| 504 | |
| 505 | - Directories may be listed, in which case the filenames will be |
| 506 | listed in an encoded form derived from their ciphertext. The |
| 507 | current encoding algorithm is described in `Filename hashing and |
| 508 | encoding`_. The algorithm is subject to change, but it is |
| 509 | guaranteed that the presented filenames will be no longer than |
| 510 | NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and |
| 511 | will uniquely identify directory entries. |
| 512 | |
| 513 | The ``.`` and ``..`` directory entries are special. They are always |
| 514 | present and are not encrypted or encoded. |
| 515 | |
| 516 | - Files may be deleted. That is, nondirectory files may be deleted |
| 517 | with unlink() as usual, and empty directories may be deleted with |
| 518 | rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as |
| 519 | expected. |
| 520 | |
| 521 | - Symlink targets may be read and followed, but they will be presented |
| 522 | in encrypted form, similar to filenames in directories. Hence, they |
| 523 | are unlikely to point to anywhere useful. |
| 524 | |
| 525 | Without the key, regular files cannot be opened or truncated. |
| 526 | Attempts to do so will fail with ENOKEY. This implies that any |
| 527 | regular file operations that require a file descriptor, such as |
| 528 | read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden. |
| 529 | |
| 530 | Also without the key, files of any type (including directories) cannot |
| 531 | be created or linked into an encrypted directory, nor can a name in an |
| 532 | encrypted directory be the source or target of a rename, nor can an |
| 533 | O_TMPFILE temporary file be created in an encrypted directory. All |
| 534 | such operations will fail with ENOKEY. |
| 535 | |
| 536 | It is not currently possible to backup and restore encrypted files |
| 537 | without the encryption key. This would require special APIs which |
| 538 | have not yet been implemented. |
| 539 | |
| 540 | Encryption policy enforcement |
| 541 | ============================= |
| 542 | |
| 543 | After an encryption policy has been set on a directory, all regular |
| 544 | files, directories, and symbolic links created in that directory |
| 545 | (recursively) will inherit that encryption policy. Special files --- |
| 546 | that is, named pipes, device nodes, and UNIX domain sockets --- will |
| 547 | not be encrypted. |
| 548 | |
| 549 | Except for those special files, it is forbidden to have unencrypted |
| 550 | files, or files encrypted with a different encryption policy, in an |
| 551 | encrypted directory tree. Attempts to link or rename such a file into |
Eric Biggers | f5e55e7 | 2019-01-22 16:20:21 -0800 | [diff] [blame] | 552 | an encrypted directory will fail with EXDEV. This is also enforced |
Eric Biggers | f4f864c | 2017-10-29 06:30:14 -0400 | [diff] [blame] | 553 | during ->lookup() to provide limited protection against offline |
| 554 | attacks that try to disable or downgrade encryption in known locations |
| 555 | where applications may later write sensitive data. It is recommended |
| 556 | that systems implementing a form of "verified boot" take advantage of |
| 557 | this by validating all top-level encryption policies prior to access. |
| 558 | |
| 559 | Implementation details |
| 560 | ====================== |
| 561 | |
| 562 | Encryption context |
| 563 | ------------------ |
| 564 | |
| 565 | An encryption policy is represented on-disk by a :c:type:`struct |
| 566 | fscrypt_context`. It is up to individual filesystems to decide where |
| 567 | to store it, but normally it would be stored in a hidden extended |
| 568 | attribute. It should *not* be exposed by the xattr-related system |
| 569 | calls such as getxattr() and setxattr() because of the special |
| 570 | semantics of the encryption xattr. (In particular, there would be |
| 571 | much confusion if an encryption policy were to be added to or removed |
| 572 | from anything other than an empty directory.) The struct is defined |
| 573 | as follows:: |
| 574 | |
| 575 | #define FS_KEY_DESCRIPTOR_SIZE 8 |
| 576 | #define FS_KEY_DERIVATION_NONCE_SIZE 16 |
| 577 | |
| 578 | struct fscrypt_context { |
| 579 | u8 format; |
| 580 | u8 contents_encryption_mode; |
| 581 | u8 filenames_encryption_mode; |
| 582 | u8 flags; |
| 583 | u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE]; |
| 584 | u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; |
| 585 | }; |
| 586 | |
| 587 | Note that :c:type:`struct fscrypt_context` contains the same |
| 588 | information as :c:type:`struct fscrypt_policy` (see `Setting an |
| 589 | encryption policy`_), except that :c:type:`struct fscrypt_context` |
| 590 | also contains a nonce. The nonce is randomly generated by the kernel |
| 591 | and is used to derive the inode's encryption key as described in |
| 592 | `Per-file keys`_. |
| 593 | |
| 594 | Data path changes |
| 595 | ----------------- |
| 596 | |
| 597 | For the read path (->readpage()) of regular files, filesystems can |
| 598 | read the ciphertext into the page cache and decrypt it in-place. The |
| 599 | page lock must be held until decryption has finished, to prevent the |
| 600 | page from becoming visible to userspace prematurely. |
| 601 | |
| 602 | For the write path (->writepage()) of regular files, filesystems |
| 603 | cannot encrypt data in-place in the page cache, since the cached |
| 604 | plaintext must be preserved. Instead, filesystems must encrypt into a |
| 605 | temporary buffer or "bounce page", then write out the temporary |
| 606 | buffer. Some filesystems, such as UBIFS, already use temporary |
| 607 | buffers regardless of encryption. Other filesystems, such as ext4 and |
| 608 | F2FS, have to allocate bounce pages specially for encryption. |
| 609 | |
| 610 | Filename hashing and encoding |
| 611 | ----------------------------- |
| 612 | |
| 613 | Modern filesystems accelerate directory lookups by using indexed |
| 614 | directories. An indexed directory is organized as a tree keyed by |
| 615 | filename hashes. When a ->lookup() is requested, the filesystem |
| 616 | normally hashes the filename being looked up so that it can quickly |
| 617 | find the corresponding directory entry, if any. |
| 618 | |
| 619 | With encryption, lookups must be supported and efficient both with and |
| 620 | without the encryption key. Clearly, it would not work to hash the |
| 621 | plaintext filenames, since the plaintext filenames are unavailable |
| 622 | without the key. (Hashing the plaintext filenames would also make it |
| 623 | impossible for the filesystem's fsck tool to optimize encrypted |
| 624 | directories.) Instead, filesystems hash the ciphertext filenames, |
| 625 | i.e. the bytes actually stored on-disk in the directory entries. When |
| 626 | asked to do a ->lookup() with the key, the filesystem just encrypts |
| 627 | the user-supplied name to get the ciphertext. |
| 628 | |
| 629 | Lookups without the key are more complicated. The raw ciphertext may |
| 630 | contain the ``\0`` and ``/`` characters, which are illegal in |
| 631 | filenames. Therefore, readdir() must base64-encode the ciphertext for |
| 632 | presentation. For most filenames, this works fine; on ->lookup(), the |
| 633 | filesystem just base64-decodes the user-supplied name to get back to |
| 634 | the raw ciphertext. |
| 635 | |
| 636 | However, for very long filenames, base64 encoding would cause the |
| 637 | filename length to exceed NAME_MAX. To prevent this, readdir() |
| 638 | actually presents long filenames in an abbreviated form which encodes |
| 639 | a strong "hash" of the ciphertext filename, along with the optional |
| 640 | filesystem-specific hash(es) needed for directory lookups. This |
| 641 | allows the filesystem to still, with a high degree of confidence, map |
| 642 | the filename given in ->lookup() back to a particular directory entry |
| 643 | that was previously listed by readdir(). See :c:type:`struct |
| 644 | fscrypt_digested_name` in the source for more details. |
| 645 | |
| 646 | Note that the precise way that filenames are presented to userspace |
| 647 | without the key is subject to change in the future. It is only meant |
| 648 | as a way to temporarily present valid filenames so that commands like |
| 649 | ``rm -r`` work as expected on encrypted directories. |