Lines Matching +full:kernel +full:- +full:policy
2 Filesystem-level encryption (fscrypt)
11 Note: "fscrypt" in this document refers to the kernel-level portion,
14 covers the kernel-level portion. For command-line examples of how to
20 <https://source.android.com/security/encryption/file-based>`_, over
21 using the kernel's API directly. Using existing tools reduces the
23 completeness this documentation covers the kernel's API anyway.)
25 Unlike dm-crypt, fscrypt operates at the filesystem level rather than
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.
34 directly into supported filesystems --- currently ext4, F2FS, and
44 fscrypt does not support encrypting files in-place. Instead, it
54 ---------------
58 event of a single point-in-time permanent offline compromise of the
60 non-filename metadata, e.g. file sizes, file permissions, file
70 --------------
75 Side-channel attacks
78 fscrypt is only resistant to side-channel attacks, such as timing or
81 such as a table-based implementation of AES, it may be possible for an
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
102 Kernel memory compromise
106 memory, e.g. by mounting a physical attack or by exploiting a kernel
110 However, fscrypt allows encryption keys to be removed from the kernel,
115 encryption key from kernel memory. If it does so, it will also try to
117 thereby wiping their per-file keys and making them once again appear
122 - Per-file keys for in-use files will *not* be removed or wiped.
128 - The kernel cannot magically wipe copies of the master key(s) that
137 - In general, decrypted contents and filenames in the kernel VFS
141 CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1
142 to your kernel command line. However, this has a performance cost.
144 - Secret keys might still exist in CPU registers, in crypto
154 - There is no verification that the provided master key is correct.
156 with another user's encrypted files to which they have read-only
160 meaning of "read-only access".
162 - A compromise of a per-file key also compromises the master key from
165 - Non-root users cannot securely remove encryption keys.
175 -----------
180 encryption modes being used. For example, if any AES-256 mode is
183 policy and AES-256-XTS is used; such keys must be 64 bytes.
192 **must not** directly use a password as a master key, zero-pad a
199 (Key Derivation Function). The kernel does not do any key stretching;
200 therefore, if userspace derives the key from a low-entropy secret such
205 -----------------------
214 encryption policies. (No real-world attack is currently known on this
218 For v1 encryption policies, the KDF only supports deriving per-file
220 AES-128-ECB, using the file's 16-byte nonce as the AES key. The
224 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
226 "application-specific information string" is used for each distinct
227 key to be derived. For example, when a per-file encryption key is
228 derived, the application-specific information string is the file's
232 HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
235 used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
237 Per-file encryption keys
238 ------------------------
243 cases, fscrypt does this by deriving per-file keys. When a new
245 fscrypt randomly generates a 16-byte nonce and stores it in the
251 require larger xattrs which would be less likely to fit in-line in the
260 -------------------
264 long IVs --- long enough to hold both an 8-byte logical block number
265 and a 16-byte per-file nonce. Also, the overhead of each Adiantum key
266 is greater than that of an AES-256-XTS key.
270 this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
271 per-file encryption keys are not used. Instead, whenever any data
272 (contents or filenames) is encrypted, the file's 16-byte nonce is
275 - For v1 encryption policies, the encryption is done directly with the
279 - For v2 encryption policies, the encryption is done with a per-mode
284 -----------------------
286 When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy,
299 -----------------------
302 IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
304 logical block number mod 2^32 to produce a 32-bit IV.
313 ---------------
315 For master keys used for v2 encryption policies, a unique 16-byte "key
320 ------------
322 For directories that are indexed using a secret-keyed dirhash over the
323 plaintext filenames, the KDF is also used to derive a 128-bit
324 SipHash-2-4 key per directory in order to hash filenames. This works
325 just like deriving a per-file encryption key, except that a different
326 KDF context is used. Currently, only casefolded ("case-insensitive")
337 - AES-256-XTS for contents and AES-256-CTS-CBC for filenames
338 - AES-128-CBC for contents and AES-128-CTS-CBC for filenames
339 - Adiantum for both contents and filenames
341 If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
343 AES-128-CBC was added only for low-powered embedded devices with
345 use AES-128-CBC, CONFIG_CRYPTO_ESSIV and CONFIG_CRYPTO_SHA256 (or
346 another SHA-256 implementation) must be enabled so that ESSIV can be
349 Adiantum is a (primarily) stream cipher-based mode that is fast even
351 wide-block mode, unlike XTS. It can also eliminate the need to derive
352 per-file encryption keys. However, it depends on the security of two
353 primitives, XChaCha12 and AES-256, rather than just one. See the
354 paper "Adiantum: length-preserving encryption for entry-level
366 -------------------
369 Starting from Linux kernel 5.5, encryption of filesystems with block
375 - With CBC mode encryption, ESSIV is also used. Specifically, each IV
376 is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
379 - With `DIRECT_KEY policies`_, the file's nonce is appended to the IV.
382 - With `IV_INO_LBLK_64 policies`_, the logical block number is limited
383 to 32 bits and is placed in bits 0-31 of the IV. The inode number
384 (which is also limited to 32 bits) is placed in bits 32-63.
386 - With `IV_INO_LBLK_32 policies`_, the logical block number is limited
387 to 32 bits and is placed in bits 0-31 of the IV. The inode number
395 --------------------
407 With CTS-CBC, the IV reuse means that when the plaintext filenames
411 weakness, as it is a wide-block encryption mode.
415 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
417 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
418 16, or 32-byte boundary (configurable). 32 is recommended since this
431 Setting an encryption policy
432 ----------------------------
437 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
439 has the specified encryption policy. It takes in a pointer to
467 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
470 policy version as "v1", though its version code is really 0.)
473 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
479 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
481 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
484 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
485 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
487 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
496 - For v2 encryption policies, ``__reserved`` must be zeroed.
498 - For v1 encryption policies, ``master_key_descriptor`` specifies how
502 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
511 the kernel returned in the struct fscrypt_add_key_arg must
517 encryption policy is assigned to the directory, turning it into an
521 directory will be encrypted, inheriting the same encryption policy.
526 policy exactly matches the actual one. If they match, then the ioctl
530 When a v2 encryption policy is assigned to a directory, it is also
541 filesystem with one key should consider using dm-crypt instead.
545 - ``EACCES``: the file is not owned by the process's uid, nor does the
548 - ``EEXIST``: the file is already encrypted with an encryption policy
550 - ``EINVAL``: an invalid encryption policy was specified (invalid
552 encryption policy was specified but the directory has the casefold
554 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
558 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
560 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
561 - ``ENOTTY``: this type of filesystem does not implement encryption
562 - ``EOPNOTSUPP``: the kernel was not configured with encryption
566 kernel config, and the superblock must have had the "encrypt"
567 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
569 - ``EPERM``: this directory may not be encrypted, e.g. because it is
571 - ``EROFS``: the filesystem is readonly
573 Getting an encryption policy
574 ----------------------------
576 Two ioctls are available to get a file's encryption policy:
578 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
579 - `FS_IOC_GET_ENCRYPTION_POLICY`_
591 policy, if any, for a directory or regular file. No additional
602 } policy; /* output */
606 the policy struct, i.e. ``sizeof(arg.policy)``.
608 On success, the policy struct is returned in ``policy``, and its
609 actual size is returned in ``policy_size``. ``policy.version`` should
610 be checked to determine the version of policy returned. Note that the
611 version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
615 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
616 encryption policy version
617 - ``ENODATA``: the file is not encrypted
618 - ``ENOTTY``: this type of filesystem does not implement encryption,
619 or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
621 - ``EOPNOTSUPP``: the kernel was not configured with encryption
624 - ``EOVERFLOW``: the file is encrypted and uses a recognized
625 encryption policy version, but the policy struct does not fit into
637 encryption policy, if any, for a directory or regular file. However,
639 FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
646 encrypted using a newer encryption policy version.
648 Getting the per-filesystem salt
649 -------------------------------
653 generated 16-byte value stored in the filesystem superblock. This
655 from a passphrase or other low-entropy user credential.
661 ---------------------------------
664 On encrypted files and directories it gets the inode's 16-byte nonce.
672 -----------
714 - If the key is being added for use by v1 encryption policies, then
725 an *output* field which the kernel fills in with a cryptographic
731 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
735 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
737 type "fscrypt-provisioning" whose payload is
740 Since ``raw`` is variable-length, the total size of this key's
747 allow re-adding keys after a filesystem is unmounted and re-mounted,
750 - ``raw`` is a variable-length field which must contain the actual
754 For v2 policy keys, the kernel keeps track of which user (identified
756 removed by that user --- or by "root", if they use
761 FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
772 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
776 - ``EDQUOT``: the key quota for this user would be exceeded by adding
778 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
780 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
782 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
784 - ``ENOTTY``: this type of filesystem does not implement encryption
785 - ``EOPNOTSUPP``: the kernel was not configured with encryption
793 provided by adding it to a process-subscribed keyring, e.g. to a
809 Nevertheless, to add a key to one of the process-subscribed keyrings,
812 "logon"; keys of this type are kept in kernel memory and cannot be
814 followed by the 16-character lower case hex representation of the
815 ``master_key_descriptor`` that was set in the encryption policy. The
828 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
831 with a filesystem-specific prefix such as "ext4:". However, the
832 filesystem-specific prefixes are deprecated and should not be used in
836 -------------
841 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
842 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
844 These two ioctls differ only in cases where v2 policy keys are added
845 or removed by non-root users.
848 process-subscribed keyrings mechanism.
850 Before using these ioctls, read the `Kernel memory compromise`_
874 - The key to remove is specified by ``key_spec``:
876 - To remove a key used by v1 encryption policies, set
882 - To remove a key used by v2 encryption policies, set
886 For v2 policy keys, this ioctl is usable by non-root users. However,
901 lock files that are still in-use, so this ioctl is expected to be used
913 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
914 are still in-use. Not guaranteed to be set in the case where only
916 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
921 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
924 - ``EINVAL``: invalid key specifier type, or reserved bits were set
925 - ``ENOKEY``: the key object was not found at all, i.e. it was never
929 - ``ENOTTY``: this type of filesystem does not implement encryption
930 - ``EOPNOTSUPP``: the kernel was not configured with encryption
938 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
942 only meaningful if non-root users are adding and removing keys.
949 ------------------
978 - To get the status of a key for v1 encryption policies, set
982 - To get the status of a key for v2 encryption policies, set
986 On success, 0 is returned and the kernel fills in the output fields:
988 - ``status`` indicates whether the key is absent, present, or
994 - ``status_flags`` can contain the following flags:
996 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1000 - ``user_count`` specifies the number of users who have added the key.
1006 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1007 - ``ENOTTY``: this type of filesystem does not implement encryption
1008 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1018 the filesystem-level keyring, i.e. the keyring managed by
1022 process-subscribed keyrings.
1028 ------------
1031 symlinks behave very similarly to their unencrypted counterparts ---
1035 - Unencrypted files, or files encrypted with a different encryption
1036 policy (i.e. different key, modes, or flags), cannot be renamed or
1037 linked into an encrypted directory; see `Encryption policy
1050 - Direct I/O is not supported on encrypted files. Attempts to use
1053 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1057 - Online defragmentation of encrypted files is not supported. The
1061 - The ext4 filesystem does not support data journaling with encrypted
1064 - DAX (Direct Access) is not supported on encrypted files.
1066 - The st_size of an encrypted symlink will not necessarily give the
1069 than the plaintext due to NUL-padding and an extra 2-byte overhead.
1071 - The maximum length of an encrypted symlink is 2 bytes shorter than
1081 ---------------
1087 - File metadata may be read, e.g. using stat().
1089 - Directories may be listed, in which case the filenames will be
1100 - Files may be deleted. That is, nondirectory files may be deleted
1102 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
1105 - Symlink targets may be read and followed, but they will be presented
1124 Encryption policy enforcement
1127 After an encryption policy has been set on a directory, all regular
1129 (recursively) will inherit that encryption policy. Special files ---
1130 that is, named pipes, device nodes, and UNIX domain sockets --- will
1134 files, or files encrypted with a different encryption policy, in an
1137 during ->lookup() to provide limited protection against offline
1141 this by validating all top-level encryption policies prior to access.
1147 ------------------
1149 An encryption policy is represented on-disk by
1153 exposed by the xattr-related system calls such as getxattr() and
1155 (In particular, there would be much confusion if an encryption policy
1183 policy structs (see `Setting an encryption policy`_), except that the
1185 by the kernel and is used as KDF input or as a tweak to cause
1186 different files to be encrypted differently; see `Per-file encryption
1190 -----------------
1192 For the read path (->readpage()) of regular files, filesystems can
1193 read the ciphertext into the page cache and decrypt it in-place. The
1197 For the write path (->writepage()) of regular files, filesystems
1198 cannot encrypt data in-place in the page cache, since the cached
1206 kernel crypto API for en/decryption of file contents. When possible,
1209 uses blk-crypto to perform the en/decryption instead of making use of
1218 -----------------------------
1222 filename hashes. When a ->lookup() is requested, the filesystem
1232 i.e. the bytes actually stored on-disk in the directory entries. When
1233 asked to do a ->lookup() with the key, the filesystem just encrypts
1234 the user-supplied name to get the ciphertext.
1238 filenames. Therefore, readdir() must base64-encode the ciphertext for
1239 presentation. For most filenames, this works fine; on ->lookup(), the
1240 filesystem just base64-decodes the user-supplied name to get back to
1247 filesystem-specific hash(es) needed for directory lookups. This
1249 the filename given in ->lookup() back to a particular directory entry
1256 ``rm -r`` work as expected on encrypted directories.
1266 f2fs encryption using `kvm-xfstests
1267 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1269 kvm-xfstests -c ext4,f2fs -g encrypt
1270 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1273 a separate command, and it takes some time for kvm-xfstests to set up
1276 kvm-xfstests -c ubifs -g encrypt
1278 No tests should fail. However, tests that use non-default encryption
1280 algorithms were not built into the kernel's crypto API. Also, tests
1289 kvm-xfstests, use the "encrypt" filesystem configuration::
1291 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1292 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1294 Because this runs many more tests than "-g encrypt" does, it takes
1295 much longer to run; so also consider using `gce-xfstests
1296 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1297 instead of kvm-xfstests::
1299 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1300 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt