Documentation/filesystems/fscrypt.rst

27 with different keys and to have unencrypted files on the same
105 Unless `hardware-wrapped keys`_ are used, an attacker who gains the
108 compromise all fscrypt keys that are currently in-use.  This also
110 keys the system was using may remain in memory for a short time.
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
117 In addition, fscrypt allows encryption keys to be removed from the
124 thereby wiping their per-file keys and making them once again appear
129 - Per-file keys for in-use files will *not* be removed or wiped.
142   containing keys to prevent it from being swapped out.
150 - Secret keys might still exist in CPU registers or in other places
158 any in-use fscrypt keys.  Thus, usually fscrypt provides no meaningful
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
188 - Non-root users cannot securely remove encryption keys.
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`_.
201 Master Keys
205 keys can be up to 64 bytes long, and must be at least as long as the
210 policy and AES-256-XTS is used; such keys must be 64 bytes.
213 appropriate master key.  There can be any number of master keys, each
217 Master keys must be real cryptographic keys, i.e. indistinguishable
224 Instead, users should generate master keys either using a
236 (Key Derivation Function) to derive the actual keys.
246 encryption keys.  It works by encrypting the master key with
257 context bytes are used for other types of derived keys.
264 Per-file encryption keys
270 cases, fscrypt does this by deriving per-file keys.  When a new
277 Key derivation was chosen over key wrapping because wrapped keys would
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
298 per-file encryption keys are not used.  Instead, whenever any data
314 the encryption keys are derived from the master key, encryption mode
342 For master keys used for v2 encryption policies, a unique 16-byte "key
346 Dirhash keys
501 per-file keys.  In this case, the IV for each data unit is simply the
503 encryption setting that does not use per-file keys.  For these, some
662   to find the master key in a keyring; see `Adding keys`_.  It is up
682 corresponding master key as described in `Adding keys`_, all regular
834 Adding keys
892   not need any privileges.  However, the number of keys that can be
894   ``Documentation/security/keys/core.rst``).
912   allow re-adding keys after a filesystem is unmounted and re-mounted,
913   without having to store the keys in userspace memory.
918     hardware-wrapped key.  See `Hardware-wrapped keys`_.  This flag
927 For v2 policy keys, the kernel keeps track of which user (identified
963   does not support hardware-wrapped keys
975 combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
987 ``Documentation/security/keys/core.rst``).  The key type must be
988 "logon"; keys of this type are kept in kernel memory and cannot be
1011 Removing keys
1020 These two ioctls differ only in cases where v2 policy keys are added
1023 These ioctls don't work on keys that were added via the legacy
1061 For v2 policy keys, this ioctl is usable by non-root users.  However,
1113 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
1117 only meaningful if non-root users are adding and removing keys.
1172       has added by the current user.  This is only set for keys
1176   This is only set for keys identified by ``identifier`` rather than
1192 FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
1351 more information about hardware-wrapped keys, see below.
1353 Hardware-wrapped keys
1356 fscrypt supports using *hardware-wrapped keys* when the inline
1357 encryption hardware supports it.  Such keys are only present in kernel
1360 to the current boot.  This prevents the keys from being compromised if
1362 keys that can be used and while still allowing the execution of
1366 Note that hardware-wrapped keys aren't specific to fscrypt; they are a
1368 hardware-wrapped keys, see the block layer documentation at
1371 the details of how fscrypt can use hardware-wrapped keys.
1373 fscrypt supports hardware-wrapped keys by allowing the fscrypt master
1374 keys to be hardware-wrapped keys as an alternative to raw keys.  To
1391 allow the hardware to derive per-file keys.
1396 the case with raw keys, the block layer will program the key into a
1405 uses its master keys to derive filenames encryption keys, key
1407 dirhash keys.  So even with file contents encryption out of the
1412 its KDF to derive all subkeys other than file contents keys.
1415 protects the file contents encryption keys.  It doesn't protect other
1416 fscrypt subkeys such as filenames encryption keys.
1484 keys`_ and `DIRECT_KEY policies`_.