| 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, UBIFS,
|
| 35 | and CephFS. This allows encrypted files to be read and written
|
| 36 | without caching both the decrypted and encrypted pages in the
|
| 37 | pagecache, thereby nearly halving the memory used and bringing it in
|
| 38 | line with unencrypted files. Similarly, half as many dentries and
|
| 39 | inodes are needed. eCryptfs also limits encrypted filenames to 143
|
| 40 | bytes, causing application compatibility issues; fscrypt allows the
|
| 41 | full 255 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API
|
| 42 | can be 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 against online attacks. In detail:
|
| 74 |
|
| 75 | Side-channel attacks
|
| 76 | ~~~~~~~~~~~~~~~~~~~~
|
| 77 |
|
| 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 or inline encryption hardware are. If a
|
| 81 | vulnerable algorithm is used, such as a table-based implementation of
|
| 82 | AES, it may be possible for an attacker to mount a side channel attack
|
| 83 | against the online system. Side channel attacks may also be mounted
|
| 84 | against applications consuming decrypted data.
|
| 85 |
|
| 86 | Unauthorized file access
|
| 87 | ~~~~~~~~~~~~~~~~~~~~~~~~
|
| 88 |
|
| 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.
|
| 93 |
|
| 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 | Read-only kernel memory compromise
|
| 103 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 104 |
|
| 105 | Unless `hardware-wrapped keys`_ are used, an attacker who gains the
|
| 106 | ability to read from arbitrary kernel memory, e.g. by mounting a
|
| 107 | physical attack or by exploiting a kernel security vulnerability, can
|
| 108 | compromise all fscrypt keys that are currently in-use. This also
|
| 109 | extends to cold boot attacks; if the system is suddenly powered off,
|
| 110 | keys the system was using may remain in memory for a short time.
|
| 111 |
|
| 112 | However, if hardware-wrapped keys are used, then the fscrypt master
|
| 113 | keys and file contents encryption keys (but not other types of fscrypt
|
| 114 | subkeys such as filenames encryption keys) are protected from
|
| 115 | compromises of arbitrary kernel memory.
|
| 116 |
|
| 117 | In addition, fscrypt allows encryption keys to be removed from the
|
| 118 | kernel, which may protect them from later compromise.
|
| 119 |
|
| 120 | In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the
|
| 121 | FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
|
| 122 | encryption key from kernel memory. If it does so, it will also try to
|
| 123 | evict all cached inodes which had been "unlocked" using the key,
|
| 124 | thereby wiping their per-file keys and making them once again appear
|
| 125 | "locked", i.e. in ciphertext or encrypted form.
|
| 126 |
|
| 127 | However, these ioctls have some limitations:
|
| 128 |
|
| 129 | - Per-file keys for in-use files will *not* be removed or wiped.
|
| 130 | Therefore, for maximum effect, userspace should close the relevant
|
| 131 | encrypted files and directories before removing a master key, as
|
| 132 | well as kill any processes whose working directory is in an affected
|
| 133 | encrypted directory.
|
| 134 |
|
| 135 | - The kernel cannot magically wipe copies of the master key(s) that
|
| 136 | userspace might have as well. Therefore, userspace must wipe all
|
| 137 | copies of the master key(s) it makes as well; normally this should
|
| 138 | be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting
|
| 139 | for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies
|
| 140 | to all higher levels in the key hierarchy. Userspace should also
|
| 141 | follow other security precautions such as mlock()ing memory
|
| 142 | containing keys to prevent it from being swapped out.
|
| 143 |
|
| 144 | - In general, decrypted contents and filenames in the kernel VFS
|
| 145 | caches are freed but not wiped. Therefore, portions thereof may be
|
| 146 | recoverable from freed memory, even after the corresponding key(s)
|
| 147 | were wiped. To partially solve this, you can add init_on_free=1 to
|
| 148 | your kernel command line. However, this has a performance cost.
|
| 149 |
|
| 150 | - Secret keys might still exist in CPU registers or in other places
|
| 151 | not explicitly considered here.
|
| 152 |
|
| 153 | Full system compromise
|
| 154 | ~~~~~~~~~~~~~~~~~~~~~~
|
| 155 |
|
| 156 | An attacker who gains "root" access and/or the ability to execute
|
| 157 | arbitrary kernel code can freely exfiltrate data that is protected by
|
| 158 | any in-use fscrypt keys. Thus, usually fscrypt provides no meaningful
|
| 159 | protection in this scenario. (Data that is protected by a key that is
|
| 160 | absent throughout the entire attack remains protected, modulo the
|
| 161 | limitations of key removal mentioned above in the case where the key
|
| 162 | was removed prior to the attack.)
|
| 163 |
|
| 164 | However, if `hardware-wrapped keys`_ are used, such attackers will be
|
| 165 | unable to exfiltrate the master keys or file contents keys in a form
|
| 166 | that will be usable after the system is powered off. This may be
|
| 167 | useful if the attacker is significantly time-limited and/or
|
| 168 | bandwidth-limited, so they can only exfiltrate some data and need to
|
| 169 | rely on a later offline attack to exfiltrate the rest of it.
|
| 170 |
|
| 171 | Limitations of v1 policies
|
| 172 | ~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 173 |
|
| 174 | v1 encryption policies have some weaknesses with respect to online
|
| 175 | attacks:
|
| 176 |
|
| 177 | - There is no verification that the provided master key is correct.
|
| 178 | Therefore, a malicious user can temporarily associate the wrong key
|
| 179 | with another user's encrypted files to which they have read-only
|
| 180 | access. Because of filesystem caching, the wrong key will then be
|
| 181 | used by the other user's accesses to those files, even if the other
|
| 182 | user has the correct key in their own keyring. This violates the
|
| 183 | meaning of "read-only access".
|
| 184 |
|
| 185 | - A compromise of a per-file key also compromises the master key from
|
| 186 | which it was derived.
|
| 187 |
|
| 188 | - Non-root users cannot securely remove encryption keys.
|
| 189 |
|
| 190 | All the above problems are fixed with v2 encryption policies. For
|
| 191 | this reason among others, v1 encryption policies are deprecated. Use
|
| 192 | v2 encryption policies on all new encrypted directories.
|
| 193 |
|
| 194 | Key hierarchy
|
| 195 | =============
|
| 196 |
|
| 197 | Note: this section assumes the use of raw keys rather than
|
| 198 | hardware-wrapped keys. The use of hardware-wrapped keys modifies the
|
| 199 | key hierarchy slightly. For details, see `Hardware-wrapped keys`_.
|
| 200 |
|
| 201 | Master Keys
|
| 202 | -----------
|
| 203 |
|
| 204 | Each encrypted directory tree is protected by a *master key*. Master
|
| 205 | keys can be up to 64 bytes long, and must be at least as long as the
|
| 206 | greater of the security strength of the contents and filenames
|
| 207 | encryption modes being used. For example, if any AES-256 mode is
|
| 208 | used, the master key must be at least 256 bits, i.e. 32 bytes. A
|
| 209 | stricter requirement applies if the key is used by a v1 encryption
|
| 210 | policy and AES-256-XTS is used; such keys must be 64 bytes.
|
| 211 |
|
| 212 | To "unlock" an encrypted directory tree, userspace must provide the
|
| 213 | appropriate master key. There can be any number of master keys, each
|
| 214 | of which protects any number of directory trees on any number of
|
| 215 | filesystems.
|
| 216 |
|
| 217 | Master keys must be real cryptographic keys, i.e. indistinguishable
|
| 218 | from random bytestrings of the same length. This implies that users
|
| 219 | **must not** directly use a password as a master key, zero-pad a
|
| 220 | shorter key, or repeat a shorter key. Security cannot be guaranteed
|
| 221 | if userspace makes any such error, as the cryptographic proofs and
|
| 222 | analysis would no longer apply.
|
| 223 |
|
| 224 | Instead, users should generate master keys either using a
|
| 225 | cryptographically secure random number generator, or by using a KDF
|
| 226 | (Key Derivation Function). The kernel does not do any key stretching;
|
| 227 | therefore, if userspace derives the key from a low-entropy secret such
|
| 228 | as a passphrase, it is critical that a KDF designed for this purpose
|
| 229 | be used, such as scrypt, PBKDF2, or Argon2.
|
| 230 |
|
| 231 | Key derivation function
|
| 232 | -----------------------
|
| 233 |
|
| 234 | With one exception, fscrypt never uses the master key(s) for
|
| 235 | encryption directly. Instead, they are only used as input to a KDF
|
| 236 | (Key Derivation Function) to derive the actual keys.
|
| 237 |
|
| 238 | The KDF used for a particular master key differs depending on whether
|
| 239 | the key is used for v1 encryption policies or for v2 encryption
|
| 240 | policies. Users **must not** use the same key for both v1 and v2
|
| 241 | encryption policies. (No real-world attack is currently known on this
|
| 242 | specific case of key reuse, but its security cannot be guaranteed
|
| 243 | since the cryptographic proofs and analysis would no longer apply.)
|
| 244 |
|
| 245 | For v1 encryption policies, the KDF only supports deriving per-file
|
| 246 | encryption keys. It works by encrypting the master key with
|
| 247 | AES-128-ECB, using the file's 16-byte nonce as the AES key. The
|
| 248 | resulting ciphertext is used as the derived key. If the ciphertext is
|
| 249 | longer than needed, then it is truncated to the needed length.
|
| 250 |
|
| 251 | For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
|
| 252 | passed as the "input keying material", no salt is used, and a distinct
|
| 253 | "application-specific information string" is used for each distinct
|
| 254 | key to be derived. For example, when a per-file encryption key is
|
| 255 | derived, the application-specific information string is the file's
|
| 256 | nonce prefixed with "fscrypt\\0" and a context byte. Different
|
| 257 | context bytes are used for other types of derived keys.
|
| 258 |
|
| 259 | HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
|
| 260 | HKDF is more flexible, is nonreversible, and evenly distributes
|
| 261 | entropy from the master key. HKDF is also standardized and widely
|
| 262 | used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
|
| 263 |
|
| 264 | Per-file encryption keys
|
| 265 | ------------------------
|
| 266 |
|
| 267 | Since each master key can protect many files, it is necessary to
|
| 268 | "tweak" the encryption of each file so that the same plaintext in two
|
| 269 | files doesn't map to the same ciphertext, or vice versa. In most
|
| 270 | cases, fscrypt does this by deriving per-file keys. When a new
|
| 271 | encrypted inode (regular file, directory, or symlink) is created,
|
| 272 | fscrypt randomly generates a 16-byte nonce and stores it in the
|
| 273 | inode's encryption xattr. Then, it uses a KDF (as described in `Key
|
| 274 | derivation function`_) to derive the file's key from the master key
|
| 275 | and nonce.
|
| 276 |
|
| 277 | Key derivation was chosen over key wrapping because wrapped keys would
|
| 278 | require larger xattrs which would be less likely to fit in-line in the
|
| 279 | filesystem's inode table, and there didn't appear to be any
|
| 280 | significant advantages to key wrapping. In particular, currently
|
| 281 | there is no requirement to support unlocking a file with multiple
|
| 282 | alternative master keys or to support rotating master keys. Instead,
|
| 283 | the master keys may be wrapped in userspace, e.g. as is done by the
|
| 284 | `fscrypt <https://github.com/google/fscrypt>`_ tool.
|
| 285 |
|
| 286 | DIRECT_KEY policies
|
| 287 | -------------------
|
| 288 |
|
| 289 | The Adiantum encryption mode (see `Encryption modes and usage`_) is
|
| 290 | suitable for both contents and filenames encryption, and it accepts
|
| 291 | long IVs --- long enough to hold both an 8-byte data unit index and a
|
| 292 | 16-byte per-file nonce. Also, the overhead of each Adiantum key is
|
| 293 | greater than that of an AES-256-XTS key.
|
| 294 |
|
| 295 | Therefore, to improve performance and save memory, for Adiantum a
|
| 296 | "direct key" configuration is supported. When the user has enabled
|
| 297 | this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
|
| 298 | per-file encryption keys are not used. Instead, whenever any data
|
| 299 | (contents or filenames) is encrypted, the file's 16-byte nonce is
|
| 300 | included in the IV. Moreover:
|
| 301 |
|
| 302 | - For v1 encryption policies, the encryption is done directly with the
|
| 303 | master key. Because of this, users **must not** use the same master
|
| 304 | key for any other purpose, even for other v1 policies.
|
| 305 |
|
| 306 | - For v2 encryption policies, the encryption is done with a per-mode
|
| 307 | key derived using the KDF. Users may use the same master key for
|
| 308 | other v2 encryption policies. However, using a distinct master key
|
| 309 | for each policy is still the best practice and normal usage.
|
| 310 |
|
| 311 | IV_INO_LBLK_64 policies
|
| 312 | -----------------------
|
| 313 |
|
| 314 | When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy,
|
| 315 | the encryption keys are derived from the master key, encryption mode
|
| 316 | number, and filesystem UUID. This normally results in all files
|
| 317 | protected by the same master key sharing a single contents encryption
|
| 318 | key and a single filenames encryption key. To still encrypt different
|
| 319 | files' data differently, inode numbers are included in the IVs.
|
| 320 | Consequently, shrinking the filesystem may not be allowed.
|
| 321 |
|
| 322 | This format is optimized for use with inline encryption hardware
|
| 323 | compliant with the UFS standard, which supports only 64 IV bits per
|
| 324 | I/O request and may have only a small number of keyslots.
|
| 325 |
|
| 326 | IV_INO_LBLK_32 policies
|
| 327 | -----------------------
|
| 328 |
|
| 329 | IV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for
|
| 330 | IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
|
| 331 | SipHash key is derived from the master key) and added to the file data
|
| 332 | unit index mod 2^32 to produce a 32-bit IV.
|
| 333 |
|
| 334 | This format is optimized for use with inline encryption hardware
|
| 335 | compliant with the eMMC v5.2 standard, which supports only 32 IV bits
|
| 336 | per I/O request and may have only a small number of keyslots. This
|
| 337 | format results in some level of IV reuse, so it should only be used
|
| 338 | when necessary due to hardware limitations.
|
| 339 |
|
| 340 | IV_INO_LBLK_32 is supported only when the filesystem block size is
|
| 341 | equal to the page size.
|
| 342 |
|
| 343 | Key identifiers
|
| 344 | ---------------
|
| 345 |
|
| 346 | For master keys used for v2 encryption policies, a unique 16-byte "key
|
| 347 | identifier" is also derived using the KDF. This value is stored in
|
| 348 | the clear, since it is needed to reliably identify the key itself.
|
| 349 |
|
| 350 | Dirhash keys
|
| 351 | ------------
|
| 352 |
|
| 353 | For directories that are indexed using a secret-keyed dirhash over the
|
| 354 | plaintext filenames, the KDF is also used to derive a 128-bit
|
| 355 | SipHash-2-4 key per directory in order to hash filenames. This works
|
| 356 | just like deriving a per-file encryption key, except that a different
|
| 357 | KDF context is used. Currently, only casefolded ("case-insensitive")
|
| 358 | encrypted directories use this style of hashing.
|
| 359 |
|
| 360 | Encryption modes and usage
|
| 361 | ==========================
|
| 362 |
|
| 363 | fscrypt allows one encryption mode to be specified for file contents
|
| 364 | and one encryption mode to be specified for filenames. Different
|
| 365 | directory trees are permitted to use different encryption modes.
|
| 366 |
|
| 367 | Supported modes
|
| 368 | ---------------
|
| 369 |
|
| 370 | Currently, the following pairs of encryption modes are supported:
|
| 371 |
|
| 372 | - AES-256-XTS for contents and AES-256-CBC-CTS for filenames
|
| 373 | - AES-256-XTS for contents and AES-256-HCTR2 for filenames
|
| 374 | - Adiantum for both contents and filenames
|
| 375 | - AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames
|
| 376 | - SM4-XTS for contents and SM4-CBC-CTS for filenames
|
| 377 |
|
| 378 | Note: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS.
|
| 379 | So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.
|
| 380 |
|
| 381 | Authenticated encryption modes are not currently supported because of
|
| 382 | the difficulty of dealing with ciphertext expansion. Therefore,
|
| 383 | contents encryption uses a block cipher in `XTS mode
|
| 384 | <https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or
|
| 385 | `CBC-ESSIV mode
|
| 386 | <https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_,
|
| 387 | or a wide-block cipher. Filenames encryption uses a
|
| 388 | block cipher in `CBC-CTS mode
|
| 389 | <https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
|
| 390 | cipher.
|
| 391 |
|
| 392 | The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default.
|
| 393 | It is also the only option that is *guaranteed* to always be supported
|
| 394 | if the kernel supports fscrypt at all; see `Kernel config options`_.
|
| 395 |
|
| 396 | The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
|
| 397 | upgrades the filenames encryption to use a wide-block cipher. (A
|
| 398 | *wide-block cipher*, also called a tweakable super-pseudorandom
|
| 399 | permutation, has the property that changing one bit scrambles the
|
| 400 | entire result.) As described in `Filenames encryption`_, a wide-block
|
| 401 | cipher is the ideal mode for the problem domain, though CBC-CTS is the
|
| 402 | "least bad" choice among the alternatives. For more information about
|
| 403 | HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_.
|
| 404 |
|
| 405 | Adiantum is recommended on systems where AES is too slow due to lack
|
| 406 | of hardware acceleration for AES. Adiantum is a wide-block cipher
|
| 407 | that uses XChaCha12 and AES-256 as its underlying components. Most of
|
| 408 | the work is done by XChaCha12, which is much faster than AES when AES
|
| 409 | acceleration is unavailable. For more information about Adiantum, see
|
| 410 | `the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_.
|
| 411 |
|
| 412 | The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair was added to try to
|
| 413 | provide a more efficient option for systems that lack AES instructions
|
| 414 | in the CPU but do have a non-inline crypto engine such as CAAM or CESA
|
| 415 | that supports AES-CBC (and not AES-XTS). This is deprecated. It has
|
| 416 | been shown that just doing AES on the CPU is actually faster.
|
| 417 | Moreover, Adiantum is faster still and is recommended on such systems.
|
| 418 |
|
| 419 | The remaining mode pairs are the "national pride ciphers":
|
| 420 |
|
| 421 | - (SM4-XTS, SM4-CBC-CTS)
|
| 422 |
|
| 423 | Generally speaking, these ciphers aren't "bad" per se, but they
|
| 424 | receive limited security review compared to the usual choices such as
|
| 425 | AES and ChaCha. They also don't bring much new to the table. It is
|
| 426 | suggested to only use these ciphers where their use is mandated.
|
| 427 |
|
| 428 | Kernel config options
|
| 429 | ---------------------
|
| 430 |
|
| 431 | Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in
|
| 432 | only the basic support from the crypto API needed to use AES-256-XTS
|
| 433 | and AES-256-CBC-CTS encryption. For optimal performance, it is
|
| 434 | strongly recommended to also enable any available platform-specific
|
| 435 | kconfig options that provide acceleration for the algorithm(s) you
|
| 436 | wish to use. Support for any "non-default" encryption modes typically
|
| 437 | requires extra kconfig options as well.
|
| 438 |
|
| 439 | Below, some relevant options are listed by encryption mode. Note,
|
| 440 | acceleration options not listed below may be available for your
|
| 441 | platform; refer to the kconfig menus. File contents encryption can
|
| 442 | also be configured to use inline encryption hardware instead of the
|
| 443 | kernel crypto API (see `Inline encryption support`_); in that case,
|
| 444 | the file contents mode doesn't need to supported in the kernel crypto
|
| 445 | API, but the filenames mode still does.
|
| 446 |
|
| 447 | - AES-256-XTS and AES-256-CBC-CTS
|
| 448 | - Recommended:
|
| 449 | - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
|
| 450 | - x86: CONFIG_CRYPTO_AES_NI_INTEL
|
| 451 |
|
| 452 | - AES-256-HCTR2
|
| 453 | - Mandatory:
|
| 454 | - CONFIG_CRYPTO_HCTR2
|
| 455 | - Recommended:
|
| 456 | - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
|
| 457 | - x86: CONFIG_CRYPTO_AES_NI_INTEL
|
| 458 |
|
| 459 | - Adiantum
|
| 460 | - Mandatory:
|
| 461 | - CONFIG_CRYPTO_ADIANTUM
|
| 462 |
|
| 463 | - AES-128-CBC-ESSIV and AES-128-CBC-CTS:
|
| 464 | - Mandatory:
|
| 465 | - CONFIG_CRYPTO_ESSIV
|
| 466 | - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
|
| 467 | - Recommended:
|
| 468 | - AES-CBC acceleration
|
| 469 |
|
| 470 | Contents encryption
|
| 471 | -------------------
|
| 472 |
|
| 473 | For contents encryption, each file's contents is divided into "data
|
| 474 | units". Each data unit is encrypted independently. The IV for each
|
| 475 | data unit incorporates the zero-based index of the data unit within
|
| 476 | the file. This ensures that each data unit within a file is encrypted
|
| 477 | differently, which is essential to prevent leaking information.
|
| 478 |
|
| 479 | Note: the encryption depending on the offset into the file means that
|
| 480 | operations like "collapse range" and "insert range" that rearrange the
|
| 481 | extent mapping of files are not supported on encrypted files.
|
| 482 |
|
| 483 | There are two cases for the sizes of the data units:
|
| 484 |
|
| 485 | * Fixed-size data units. This is how all filesystems other than UBIFS
|
| 486 | work. A file's data units are all the same size; the last data unit
|
| 487 | is zero-padded if needed. By default, the data unit size is equal
|
| 488 | to the filesystem block size. On some filesystems, users can select
|
| 489 | a sub-block data unit size via the ``log2_data_unit_size`` field of
|
| 490 | the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_.
|
| 491 |
|
| 492 | * Variable-size data units. This is what UBIFS does. Each "UBIFS
|
| 493 | data node" is treated as a crypto data unit. Each contains variable
|
| 494 | length, possibly compressed data, zero-padded to the next 16-byte
|
| 495 | boundary. Users cannot select a sub-block data unit size on UBIFS.
|
| 496 |
|
| 497 | In the case of compression + encryption, the compressed data is
|
| 498 | encrypted. UBIFS compression works as described above. f2fs
|
| 499 | compression works a bit differently; it compresses a number of
|
| 500 | filesystem blocks into a smaller number of filesystem blocks.
|
| 501 | Therefore a f2fs-compressed file still uses fixed-size data units, and
|
| 502 | it is encrypted in a similar way to a file containing holes.
|
| 503 |
|
| 504 | As mentioned in `Key hierarchy`_, the default encryption setting uses
|
| 505 | per-file keys. In this case, the IV for each data unit is simply the
|
| 506 | index of the data unit in the file. However, users can select an
|
| 507 | encryption setting that does not use per-file keys. For these, some
|
| 508 | kind of file identifier is incorporated into the IVs as follows:
|
| 509 |
|
| 510 | - With `DIRECT_KEY policies`_, the data unit index is placed in bits
|
| 511 | 0-63 of the IV, and the file's nonce is placed in bits 64-191.
|
| 512 |
|
| 513 | - With `IV_INO_LBLK_64 policies`_, the data unit index is placed in
|
| 514 | bits 0-31 of the IV, and the file's inode number is placed in bits
|
| 515 | 32-63. This setting is only allowed when data unit indices and
|
| 516 | inode numbers fit in 32 bits.
|
| 517 |
|
| 518 | - With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed
|
| 519 | and added to the data unit index. The resulting value is truncated
|
| 520 | to 32 bits and placed in bits 0-31 of the IV. This setting is only
|
| 521 | allowed when data unit indices and inode numbers fit in 32 bits.
|
| 522 |
|
| 523 | The byte order of the IV is always little endian.
|
| 524 |
|
| 525 | If the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an
|
| 526 | ESSIV layer is automatically included. In this case, before the IV is
|
| 527 | passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
|
| 528 | key is the SHA-256 hash of the file's contents encryption key.
|
| 529 |
|
| 530 | Filenames encryption
|
| 531 | --------------------
|
| 532 |
|
| 533 | For filenames, each full filename is encrypted at once. Because of
|
| 534 | the requirements to retain support for efficient directory lookups and
|
| 535 | filenames of up to 255 bytes, the same IV is used for every filename
|
| 536 | in a directory.
|
| 537 |
|
| 538 | However, each encrypted directory still uses a unique key, or
|
| 539 | alternatively has the file's nonce (for `DIRECT_KEY policies`_) or
|
| 540 | inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs.
|
| 541 | Thus, IV reuse is limited to within a single directory.
|
| 542 |
|
| 543 | With CBC-CTS, the IV reuse means that when the plaintext filenames share a
|
| 544 | common prefix at least as long as the cipher block size (16 bytes for AES), the
|
| 545 | corresponding encrypted filenames will also share a common prefix. This is
|
| 546 | undesirable. Adiantum and HCTR2 do not have this weakness, as they are
|
| 547 | wide-block encryption modes.
|
| 548 |
|
| 549 | All supported filenames encryption modes accept any plaintext length
|
| 550 | >= 16 bytes; cipher block alignment is not required. However,
|
| 551 | filenames shorter than 16 bytes are NUL-padded to 16 bytes before
|
| 552 | being encrypted. In addition, to reduce leakage of filename lengths
|
| 553 | via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
|
| 554 | 16, or 32-byte boundary (configurable). 32 is recommended since this
|
| 555 | provides the best confidentiality, at the cost of making directory
|
| 556 | entries consume slightly more space. Note that since NUL (``\0``) is
|
| 557 | not otherwise a valid character in filenames, the padding will never
|
| 558 | produce duplicate plaintexts.
|
| 559 |
|
| 560 | Symbolic link targets are considered a type of filename and are
|
| 561 | encrypted in the same way as filenames in directory entries, except
|
| 562 | that IV reuse is not a problem as each symlink has its own inode.
|
| 563 |
|
| 564 | User API
|
| 565 | ========
|
| 566 |
|
| 567 | Setting an encryption policy
|
| 568 | ----------------------------
|
| 569 |
|
| 570 | FS_IOC_SET_ENCRYPTION_POLICY
|
| 571 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 572 |
|
| 573 | The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
|
| 574 | empty directory or verifies that a directory or regular file already
|
| 575 | has the specified encryption policy. It takes in a pointer to
|
| 576 | struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
|
| 577 | follows::
|
| 578 |
|
| 579 | #define FSCRYPT_POLICY_V1 0
|
| 580 | #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
|
| 581 | struct fscrypt_policy_v1 {
|
| 582 | __u8 version;
|
| 583 | __u8 contents_encryption_mode;
|
| 584 | __u8 filenames_encryption_mode;
|
| 585 | __u8 flags;
|
| 586 | __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
|
| 587 | };
|
| 588 | #define fscrypt_policy fscrypt_policy_v1
|
| 589 |
|
| 590 | #define FSCRYPT_POLICY_V2 2
|
| 591 | #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
|
| 592 | struct fscrypt_policy_v2 {
|
| 593 | __u8 version;
|
| 594 | __u8 contents_encryption_mode;
|
| 595 | __u8 filenames_encryption_mode;
|
| 596 | __u8 flags;
|
| 597 | __u8 log2_data_unit_size;
|
| 598 | __u8 __reserved[3];
|
| 599 | __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
|
| 600 | };
|
| 601 |
|
| 602 | This structure must be initialized as follows:
|
| 603 |
|
| 604 | - ``version`` must be FSCRYPT_POLICY_V1 (0) if
|
| 605 | struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if
|
| 606 | struct fscrypt_policy_v2 is used. (Note: we refer to the original
|
| 607 | policy version as "v1", though its version code is really 0.)
|
| 608 | For new encrypted directories, use v2 policies, which are supported
|
| 609 | since Linux v5.4. v1 policies are deprecated and have several
|
| 610 | usability and security problems.
|
| 611 |
|
| 612 | - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
|
| 613 | be set to constants from ``<linux/fscrypt.h>`` which identify the
|
| 614 | encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS
|
| 615 | (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
|
| 616 | (4) for ``filenames_encryption_mode``. For details, see `Encryption
|
| 617 | modes and usage`_.
|
| 618 |
|
| 619 | v1 encryption policies only support three combinations of modes:
|
| 620 | (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS),
|
| 621 | (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and
|
| 622 | (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM). v2 policies support
|
| 623 | all combinations documented in `Supported modes`_.
|
| 624 |
|
| 625 | - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
|
| 626 |
|
| 627 | - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
|
| 628 | encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32
|
| 629 | (0x3).
|
| 630 | - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
|
| 631 | - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
|
| 632 | policies`_.
|
| 633 | - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
|
| 634 | policies`_.
|
| 635 |
|
| 636 | v1 encryption policies only support the PAD_* and DIRECT_KEY flags.
|
| 637 | The other flags are only supported by v2 encryption policies.
|
| 638 |
|
| 639 | The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are
|
| 640 | mutually exclusive.
|
| 641 |
|
| 642 | - ``log2_data_unit_size`` is the log2 of the data unit size in bytes,
|
| 643 | or 0 to select the default data unit size. The data unit size is
|
| 644 | the granularity of file contents encryption. For example, setting
|
| 645 | ``log2_data_unit_size`` to 12 causes file contents be passed to the
|
| 646 | underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
|
| 647 | data units, each with its own IV.
|
| 648 |
|
| 649 | Not all filesystems support setting ``log2_data_unit_size``. ext4
|
| 650 | and f2fs support it since Linux v6.7. On filesystems that support
|
| 651 | it, the supported nonzero values are 9 through the log2 of the
|
| 652 | filesystem block size, inclusively. The default value of 0 selects
|
| 653 | the filesystem block size.
|
| 654 |
|
| 655 | The main use case for ``log2_data_unit_size`` is for selecting a
|
| 656 | data unit size smaller than the filesystem block size for
|
| 657 | compatibility with inline encryption hardware that only supports
|
| 658 | smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be
|
| 659 | useful for checking which data unit sizes are supported by a
|
| 660 | particular system's inline encryption hardware.
|
| 661 |
|
| 662 | Leave this field zeroed unless you are certain you need it. Using
|
| 663 | an unnecessarily small data unit size reduces performance.
|
| 664 |
|
| 665 | - For v2 encryption policies, ``__reserved`` must be zeroed.
|
| 666 |
|
| 667 | - For v1 encryption policies, ``master_key_descriptor`` specifies how
|
| 668 | to find the master key in a keyring; see `Adding keys`_. It is up
|
| 669 | to userspace to choose a unique ``master_key_descriptor`` for each
|
| 670 | master key. The e4crypt and fscrypt tools use the first 8 bytes of
|
| 671 | ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
|
| 672 | required. Also, the master key need not be in the keyring yet when
|
| 673 | FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added
|
| 674 | before any files can be created in the encrypted directory.
|
| 675 |
|
| 676 | For v2 encryption policies, ``master_key_descriptor`` has been
|
| 677 | replaced with ``master_key_identifier``, which is longer and cannot
|
| 678 | be arbitrarily chosen. Instead, the key must first be added using
|
| 679 | `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
|
| 680 | the kernel returned in the struct fscrypt_add_key_arg must
|
| 681 | be used as the ``master_key_identifier`` in
|
| 682 | struct fscrypt_policy_v2.
|
| 683 |
|
| 684 | If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
|
| 685 | verifies that the file is an empty directory. If so, the specified
|
| 686 | encryption policy is assigned to the directory, turning it into an
|
| 687 | encrypted directory. After that, and after providing the
|
| 688 | corresponding master key as described in `Adding keys`_, all regular
|
| 689 | files, directories (recursively), and symlinks created in the
|
| 690 | directory will be encrypted, inheriting the same encryption policy.
|
| 691 | The filenames in the directory's entries will be encrypted as well.
|
| 692 |
|
| 693 | Alternatively, if the file is already encrypted, then
|
| 694 | FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
|
| 695 | policy exactly matches the actual one. If they match, then the ioctl
|
| 696 | returns 0. Otherwise, it fails with EEXIST. This works on both
|
| 697 | regular files and directories, including nonempty directories.
|
| 698 |
|
| 699 | When a v2 encryption policy is assigned to a directory, it is also
|
| 700 | required that either the specified key has been added by the current
|
| 701 | user or that the caller has CAP_FOWNER in the initial user namespace.
|
| 702 | (This is needed to prevent a user from encrypting their data with
|
| 703 | another user's key.) The key must remain added while
|
| 704 | FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new
|
| 705 | encrypted directory does not need to be accessed immediately, then the
|
| 706 | key can be removed right away afterwards.
|
| 707 |
|
| 708 | Note that the ext4 filesystem does not allow the root directory to be
|
| 709 | encrypted, even if it is empty. Users who want to encrypt an entire
|
| 710 | filesystem with one key should consider using dm-crypt instead.
|
| 711 |
|
| 712 | FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
|
| 713 |
|
| 714 | - ``EACCES``: the file is not owned by the process's uid, nor does the
|
| 715 | process have the CAP_FOWNER capability in a namespace with the file
|
| 716 | owner's uid mapped
|
| 717 | - ``EEXIST``: the file is already encrypted with an encryption policy
|
| 718 | different from the one specified
|
| 719 | - ``EINVAL``: an invalid encryption policy was specified (invalid
|
| 720 | version, mode(s), or flags; or reserved bits were set); or a v1
|
| 721 | encryption policy was specified but the directory has the casefold
|
| 722 | flag enabled (casefolding is incompatible with v1 policies).
|
| 723 | - ``ENOKEY``: a v2 encryption policy was specified, but the key with
|
| 724 | the specified ``master_key_identifier`` has not been added, nor does
|
| 725 | the process have the CAP_FOWNER capability in the initial user
|
| 726 | namespace
|
| 727 | - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
|
| 728 | directory
|
| 729 | - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
|
| 730 | - ``ENOTTY``: this type of filesystem does not implement encryption
|
| 731 | - ``EOPNOTSUPP``: the kernel was not configured with encryption
|
| 732 | support for filesystems, or the filesystem superblock has not
|
| 733 | had encryption enabled on it. (For example, to use encryption on an
|
| 734 | ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the
|
| 735 | kernel config, and the superblock must have had the "encrypt"
|
| 736 | feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
|
| 737 | encrypt``.)
|
| 738 | - ``EPERM``: this directory may not be encrypted, e.g. because it is
|
| 739 | the root directory of an ext4 filesystem
|
| 740 | - ``EROFS``: the filesystem is readonly
|
| 741 |
|
| 742 | Getting an encryption policy
|
| 743 | ----------------------------
|
| 744 |
|
| 745 | FS_IOC_GET_ENCRYPTION_POLICY_EX
|
| 746 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 747 |
|
| 748 | The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
|
| 749 | policy, if any, for a directory or regular file. No additional
|
| 750 | permissions are required beyond the ability to open the file. It
|
| 751 | takes in a pointer to struct fscrypt_get_policy_ex_arg,
|
| 752 | defined as follows::
|
| 753 |
|
| 754 | struct fscrypt_get_policy_ex_arg {
|
| 755 | __u64 policy_size; /* input/output */
|
| 756 | union {
|
| 757 | __u8 version;
|
| 758 | struct fscrypt_policy_v1 v1;
|
| 759 | struct fscrypt_policy_v2 v2;
|
| 760 | } policy; /* output */
|
| 761 | };
|
| 762 |
|
| 763 | The caller must initialize ``policy_size`` to the size available for
|
| 764 | the policy struct, i.e. ``sizeof(arg.policy)``.
|
| 765 |
|
| 766 | On success, the policy struct is returned in ``policy``, and its
|
| 767 | actual size is returned in ``policy_size``. ``policy.version`` should
|
| 768 | be checked to determine the version of policy returned. Note that the
|
| 769 | version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
|
| 770 |
|
| 771 | FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:
|
| 772 |
|
| 773 | - ``EINVAL``: the file is encrypted, but it uses an unrecognized
|
| 774 | encryption policy version
|
| 775 | - ``ENODATA``: the file is not encrypted
|
| 776 | - ``ENOTTY``: this type of filesystem does not implement encryption,
|
| 777 | or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
|
| 778 | - ``EOPNOTSUPP``: the kernel was not configured with encryption
|
| 779 | support for this filesystem, or the filesystem superblock has not
|
| 780 | had encryption enabled on it
|
| 781 | - ``EOVERFLOW``: the file is encrypted and uses a recognized
|
| 782 | encryption policy version, but the policy struct does not fit into
|
| 783 | the provided buffer
|
| 784 |
|
| 785 | Note: if you only need to know whether a file is encrypted or not, on
|
| 786 | most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
|
| 787 | and check for FS_ENCRYPT_FL, or to use the statx() system call and
|
| 788 | check for STATX_ATTR_ENCRYPTED in stx_attributes.
|
| 789 |
|
| 790 | FS_IOC_GET_ENCRYPTION_POLICY
|
| 791 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 792 |
|
| 793 | The FS_IOC_GET_ENCRYPTION_POLICY ioctl is deprecated. It supports
|
| 794 | only v1 encryption policies, which themselves are deprecated. Use
|
| 795 | `FS_IOC_GET_ENCRYPTION_POLICY_EX`_ instead.
|
| 796 |
|
| 797 | FS_IOC_GET_ENCRYPTION_POLICY retrieves the encryption policy for a
|
| 798 | directory or regular file, but only if it uses a v1 policy. It takes
|
| 799 | in a pointer directly to struct fscrypt_policy_v1.
|
| 800 |
|
| 801 | The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
|
| 802 | for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
|
| 803 | FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
|
| 804 | encrypted using a newer encryption policy version.
|
| 805 |
|
| 806 | Getting the per-filesystem salt
|
| 807 | -------------------------------
|
| 808 |
|
| 809 | Some filesystems, such as ext4 and F2FS, also support the deprecated
|
| 810 | ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly
|
| 811 | generated 16-byte value stored in the filesystem superblock. This
|
| 812 | value is intended to used as a salt when deriving an encryption key
|
| 813 | from a passphrase or other low-entropy user credential.
|
| 814 |
|
| 815 | FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to
|
| 816 | generate and manage any needed salt(s) in userspace.
|
| 817 |
|
| 818 | Getting a file's encryption nonce
|
| 819 | ---------------------------------
|
| 820 |
|
| 821 | Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported.
|
| 822 | On encrypted files and directories it gets the inode's 16-byte nonce.
|
| 823 | On unencrypted files and directories, it fails with ENODATA.
|
| 824 |
|
| 825 | This ioctl can be useful for automated tests which verify that the
|
| 826 | encryption is being done correctly. It is not needed for normal use
|
| 827 | of fscrypt.
|
| 828 |
|
| 829 | Adding keys
|
| 830 | -----------
|
| 831 |
|
| 832 | FS_IOC_ADD_ENCRYPTION_KEY
|
| 833 | ~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 834 |
|
| 835 | The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
|
| 836 | the filesystem, making all files on the filesystem which were
|
| 837 | encrypted using that key appear "unlocked", i.e. in plaintext form.
|
| 838 | It can be executed on any file or directory on the target filesystem,
|
| 839 | but using the filesystem's root directory is recommended. It takes in
|
| 840 | a pointer to struct fscrypt_add_key_arg, defined as follows::
|
| 841 |
|
| 842 | struct fscrypt_add_key_arg {
|
| 843 | struct fscrypt_key_specifier key_spec;
|
| 844 | __u32 raw_size;
|
| 845 | __u32 key_id;
|
| 846 | #define FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED 0x00000001
|
| 847 | __u32 flags;
|
| 848 | __u32 __reserved[7];
|
| 849 | __u8 raw[];
|
| 850 | };
|
| 851 |
|
| 852 | #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1
|
| 853 | #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2
|
| 854 |
|
| 855 | struct fscrypt_key_specifier {
|
| 856 | __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */
|
| 857 | __u32 __reserved;
|
| 858 | union {
|
| 859 | __u8 __reserved[32]; /* reserve some extra space */
|
| 860 | __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
|
| 861 | __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
|
| 862 | } u;
|
| 863 | };
|
| 864 |
|
| 865 | struct fscrypt_provisioning_key_payload {
|
| 866 | __u32 type;
|
| 867 | __u32 flags;
|
| 868 | __u8 raw[];
|
| 869 | };
|
| 870 |
|
| 871 | struct fscrypt_add_key_arg must be zeroed, then initialized
|
| 872 | as follows:
|
| 873 |
|
| 874 | - If the key is being added for use by v1 encryption policies, then
|
| 875 | ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
|
| 876 | ``key_spec.u.descriptor`` must contain the descriptor of the key
|
| 877 | being added, corresponding to the value in the
|
| 878 | ``master_key_descriptor`` field of struct fscrypt_policy_v1.
|
| 879 | To add this type of key, the calling process must have the
|
| 880 | CAP_SYS_ADMIN capability in the initial user namespace.
|
| 881 |
|
| 882 | (Note that v1 encryption policies are deprecated. The ability to
|
| 883 | add a key for v1 encryption policies remains only for compatibility
|
| 884 | with existing encrypted directories.)
|
| 885 |
|
| 886 | Alternatively, if the key is being added for use by v2 encryption
|
| 887 | policies, then ``key_spec.type`` must contain
|
| 888 | FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is
|
| 889 | an *output* field which the kernel fills in with a cryptographic
|
| 890 | hash of the key. To add this type of key, the calling process does
|
| 891 | not need any privileges. However, the number of keys that can be
|
| 892 | added is limited by the user's quota for the keyrings service (see
|
| 893 | ``Documentation/security/keys/core.rst``).
|
| 894 |
|
| 895 | - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
|
| 896 | Alternatively, if ``key_id`` is nonzero, this field must be 0, since
|
| 897 | in that case the size is implied by the specified Linux keyring key.
|
| 898 |
|
| 899 | - ``key_id`` is 0 if the key is given directly in the ``raw`` field.
|
| 900 | Otherwise ``key_id`` is the ID of a Linux keyring key of type
|
| 901 | "fscrypt-provisioning" whose payload is struct
|
| 902 | fscrypt_provisioning_key_payload whose ``raw`` field contains the
|
| 903 | key, whose ``type`` field matches ``key_spec.type``, and whose
|
| 904 | ``flags`` field matches ``flags``. Since ``raw`` is
|
| 905 | variable-length, the total size of this key's payload must be
|
| 906 | ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the number
|
| 907 | of key bytes. The process must have Search permission on this key.
|
| 908 |
|
| 909 | Most users should leave this 0 and specify the key directly. The
|
| 910 | support for specifying a Linux keyring key is intended mainly to
|
| 911 | allow re-adding keys after a filesystem is unmounted and re-mounted,
|
| 912 | without having to store the keys in userspace memory.
|
| 913 |
|
| 914 | - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
|
| 915 |
|
| 916 | - FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED: This denotes that the key is a
|
| 917 | hardware-wrapped key. See `Hardware-wrapped keys`_. This flag
|
| 918 | can't be used if FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR is used.
|
| 919 |
|
| 920 | - ``raw`` is a variable-length field which must contain the actual
|
| 921 | key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is
|
| 922 | nonzero, then this field is unused. Note that despite being named
|
| 923 | ``raw``, if FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED is specified then it
|
| 924 | will contain a wrapped key, not a raw key.
|
| 925 |
|
| 926 | For v2 policy keys, the kernel keeps track of which user (identified
|
| 927 | by effective user ID) added the key, and only allows the key to be
|
| 928 | removed by that user --- or by "root", if they use
|
| 929 | `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
|
| 930 |
|
| 931 | However, if another user has added the key, it may be desirable to
|
| 932 | prevent that other user from unexpectedly removing it. Therefore,
|
| 933 | FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
|
| 934 | *again*, even if it's already added by other user(s). In this case,
|
| 935 | FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
|
| 936 | current user, rather than actually add the key again (but the key must
|
| 937 | still be provided, as a proof of knowledge).
|
| 938 |
|
| 939 | FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
|
| 940 | the key was either added or already exists.
|
| 941 |
|
| 942 | FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:
|
| 943 |
|
| 944 | - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
|
| 945 | caller does not have the CAP_SYS_ADMIN capability in the initial
|
| 946 | user namespace; or the key was specified by Linux key ID but the
|
| 947 | process lacks Search permission on the key.
|
| 948 | - ``EBADMSG``: invalid hardware-wrapped key
|
| 949 | - ``EDQUOT``: the key quota for this user would be exceeded by adding
|
| 950 | the key
|
| 951 | - ``EINVAL``: invalid key size or key specifier type, or reserved bits
|
| 952 | were set
|
| 953 | - ``EKEYREJECTED``: the key was specified by Linux key ID, but the key
|
| 954 | has the wrong type
|
| 955 | - ``ENOKEY``: the key was specified by Linux key ID, but no key exists
|
| 956 | with that ID
|
| 957 | - ``ENOTTY``: this type of filesystem does not implement encryption
|
| 958 | - ``EOPNOTSUPP``: the kernel was not configured with encryption
|
| 959 | support for this filesystem, or the filesystem superblock has not
|
| 960 | had encryption enabled on it; or a hardware wrapped key was specified
|
| 961 | but the filesystem does not support inline encryption or the hardware
|
| 962 | does not support hardware-wrapped keys
|
| 963 |
|
| 964 | Legacy method
|
| 965 | ~~~~~~~~~~~~~
|
| 966 |
|
| 967 | For v1 encryption policies, a master encryption key can also be
|
| 968 | provided by adding it to a process-subscribed keyring, e.g. to a
|
| 969 | session keyring, or to a user keyring if the user keyring is linked
|
| 970 | into the session keyring.
|
| 971 |
|
| 972 | This method is deprecated (and not supported for v2 encryption
|
| 973 | policies) for several reasons. First, it cannot be used in
|
| 974 | combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
|
| 975 | so for removing a key a workaround such as keyctl_unlink() in
|
| 976 | combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would
|
| 977 | have to be used. Second, it doesn't match the fact that the
|
| 978 | locked/unlocked status of encrypted files (i.e. whether they appear to
|
| 979 | be in plaintext form or in ciphertext form) is global. This mismatch
|
| 980 | has caused much confusion as well as real problems when processes
|
| 981 | running under different UIDs, such as a ``sudo`` command, need to
|
| 982 | access encrypted files.
|
| 983 |
|
| 984 | Nevertheless, to add a key to one of the process-subscribed keyrings,
|
| 985 | the add_key() system call can be used (see:
|
| 986 | ``Documentation/security/keys/core.rst``). The key type must be
|
| 987 | "logon"; keys of this type are kept in kernel memory and cannot be
|
| 988 | read back by userspace. The key description must be "fscrypt:"
|
| 989 | followed by the 16-character lower case hex representation of the
|
| 990 | ``master_key_descriptor`` that was set in the encryption policy. The
|
| 991 | key payload must conform to the following structure::
|
| 992 |
|
| 993 | #define FSCRYPT_MAX_KEY_SIZE 64
|
| 994 |
|
| 995 | struct fscrypt_key {
|
| 996 | __u32 mode;
|
| 997 | __u8 raw[FSCRYPT_MAX_KEY_SIZE];
|
| 998 | __u32 size;
|
| 999 | };
|
| 1000 |
|
| 1001 | ``mode`` is ignored; just set it to 0. The actual key is provided in
|
| 1002 | ``raw`` with ``size`` indicating its size in bytes. That is, the
|
| 1003 | bytes ``raw[0..size-1]`` (inclusive) are the actual key.
|
| 1004 |
|
| 1005 | The key description prefix "fscrypt:" may alternatively be replaced
|
| 1006 | with a filesystem-specific prefix such as "ext4:". However, the
|
| 1007 | filesystem-specific prefixes are deprecated and should not be used in
|
| 1008 | new programs.
|
| 1009 |
|
| 1010 | Removing keys
|
| 1011 | -------------
|
| 1012 |
|
| 1013 | Two ioctls are available for removing a key that was added by
|
| 1014 | `FS_IOC_ADD_ENCRYPTION_KEY`_:
|
| 1015 |
|
| 1016 | - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
|
| 1017 | - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
|
| 1018 |
|
| 1019 | These two ioctls differ only in cases where v2 policy keys are added
|
| 1020 | or removed by non-root users.
|
| 1021 |
|
| 1022 | These ioctls don't work on keys that were added via the legacy
|
| 1023 | process-subscribed keyrings mechanism.
|
| 1024 |
|
| 1025 | Before using these ioctls, read the `Online attacks`_ section for a
|
| 1026 | discussion of the security goals and limitations of these ioctls.
|
| 1027 |
|
| 1028 | FS_IOC_REMOVE_ENCRYPTION_KEY
|
| 1029 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 1030 |
|
| 1031 | The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
|
| 1032 | encryption key from the filesystem, and possibly removes the key
|
| 1033 | itself. It can be executed on any file or directory on the target
|
| 1034 | filesystem, but using the filesystem's root directory is recommended.
|
| 1035 | It takes in a pointer to struct fscrypt_remove_key_arg, defined
|
| 1036 | as follows::
|
| 1037 |
|
| 1038 | struct fscrypt_remove_key_arg {
|
| 1039 | struct fscrypt_key_specifier key_spec;
|
| 1040 | #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001
|
| 1041 | #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002
|
| 1042 | __u32 removal_status_flags; /* output */
|
| 1043 | __u32 __reserved[5];
|
| 1044 | };
|
| 1045 |
|
| 1046 | This structure must be zeroed, then initialized as follows:
|
| 1047 |
|
| 1048 | - The key to remove is specified by ``key_spec``:
|
| 1049 |
|
| 1050 | - To remove a key used by v1 encryption policies, set
|
| 1051 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
|
| 1052 | in ``key_spec.u.descriptor``. To remove this type of key, the
|
| 1053 | calling process must have the CAP_SYS_ADMIN capability in the
|
| 1054 | initial user namespace.
|
| 1055 |
|
| 1056 | - To remove a key used by v2 encryption policies, set
|
| 1057 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
|
| 1058 | in ``key_spec.u.identifier``.
|
| 1059 |
|
| 1060 | For v2 policy keys, this ioctl is usable by non-root users. However,
|
| 1061 | to make this possible, it actually just removes the current user's
|
| 1062 | claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
|
| 1063 | Only after all claims are removed is the key really removed.
|
| 1064 |
|
| 1065 | For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000,
|
| 1066 | then the key will be "claimed" by uid 1000, and
|
| 1067 | FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if
|
| 1068 | both uids 1000 and 2000 added the key, then for each uid
|
| 1069 | FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only
|
| 1070 | once *both* are removed is the key really removed. (Think of it like
|
| 1071 | unlinking a file that may have hard links.)
|
| 1072 |
|
| 1073 | If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
|
| 1074 | try to "lock" all files that had been unlocked with the key. It won't
|
| 1075 | lock files that are still in-use, so this ioctl is expected to be used
|
| 1076 | in cooperation with userspace ensuring that none of the files are
|
| 1077 | still open. However, if necessary, this ioctl can be executed again
|
| 1078 | later to retry locking any remaining files.
|
| 1079 |
|
| 1080 | FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed
|
| 1081 | (but may still have files remaining to be locked), the user's claim to
|
| 1082 | the key was removed, or the key was already removed but had files
|
| 1083 | remaining to be the locked so the ioctl retried locking them. In any
|
| 1084 | of these cases, ``removal_status_flags`` is filled in with the
|
| 1085 | following informational status flags:
|
| 1086 |
|
| 1087 | - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
|
| 1088 | are still in-use. Not guaranteed to be set in the case where only
|
| 1089 | the user's claim to the key was removed.
|
| 1090 | - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
|
| 1091 | user's claim to the key was removed, not the key itself
|
| 1092 |
|
| 1093 | FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:
|
| 1094 |
|
| 1095 | - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
|
| 1096 | was specified, but the caller does not have the CAP_SYS_ADMIN
|
| 1097 | capability in the initial user namespace
|
| 1098 | - ``EINVAL``: invalid key specifier type, or reserved bits were set
|
| 1099 | - ``ENOKEY``: the key object was not found at all, i.e. it was never
|
| 1100 | added in the first place or was already fully removed including all
|
| 1101 | files locked; or, the user does not have a claim to the key (but
|
| 1102 | someone else does).
|
| 1103 | - ``ENOTTY``: this type of filesystem does not implement encryption
|
| 1104 | - ``EOPNOTSUPP``: the kernel was not configured with encryption
|
| 1105 | support for this filesystem, or the filesystem superblock has not
|
| 1106 | had encryption enabled on it
|
| 1107 |
|
| 1108 | FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
|
| 1109 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 1110 |
|
| 1111 | FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
|
| 1112 | `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
|
| 1113 | ALL_USERS version of the ioctl will remove all users' claims to the
|
| 1114 | key, not just the current user's. I.e., the key itself will always be
|
| 1115 | removed, no matter how many users have added it. This difference is
|
| 1116 | only meaningful if non-root users are adding and removing keys.
|
| 1117 |
|
| 1118 | Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires
|
| 1119 | "root", namely the CAP_SYS_ADMIN capability in the initial user
|
| 1120 | namespace. Otherwise it will fail with EACCES.
|
| 1121 |
|
| 1122 | Getting key status
|
| 1123 | ------------------
|
| 1124 |
|
| 1125 | FS_IOC_GET_ENCRYPTION_KEY_STATUS
|
| 1126 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 1127 |
|
| 1128 | The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
|
| 1129 | master encryption key. It can be executed on any file or directory on
|
| 1130 | the target filesystem, but using the filesystem's root directory is
|
| 1131 | recommended. It takes in a pointer to
|
| 1132 | struct fscrypt_get_key_status_arg, defined as follows::
|
| 1133 |
|
| 1134 | struct fscrypt_get_key_status_arg {
|
| 1135 | /* input */
|
| 1136 | struct fscrypt_key_specifier key_spec;
|
| 1137 | __u32 __reserved[6];
|
| 1138 |
|
| 1139 | /* output */
|
| 1140 | #define FSCRYPT_KEY_STATUS_ABSENT 1
|
| 1141 | #define FSCRYPT_KEY_STATUS_PRESENT 2
|
| 1142 | #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3
|
| 1143 | __u32 status;
|
| 1144 | #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001
|
| 1145 | __u32 status_flags;
|
| 1146 | __u32 user_count;
|
| 1147 | __u32 __out_reserved[13];
|
| 1148 | };
|
| 1149 |
|
| 1150 | The caller must zero all input fields, then fill in ``key_spec``:
|
| 1151 |
|
| 1152 | - To get the status of a key for v1 encryption policies, set
|
| 1153 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
|
| 1154 | in ``key_spec.u.descriptor``.
|
| 1155 |
|
| 1156 | - To get the status of a key for v2 encryption policies, set
|
| 1157 | ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
|
| 1158 | in ``key_spec.u.identifier``.
|
| 1159 |
|
| 1160 | On success, 0 is returned and the kernel fills in the output fields:
|
| 1161 |
|
| 1162 | - ``status`` indicates whether the key is absent, present, or
|
| 1163 | incompletely removed. Incompletely removed means that removal has
|
| 1164 | been initiated, but some files are still in use; i.e.,
|
| 1165 | `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational
|
| 1166 | status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.
|
| 1167 |
|
| 1168 | - ``status_flags`` can contain the following flags:
|
| 1169 |
|
| 1170 | - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
|
| 1171 | has added by the current user. This is only set for keys
|
| 1172 | identified by ``identifier`` rather than by ``descriptor``.
|
| 1173 |
|
| 1174 | - ``user_count`` specifies the number of users who have added the key.
|
| 1175 | This is only set for keys identified by ``identifier`` rather than
|
| 1176 | by ``descriptor``.
|
| 1177 |
|
| 1178 | FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:
|
| 1179 |
|
| 1180 | - ``EINVAL``: invalid key specifier type, or reserved bits were set
|
| 1181 | - ``ENOTTY``: this type of filesystem does not implement encryption
|
| 1182 | - ``EOPNOTSUPP``: the kernel was not configured with encryption
|
| 1183 | support for this filesystem, or the filesystem superblock has not
|
| 1184 | had encryption enabled on it
|
| 1185 |
|
| 1186 | Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful
|
| 1187 | for determining whether the key for a given encrypted directory needs
|
| 1188 | to be added before prompting the user for the passphrase needed to
|
| 1189 | derive the key.
|
| 1190 |
|
| 1191 | FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
|
| 1192 | the filesystem-level keyring, i.e. the keyring managed by
|
| 1193 | `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It
|
| 1194 | cannot get the status of a key that has only been added for use by v1
|
| 1195 | encryption policies using the legacy mechanism involving
|
| 1196 | process-subscribed keyrings.
|
| 1197 |
|
| 1198 | Access semantics
|
| 1199 | ================
|
| 1200 |
|
| 1201 | With the key
|
| 1202 | ------------
|
| 1203 |
|
| 1204 | With the encryption key, encrypted regular files, directories, and
|
| 1205 | symlinks behave very similarly to their unencrypted counterparts ---
|
| 1206 | after all, the encryption is intended to be transparent. However,
|
| 1207 | astute users may notice some differences in behavior:
|
| 1208 |
|
| 1209 | - Unencrypted files, or files encrypted with a different encryption
|
| 1210 | policy (i.e. different key, modes, or flags), cannot be renamed or
|
| 1211 | linked into an encrypted directory; see `Encryption policy
|
| 1212 | enforcement`_. Attempts to do so will fail with EXDEV. However,
|
| 1213 | encrypted files can be renamed within an encrypted directory, or
|
| 1214 | into an unencrypted directory.
|
| 1215 |
|
| 1216 | Note: "moving" an unencrypted file into an encrypted directory, e.g.
|
| 1217 | with the `mv` program, is implemented in userspace by a copy
|
| 1218 | followed by a delete. Be aware that the original unencrypted data
|
| 1219 | may remain recoverable from free space on the disk; prefer to keep
|
| 1220 | all files encrypted from the very beginning. The `shred` program
|
| 1221 | may be used to overwrite the source files but isn't guaranteed to be
|
| 1222 | effective on all filesystems and storage devices.
|
| 1223 |
|
| 1224 | - Direct I/O is supported on encrypted files only under some
|
| 1225 | circumstances. For details, see `Direct I/O support`_.
|
| 1226 |
|
| 1227 | - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
|
| 1228 | FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will
|
| 1229 | fail with EOPNOTSUPP.
|
| 1230 |
|
| 1231 | - Online defragmentation of encrypted files is not supported. The
|
| 1232 | EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
|
| 1233 | EOPNOTSUPP.
|
| 1234 |
|
| 1235 | - The ext4 filesystem does not support data journaling with encrypted
|
| 1236 | regular files. It will fall back to ordered data mode instead.
|
| 1237 |
|
| 1238 | - DAX (Direct Access) is not supported on encrypted files.
|
| 1239 |
|
| 1240 | - Encrypted files cannot be used directly as swap files. To swap to
|
| 1241 | an encrypted file, set up a loopback device on top of it.
|
| 1242 | Alternatively, encrypted swap can use a dm-crypt device.
|
| 1243 |
|
| 1244 | - The maximum length of an encrypted symlink is 2 bytes shorter than
|
| 1245 | the maximum length of an unencrypted symlink. For example, on an
|
| 1246 | EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
|
| 1247 | to 4095 bytes long, while encrypted symlinks can only be up to 4093
|
| 1248 | bytes long (both lengths excluding the terminating null).
|
| 1249 |
|
| 1250 | Note that mmap *is* supported. This is possible because the pagecache
|
| 1251 | for an encrypted file contains the plaintext, not the ciphertext.
|
| 1252 |
|
| 1253 | Without the key
|
| 1254 | ---------------
|
| 1255 |
|
| 1256 | Some filesystem operations may be performed on encrypted regular
|
| 1257 | files, directories, and symlinks even before their encryption key has
|
| 1258 | been added, or after their encryption key has been removed:
|
| 1259 |
|
| 1260 | - File metadata may be read, e.g. using stat().
|
| 1261 |
|
| 1262 | - Directories may be listed, in which case the filenames will be
|
| 1263 | listed in an encoded form derived from their ciphertext. The
|
| 1264 | current encoding algorithm is described in `Filename hashing and
|
| 1265 | encoding`_. The algorithm is subject to change, but it is
|
| 1266 | guaranteed that the presented filenames will be no longer than
|
| 1267 | NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
|
| 1268 | will uniquely identify directory entries.
|
| 1269 |
|
| 1270 | The ``.`` and ``..`` directory entries are special. They are always
|
| 1271 | present and are not encrypted or encoded.
|
| 1272 |
|
| 1273 | - Files may be deleted. That is, nondirectory files may be deleted
|
| 1274 | with unlink() as usual, and empty directories may be deleted with
|
| 1275 | rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
|
| 1276 | expected.
|
| 1277 |
|
| 1278 | - Symlink targets may be read and followed, but they will be presented
|
| 1279 | in encrypted form, similar to filenames in directories. Hence, they
|
| 1280 | are unlikely to point to anywhere useful.
|
| 1281 |
|
| 1282 | Without the key, regular files cannot be opened or truncated.
|
| 1283 | Attempts to do so will fail with ENOKEY. This implies that any
|
| 1284 | regular file operations that require a file descriptor, such as
|
| 1285 | read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
|
| 1286 |
|
| 1287 | Also without the key, files of any type (including directories) cannot
|
| 1288 | be created or linked into an encrypted directory, nor can a name in an
|
| 1289 | encrypted directory be the source or target of a rename, nor can an
|
| 1290 | O_TMPFILE temporary file be created in an encrypted directory. All
|
| 1291 | such operations will fail with ENOKEY.
|
| 1292 |
|
| 1293 | It is not currently possible to backup and restore encrypted files
|
| 1294 | without the encryption key. This would require special APIs which
|
| 1295 | have not yet been implemented.
|
| 1296 |
|
| 1297 | Encryption policy enforcement
|
| 1298 | =============================
|
| 1299 |
|
| 1300 | After an encryption policy has been set on a directory, all regular
|
| 1301 | files, directories, and symbolic links created in that directory
|
| 1302 | (recursively) will inherit that encryption policy. Special files ---
|
| 1303 | that is, named pipes, device nodes, and UNIX domain sockets --- will
|
| 1304 | not be encrypted.
|
| 1305 |
|
| 1306 | Except for those special files, it is forbidden to have unencrypted
|
| 1307 | files, or files encrypted with a different encryption policy, in an
|
| 1308 | encrypted directory tree. Attempts to link or rename such a file into
|
| 1309 | an encrypted directory will fail with EXDEV. This is also enforced
|
| 1310 | during ->lookup() to provide limited protection against offline
|
| 1311 | attacks that try to disable or downgrade encryption in known locations
|
| 1312 | where applications may later write sensitive data. It is recommended
|
| 1313 | that systems implementing a form of "verified boot" take advantage of
|
| 1314 | this by validating all top-level encryption policies prior to access.
|
| 1315 |
|
| 1316 | Inline encryption support
|
| 1317 | =========================
|
| 1318 |
|
| 1319 | Many newer systems (especially mobile SoCs) have *inline encryption
|
| 1320 | hardware* that can encrypt/decrypt data while it is on its way to/from
|
| 1321 | the storage device.
|
| 1322 |
|
| 1323 | On supported filesystems (currently ext4 and f2fs), fscrypt can use
|
| 1324 | inline encryption hardware instead of the CPU to encrypt/decrypt file
|
| 1325 | contents. To enable this, specify the "inlinecrypt" mount option when
|
| 1326 | mounting the filesystem.
|
| 1327 |
|
| 1328 | This causes the filesystem to use inline encryption hardware whenever
|
| 1329 | possible, falling back to the CPU only if such hardware is absent or
|
| 1330 | doesn't provide the needed crypto capabilities.
|
| 1331 |
|
| 1332 | For more information about the kernel's support for inline encryption
|
| 1333 | hardware, see :ref:`Documentation/block/inline-encryption.rst
|
| 1334 | <inline_encryption>`.
|
| 1335 |
|
| 1336 | Inline encryption doesn't affect the ciphertext or other aspects of
|
| 1337 | the on-disk format, so users may freely switch back and forth between
|
| 1338 | using "inlinecrypt" and not using "inlinecrypt". An exception is that
|
| 1339 | files that are protected by a hardware-wrapped key can only be
|
| 1340 | encrypted/decrypted by the inline encryption hardware and therefore
|
| 1341 | can only be accessed when the "inlinecrypt" mount option is used. For
|
| 1342 | more information about hardware-wrapped keys, see below.
|
| 1343 |
|
| 1344 | Hardware-wrapped keys
|
| 1345 | ---------------------
|
| 1346 |
|
| 1347 | fscrypt supports using *hardware-wrapped keys* when the inline
|
| 1348 | encryption hardware supports it. Such keys are only present in kernel
|
| 1349 | memory in wrapped (encrypted) form; they can only be unwrapped
|
| 1350 | (decrypted) by the inline encryption hardware and are temporally bound
|
| 1351 | to the current boot. This prevents the keys from being compromised if
|
| 1352 | kernel memory is leaked. This is done without limiting the number of
|
| 1353 | keys that can be used and while still allowing the execution of
|
| 1354 | cryptographic tasks that are tied to the same key but can't use inline
|
| 1355 | encryption hardware, e.g. filenames encryption.
|
| 1356 |
|
| 1357 | Note that hardware-wrapped keys aren't specific to fscrypt; they are a
|
| 1358 | block layer feature (part of *blk-crypto*). For more details about
|
| 1359 | hardware-wrapped keys, see the block layer documentation at
|
| 1360 | :ref:`Documentation/block/inline-encryption.rst
|
| 1361 | <hardware_wrapped_keys>`. The rest of this section just focuses on
|
| 1362 | the details of how fscrypt can use hardware-wrapped keys.
|
| 1363 |
|
| 1364 | fscrypt supports hardware-wrapped keys by allowing the fscrypt master
|
| 1365 | keys to be hardware-wrapped keys as an alternative to raw keys. To
|
| 1366 | add a hardware-wrapped key with `FS_IOC_ADD_ENCRYPTION_KEY`_,
|
| 1367 | userspace must specify FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED in the
|
| 1368 | ``flags`` field of struct fscrypt_add_key_arg and also in the
|
| 1369 | ``flags`` field of struct fscrypt_provisioning_key_payload when
|
| 1370 | applicable. The key must be in ephemerally-wrapped form, not
|
| 1371 | long-term wrapped form.
|
| 1372 |
|
| 1373 | Some limitations apply. First, files protected by a hardware-wrapped
|
| 1374 | key are tied to the system's inline encryption hardware. Therefore
|
| 1375 | they can only be accessed when the "inlinecrypt" mount option is used,
|
| 1376 | and they can't be included in portable filesystem images. Second,
|
| 1377 | currently the hardware-wrapped key support is only compatible with
|
| 1378 | `IV_INO_LBLK_64 policies`_ and `IV_INO_LBLK_32 policies`_, as it
|
| 1379 | assumes that there is just one file contents encryption key per
|
| 1380 | fscrypt master key rather than one per file. Future work may address
|
| 1381 | this limitation by passing per-file nonces down the storage stack to
|
| 1382 | allow the hardware to derive per-file keys.
|
| 1383 |
|
| 1384 | Implementation-wise, to encrypt/decrypt the contents of files that are
|
| 1385 | protected by a hardware-wrapped key, fscrypt uses blk-crypto,
|
| 1386 | attaching the hardware-wrapped key to the bio crypt contexts. As is
|
| 1387 | the case with raw keys, the block layer will program the key into a
|
| 1388 | keyslot when it isn't already in one. However, when programming a
|
| 1389 | hardware-wrapped key, the hardware doesn't program the given key
|
| 1390 | directly into a keyslot but rather unwraps it (using the hardware's
|
| 1391 | ephemeral wrapping key) and derives the inline encryption key from it.
|
| 1392 | The inline encryption key is the key that actually gets programmed
|
| 1393 | into a keyslot, and it is never exposed to software.
|
| 1394 |
|
| 1395 | However, fscrypt doesn't just do file contents encryption; it also
|
| 1396 | uses its master keys to derive filenames encryption keys, key
|
| 1397 | identifiers, and sometimes some more obscure types of subkeys such as
|
| 1398 | dirhash keys. So even with file contents encryption out of the
|
| 1399 | picture, fscrypt still needs a raw key to work with. To get such a
|
| 1400 | key from a hardware-wrapped key, fscrypt asks the inline encryption
|
| 1401 | hardware to derive a cryptographically isolated "software secret" from
|
| 1402 | the hardware-wrapped key. fscrypt uses this "software secret" to key
|
| 1403 | its KDF to derive all subkeys other than file contents keys.
|
| 1404 |
|
| 1405 | Note that this implies that the hardware-wrapped key feature only
|
| 1406 | protects the file contents encryption keys. It doesn't protect other
|
| 1407 | fscrypt subkeys such as filenames encryption keys.
|
| 1408 |
|
| 1409 | Direct I/O support
|
| 1410 | ==================
|
| 1411 |
|
| 1412 | For direct I/O on an encrypted file to work, the following conditions
|
| 1413 | must be met (in addition to the conditions for direct I/O on an
|
| 1414 | unencrypted file):
|
| 1415 |
|
| 1416 | * The filesystem must be block-based. (Before Linux v7.3, the
|
| 1417 | filesystem also needed to be mounted with ``-o inlinecrypt``.)
|
| 1418 |
|
| 1419 | * The I/O request must be fully aligned to the filesystem block size.
|
| 1420 | This means that the file position the I/O is targeting, the lengths
|
| 1421 | of all I/O segments, and the memory addresses of all I/O buffers
|
| 1422 | must be multiples of this value. Note that the filesystem block
|
| 1423 | size may be greater than the logical block size of the block device.
|
| 1424 |
|
| 1425 | If either of the above conditions is not met, then direct I/O on the
|
| 1426 | encrypted file will fall back to buffered I/O.
|
| 1427 |
|
| 1428 | Implementation details
|
| 1429 | ======================
|
| 1430 |
|
| 1431 | Encryption context
|
| 1432 | ------------------
|
| 1433 |
|
| 1434 | An encryption policy is represented on-disk by
|
| 1435 | struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to
|
| 1436 | individual filesystems to decide where to store it, but normally it
|
| 1437 | would be stored in a hidden extended attribute. It should *not* be
|
| 1438 | exposed by the xattr-related system calls such as getxattr() and
|
| 1439 | setxattr() because of the special semantics of the encryption xattr.
|
| 1440 | (In particular, there would be much confusion if an encryption policy
|
| 1441 | were to be added to or removed from anything other than an empty
|
| 1442 | directory.) These structs are defined as follows::
|
| 1443 |
|
| 1444 | #define FSCRYPT_FILE_NONCE_SIZE 16
|
| 1445 |
|
| 1446 | #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
|
| 1447 | struct fscrypt_context_v1 {
|
| 1448 | u8 version;
|
| 1449 | u8 contents_encryption_mode;
|
| 1450 | u8 filenames_encryption_mode;
|
| 1451 | u8 flags;
|
| 1452 | u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
|
| 1453 | u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
|
| 1454 | };
|
| 1455 |
|
| 1456 | #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
|
| 1457 | struct fscrypt_context_v2 {
|
| 1458 | u8 version;
|
| 1459 | u8 contents_encryption_mode;
|
| 1460 | u8 filenames_encryption_mode;
|
| 1461 | u8 flags;
|
| 1462 | u8 log2_data_unit_size;
|
| 1463 | u8 __reserved[3];
|
| 1464 | u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
|
| 1465 | u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
|
| 1466 | };
|
| 1467 |
|
| 1468 | The context structs contain the same information as the corresponding
|
| 1469 | policy structs (see `Setting an encryption policy`_), except that the
|
| 1470 | context structs also contain a nonce. The nonce is randomly generated
|
| 1471 | by the kernel and is used as KDF input or as a tweak to cause
|
| 1472 | different files to be encrypted differently; see `Per-file encryption
|
| 1473 | keys`_ and `DIRECT_KEY policies`_.
|
| 1474 |
|
| 1475 | Data path changes
|
| 1476 | -----------------
|
| 1477 |
|
| 1478 | The block-based filesystems that support fscrypt, such as ext4 and
|
| 1479 | f2fs, use blk-crypto (:ref:`inline_encryption`) to implement file
|
| 1480 | contents encryption and decryption. With blk-crypto, the filesystem
|
| 1481 | assigns an encryption context to each I/O request it issues to the
|
| 1482 | contents of an encrypted file. The encryption (for writes) or
|
| 1483 | decryption (for reads) is handled by the block layer transparently to
|
| 1484 | the filesystem, using either the CPU or inline encryption hardware.
|
| 1485 |
|
| 1486 | Non-block-based filesystems can't use blk-crypto, so they make the
|
| 1487 | calls to the cryptographic algorithms at the filesystem layer instead.
|
| 1488 |
|
| 1489 | Regardless of the layer in which they occur (blk-crypto-fallback or the
|
| 1490 | filesystem), for CPU-based encryption and decryption of file contents:
|
| 1491 |
|
| 1492 | - For reads, the ciphertext data is read from the storage backend
|
| 1493 | (block device, network, UBI device, etc.) into the destination
|
| 1494 | buffers, then decrypted in-place. The destination buffers are
|
| 1495 | pagecache folios for buffered reads, or application-provided buffers
|
| 1496 | for direct reads. In either case, the filesystem reports success
|
| 1497 | only after decryption has successfully completed.
|
| 1498 |
|
| 1499 | - For writes, the plaintext data is encrypted from the source buffers
|
| 1500 | (which cannot be modified) into bounce buffers. Then, the
|
| 1501 | ciphertext in the bounce buffers is written to the storage backend.
|
| 1502 |
|
| 1503 | The source buffers are usually pagecache folios for buffered writes,
|
| 1504 | or application-provided buffers for direct writes. There are also
|
| 1505 | some cases (all files on UBIFS, and compressed files on f2fs) where
|
| 1506 | the filesystem already uses bounce buffers for writes for other
|
| 1507 | reasons; in these cases the source plaintext data is already in
|
| 1508 | bounce buffers. UBIFS optimizes this case by encrypting the data
|
| 1509 | in-place in its existing bounce buffers.
|
| 1510 |
|
| 1511 | When inline encryption hardware is used instead of the CPU, reads from
|
| 1512 | the storage backend logically return plaintext data, and writes accept
|
| 1513 | plaintext data. In that case the flow is simplified: there's no
|
| 1514 | scheduling of decryption work, and no bounce buffers are used.
|
| 1515 |
|
| 1516 | Filename hashing and encoding
|
| 1517 | -----------------------------
|
| 1518 |
|
| 1519 | Modern filesystems accelerate directory lookups by using indexed
|
| 1520 | directories. An indexed directory is organized as a tree keyed by
|
| 1521 | filename hashes. When a ->lookup() is requested, the filesystem
|
| 1522 | normally hashes the filename being looked up so that it can quickly
|
| 1523 | find the corresponding directory entry, if any.
|
| 1524 |
|
| 1525 | With encryption, lookups must be supported and efficient both with and
|
| 1526 | without the encryption key. Clearly, it would not work to hash the
|
| 1527 | plaintext filenames, since the plaintext filenames are unavailable
|
| 1528 | without the key. (Hashing the plaintext filenames would also make it
|
| 1529 | impossible for the filesystem's fsck tool to optimize encrypted
|
| 1530 | directories.) Instead, filesystems hash the ciphertext filenames,
|
| 1531 | i.e. the bytes actually stored on-disk in the directory entries. When
|
| 1532 | asked to do a ->lookup() with the key, the filesystem just encrypts
|
| 1533 | the user-supplied name to get the ciphertext.
|
| 1534 |
|
| 1535 | Lookups without the key are more complicated. The raw ciphertext may
|
| 1536 | contain the ``\0`` and ``/`` characters, which are illegal in
|
| 1537 | filenames. Therefore, readdir() must base64url-encode the ciphertext
|
| 1538 | for presentation. For most filenames, this works fine; on ->lookup(),
|
| 1539 | the filesystem just base64url-decodes the user-supplied name to get
|
| 1540 | back to the raw ciphertext.
|
| 1541 |
|
| 1542 | However, for very long filenames, base64url encoding would cause the
|
| 1543 | filename length to exceed NAME_MAX. To prevent this, readdir()
|
| 1544 | actually presents long filenames in an abbreviated form which encodes
|
| 1545 | a strong "hash" of the ciphertext filename, along with the optional
|
| 1546 | filesystem-specific hash(es) needed for directory lookups. This
|
| 1547 | allows the filesystem to still, with a high degree of confidence, map
|
| 1548 | the filename given in ->lookup() back to a particular directory entry
|
| 1549 | that was previously listed by readdir(). See
|
| 1550 | struct fscrypt_nokey_name in the source for more details.
|
| 1551 |
|
| 1552 | Note that the precise way that filenames are presented to userspace
|
| 1553 | without the key is subject to change in the future. It is only meant
|
| 1554 | as a way to temporarily present valid filenames so that commands like
|
| 1555 | ``rm -r`` work as expected on encrypted directories.
|
| 1556 |
|
| 1557 | Tests
|
| 1558 | =====
|
| 1559 |
|
| 1560 | To test fscrypt, use xfstests, which is Linux's de facto standard
|
| 1561 | filesystem test suite. First, run all the tests in the "encrypt"
|
| 1562 | group on the relevant filesystem(s). For example, to test ext4 and
|
| 1563 | f2fs encryption using `kvm-xfstests
|
| 1564 | <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
|
| 1565 |
|
| 1566 | kvm-xfstests -c ext4,f2fs -g encrypt
|
| 1567 |
|
| 1568 | UBIFS encryption can also be tested this way, but it should be done in
|
| 1569 | a separate command, and it takes some time for kvm-xfstests to set up
|
| 1570 | emulated UBI volumes::
|
| 1571 |
|
| 1572 | kvm-xfstests -c ubifs -g encrypt
|
| 1573 |
|
| 1574 | No tests should fail. However, tests that use non-default encryption
|
| 1575 | modes (e.g. generic/549 and generic/550) will be skipped if the needed
|
| 1576 | algorithms were not built into the kernel's crypto API. Also, tests
|
| 1577 | that access the raw block device (e.g. generic/399, generic/548,
|
| 1578 | generic/549, generic/550) will be skipped on UBIFS.
|
| 1579 |
|
| 1580 | Besides running the "encrypt" group tests, for ext4 and f2fs it's also
|
| 1581 | possible to run most xfstests with the "test_dummy_encryption" mount
|
| 1582 | option. This option causes all new files to be automatically
|
| 1583 | encrypted with a dummy key, without having to make any API calls.
|
| 1584 | This tests the encrypted I/O paths more thoroughly. To do this with
|
| 1585 | kvm-xfstests, use the "encrypt" filesystem configuration::
|
| 1586 |
|
| 1587 | kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
|
| 1588 |
|
| 1589 | Because this runs many more tests than "-g encrypt" does, it takes
|
| 1590 | much longer to run; so also consider using `gce-xfstests
|
| 1591 | <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
|
| 1592 | instead of kvm-xfstests::
|
| 1593 |
|
| 1594 | gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
|
| 1595 |
|
| 1596 | To test inline encryption hardware on a platform that supports such
|
| 1597 | hardware, run xfstests directly with the ``inlinecrypt`` mount option
|
| 1598 | enabled. For example::
|
| 1599 |
|
| 1600 | EXT_MOUNT_OPTIONS="-o inlinecrypt" ./check -g encrypt
|