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, UBIFS,
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 vulnerable algorithm is used, such as a table-based implementation 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
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 data unit index and a
265 16-byte per-file nonce. Also, the overhead of each Adiantum key is
266 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 unit index 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 ---------------
341 - AES-256-XTS for contents and AES-256-CTS-CBC for filenames
342 - AES-256-XTS for contents and AES-256-HCTR2 for filenames
343 - Adiantum for both contents and filenames
344 - AES-128-CBC-ESSIV for contents and AES-128-CTS-CBC for filenames
345 - SM4-XTS for contents and SM4-CTS-CBC for filenames
351 `CBC-ESSIV mode
352 <https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(…
353 or a wide-block cipher. Filenames encryption uses a
354 block cipher in `CTS-CBC mode
355 <https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
358 The (AES-256-XTS, AES-256-CTS-CBC) pair is the recommended default.
360 if the kernel supports fscrypt at all; see `Kernel config options`_.
362 The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
363 upgrades the filenames encryption to use a wide-block cipher. (A
364 *wide-block cipher*, also called a tweakable super-pseudorandom
366 entire result.) As described in `Filenames encryption`_, a wide-block
367 cipher is the ideal mode for the problem domain, though CTS-CBC is the
372 of hardware acceleration for AES. Adiantum is a wide-block cipher
373 that uses XChaCha12 and AES-256 as its underlying components. Most of
378 The (AES-128-CBC-ESSIV, AES-128-CTS-CBC) pair exists only to support
379 systems whose only form of AES acceleration is an off-CPU crypto
384 - (SM4-XTS, SM4-CTS-CBC)
391 Kernel config options
392 ---------------------
395 only the basic support from the crypto API needed to use AES-256-XTS
396 and AES-256-CTS-CBC encryption. For optimal performance, it is
397 strongly recommended to also enable any available platform-specific
399 wish to use. Support for any "non-default" encryption modes typically
406 kernel crypto API (see `Inline encryption support`_); in that case,
407 the file contents mode doesn't need to supported in the kernel crypto
410 - AES-256-XTS and AES-256-CTS-CBC
411 - Recommended:
412 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
413 - x86: CONFIG_CRYPTO_AES_NI_INTEL
415 - AES-256-HCTR2
416 - Mandatory:
417 - CONFIG_CRYPTO_HCTR2
418 - Recommended:
419 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
420 - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE
421 - x86: CONFIG_CRYPTO_AES_NI_INTEL
422 - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI
424 - Adiantum
425 - Mandatory:
426 - CONFIG_CRYPTO_ADIANTUM
427 - Recommended:
428 - arm32: CONFIG_CRYPTO_CHACHA20_NEON
429 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
430 - arm64: CONFIG_CRYPTO_CHACHA20_NEON
431 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
432 - x86: CONFIG_CRYPTO_CHACHA20_X86_64
433 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
434 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
436 - AES-128-CBC-ESSIV and AES-128-CTS-CBC:
437 - Mandatory:
438 - CONFIG_CRYPTO_ESSIV
439 - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
440 - Recommended:
441 - AES-CBC acceleration
443 fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512
446 - SHA-512
447 - Recommended:
448 - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
449 - x86: CONFIG_CRYPTO_SHA512_SSSE3
452 -------------------
456 data unit incorporates the zero-based index of the data unit within
466 * Fixed-size data units. This is how all filesystems other than UBIFS
468 is zero-padded if needed. By default, the data unit size is equal
470 a sub-block data unit size via the ``log2_data_unit_size`` field of
471 the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_.
473 * Variable-size data units. This is what UBIFS does. Each "UBIFS
475 length, possibly compressed data, zero-padded to the next 16-byte
476 boundary. Users cannot select a sub-block data unit size on UBIFS.
482 Therefore a f2fs-compressed file still uses fixed-size data units, and
486 per-file keys. In this case, the IV for each data unit is simply the
488 encryption setting that does not use per-file keys. For these, some
491 - With `DIRECT_KEY policies`_, the data unit index is placed in bits
492 0-63 of the IV, and the file's nonce is placed in bits 64-191.
494 - With `IV_INO_LBLK_64 policies`_, the data unit index is placed in
495 bits 0-31 of the IV, and the file's inode number is placed in bits
496 32-63. This setting is only allowed when data unit indices and
499 - With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed
501 to 32 bits and placed in bits 0-31 of the IV. This setting is only
508 passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
509 key is the SHA-256 hash of the file's contents encryption key.
512 --------------------
524 With CTS-CBC, the IV reuse means that when the plaintext filenames share a
528 wide-block encryption modes.
532 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
534 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
535 16, or 32-byte boundary (configurable). 32 is recommended since this
548 Setting an encryption policy
549 ----------------------------
554 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
556 has the specified encryption policy. It takes in a pointer to
585 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
588 policy version as "v1", though its version code is really 0.)
591 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
604 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
606 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
609 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
610 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
612 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
621 - ``log2_data_unit_size`` is the log2 of the data unit size in bytes,
625 underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
644 - For v2 encryption policies, ``__reserved`` must be zeroed.
646 - For v1 encryption policies, ``master_key_descriptor`` specifies how
650 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
659 the kernel returned in the struct fscrypt_add_key_arg must
665 encryption policy is assigned to the directory, turning it into an
669 directory will be encrypted, inheriting the same encryption policy.
674 policy exactly matches the actual one. If they match, then the ioctl
678 When a v2 encryption policy is assigned to a directory, it is also
689 filesystem with one key should consider using dm-crypt instead.
693 - ``EACCES``: the file is not owned by the process's uid, nor does the
696 - ``EEXIST``: the file is already encrypted with an encryption policy
698 - ``EINVAL``: an invalid encryption policy was specified (invalid
700 encryption policy was specified but the directory has the casefold
702 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
706 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
708 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
709 - ``ENOTTY``: this type of filesystem does not implement encryption
710 - ``EOPNOTSUPP``: the kernel was not configured with encryption
714 kernel config, and the superblock must have had the "encrypt"
715 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
717 - ``EPERM``: this directory may not be encrypted, e.g. because it is
719 - ``EROFS``: the filesystem is readonly
721 Getting an encryption policy
722 ----------------------------
724 Two ioctls are available to get a file's encryption policy:
726 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
727 - `FS_IOC_GET_ENCRYPTION_POLICY`_
739 policy, if any, for a directory or regular file. No additional
750 } policy; /* output */
754 the policy struct, i.e. ``sizeof(arg.policy)``.
756 On success, the policy struct is returned in ``policy``, and its
757 actual size is returned in ``policy_size``. ``policy.version`` should
758 be checked to determine the version of policy returned. Note that the
759 version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
763 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
764 encryption policy version
765 - ``ENODATA``: the file is not encrypted
766 - ``ENOTTY``: this type of filesystem does not implement encryption,
767 or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
769 - ``EOPNOTSUPP``: the kernel was not configured with encryption
772 - ``EOVERFLOW``: the file is encrypted and uses a recognized
773 encryption policy version, but the policy struct does not fit into
785 encryption policy, if any, for a directory or regular file. However,
787 FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
794 encrypted using a newer encryption policy version.
796 Getting the per-filesystem salt
797 -------------------------------
801 generated 16-byte value stored in the filesystem superblock. This
803 from a passphrase or other low-entropy user credential.
809 ---------------------------------
812 On encrypted files and directories it gets the inode's 16-byte nonce.
820 -----------
862 - If the key is being added for use by v1 encryption policies, then
873 an *output* field which the kernel fills in with a cryptographic
879 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
883 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
885 type "fscrypt-provisioning" whose payload is
888 Since ``raw`` is variable-length, the total size of this key's
895 allow re-adding keys after a filesystem is unmounted and re-mounted,
898 - ``raw`` is a variable-length field which must contain the actual
902 For v2 policy keys, the kernel keeps track of which user (identified
904 removed by that user --- or by "root", if they use
909 FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
920 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
924 - ``EDQUOT``: the key quota for this user would be exceeded by adding
926 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
928 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
930 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
932 - ``ENOTTY``: this type of filesystem does not implement encryption
933 - ``EOPNOTSUPP``: the kernel was not configured with encryption
941 provided by adding it to a process-subscribed keyring, e.g. to a
957 Nevertheless, to add a key to one of the process-subscribed keyrings,
960 "logon"; keys of this type are kept in kernel memory and cannot be
962 followed by the 16-character lower case hex representation of the
963 ``master_key_descriptor`` that was set in the encryption policy. The
976 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
979 with a filesystem-specific prefix such as "ext4:". However, the
980 filesystem-specific prefixes are deprecated and should not be used in
984 -------------
989 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
990 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
992 These two ioctls differ only in cases where v2 policy keys are added
993 or removed by non-root users.
996 process-subscribed keyrings mechanism.
998 Before using these ioctls, read the `Kernel memory compromise`_
1022 - The key to remove is specified by ``key_spec``:
1024 - To remove a key used by v1 encryption policies, set
1030 - To remove a key used by v2 encryption policies, set
1034 For v2 policy keys, this ioctl is usable by non-root users. However,
1049 lock files that are still in-use, so this ioctl is expected to be used
1061 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
1062 are still in-use. Not guaranteed to be set in the case where only
1064 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
1069 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
1072 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1073 - ``ENOKEY``: the key object was not found at all, i.e. it was never
1077 - ``ENOTTY``: this type of filesystem does not implement encryption
1078 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1086 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
1090 only meaningful if non-root users are adding and removing keys.
1097 ------------------
1126 - To get the status of a key for v1 encryption policies, set
1130 - To get the status of a key for v2 encryption policies, set
1134 On success, 0 is returned and the kernel fills in the output fields:
1136 - ``status`` indicates whether the key is absent, present, or
1142 - ``status_flags`` can contain the following flags:
1144 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1148 - ``user_count`` specifies the number of users who have added the key.
1154 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1155 - ``ENOTTY``: this type of filesystem does not implement encryption
1156 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1166 the filesystem-level keyring, i.e. the keyring managed by
1170 process-subscribed keyrings.
1176 ------------
1179 symlinks behave very similarly to their unencrypted counterparts ---
1183 - Unencrypted files, or files encrypted with a different encryption
1184 policy (i.e. different key, modes, or flags), cannot be renamed or
1185 linked into an encrypted directory; see `Encryption policy
1198 - Direct I/O is supported on encrypted files only under some
1201 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1205 - Online defragmentation of encrypted files is not supported. The
1209 - The ext4 filesystem does not support data journaling with encrypted
1212 - DAX (Direct Access) is not supported on encrypted files.
1214 - The maximum length of an encrypted symlink is 2 bytes shorter than
1224 ---------------
1230 - File metadata may be read, e.g. using stat().
1232 - Directories may be listed, in which case the filenames will be
1243 - Files may be deleted. That is, nondirectory files may be deleted
1245 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
1248 - Symlink targets may be read and followed, but they will be presented
1267 Encryption policy enforcement
1270 After an encryption policy has been set on a directory, all regular
1272 (recursively) will inherit that encryption policy. Special files ---
1273 that is, named pipes, device nodes, and UNIX domain sockets --- will
1277 files, or files encrypted with a different encryption policy, in an
1280 during ->lookup() to provide limited protection against offline
1284 this by validating all top-level encryption policies prior to access.
1289 By default, fscrypt uses the kernel crypto API for all cryptographic
1291 itself). The kernel crypto API supports hardware crypto accelerators,
1301 through a set of extensions to the block layer called *blk-crypto*.
1302 blk-crypto allows filesystems to attach encryption contexts to bios
1304 in-line. For more information about blk-crypto, see
1305 :ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1308 blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1310 the kernel configuration, and specify the "inlinecrypt" mount option
1315 still fall back to using the kernel crypto API on files where the
1318 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1319 to be usable, it must be enabled in the kernel configuration with
1327 the on-disk format, so users may freely switch back and forth between
1338 the filesystem must be mounted with ``-o inlinecrypt`` and inline
1355 ------------------
1357 An encryption policy is represented on-disk by
1361 exposed by the xattr-related system calls such as getxattr() and
1363 (In particular, there would be much confusion if an encryption policy
1392 policy structs (see `Setting an encryption policy`_), except that the
1394 by the kernel and is used as KDF input or as a tweak to cause
1395 different files to be encrypted differently; see `Per-file encryption
1399 -----------------
1408 For the read path (->read_folio()) of regular files, filesystems can
1409 read the ciphertext into the page cache and decrypt it in-place. The
1413 For the write path (->writepage()) of regular files, filesystems
1414 cannot encrypt data in-place in the page cache, since the cached
1422 -----------------------------
1426 filename hashes. When a ->lookup() is requested, the filesystem
1436 i.e. the bytes actually stored on-disk in the directory entries. When
1437 asked to do a ->lookup() with the key, the filesystem just encrypts
1438 the user-supplied name to get the ciphertext.
1442 filenames. Therefore, readdir() must base64url-encode the ciphertext
1443 for presentation. For most filenames, this works fine; on ->lookup(),
1444 the filesystem just base64url-decodes the user-supplied name to get
1451 filesystem-specific hash(es) needed for directory lookups. This
1453 the filename given in ->lookup() back to a particular directory entry
1460 ``rm -r`` work as expected on encrypted directories.
1470 f2fs encryption using `kvm-xfstests
1471 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1473 kvm-xfstests -c ext4,f2fs -g encrypt
1474 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1477 a separate command, and it takes some time for kvm-xfstests to set up
1480 kvm-xfstests -c ubifs -g encrypt
1482 No tests should fail. However, tests that use non-default encryption
1484 algorithms were not built into the kernel's crypto API. Also, tests
1493 kvm-xfstests, use the "encrypt" filesystem configuration::
1495 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1496 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1498 Because this runs many more tests than "-g encrypt" does, it takes
1499 much longer to run; so also consider using `gce-xfstests
1500 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1501 instead of kvm-xfstests::
1503 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1504 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt