Lines Matching +full:master +full:- +full:kernel
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 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,
114 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
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.
124 encrypted files and directories before removing a master key, as
128 - The kernel cannot magically wipe copies of the master key(s) that
130 copies of the master key(s) it makes as well; normally this should
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.
174 Master Keys
175 -----------
177 Each encrypted directory tree is protected by a *master key*. Master
180 encryption modes being used. For example, if any AES-256 mode is
181 used, the master key must be at least 256 bits, i.e. 32 bytes. A
183 policy and AES-256-XTS is used; such keys must be 64 bytes.
186 appropriate master key. There can be any number of master keys, each
190 Master keys must be real cryptographic keys, i.e. indistinguishable
192 **must not** directly use a password as a master key, zero-pad a
197 Instead, users should generate master keys either using 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 -----------------------
207 With one exception, fscrypt never uses the master key(s) for
211 The KDF used for a particular master key differs depending on whether
214 encryption policies. (No real-world attack is currently known on this
218 For v1 encryption policies, the KDF only supports deriving per-file
219 encryption keys. It works by encrypting the master key with
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
234 entropy from the master key. HKDF is also standardized and widely
235 used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
237 Per-file encryption keys
238 ------------------------
240 Since each master key can protect many files, it is necessary to
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
247 derivation function`_) to derive the file's key from the master key
251 require larger xattrs which would be less likely to fit in-line in the
255 alternative master keys or to support rotating master keys. Instead,
256 the master keys may be wrapped in userspace, e.g. as is done by 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.
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
276 master key. Because of this, users **must not** use the same master
279 - For v2 encryption policies, the encryption is done with a per-mode
280 key derived using the KDF. Users may use the same master key for
284 -----------------------
287 the encryption keys are derived from the master key, encryption mode
289 protected by the same master key sharing a single contents encryption
299 -----------------------
302 IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
303 SipHash key is derived from the master key) and added to the file
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 ---------------
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 -------------------
455 Starting from Linux kernel 5.5, encryption of filesystems with block
461 - With CBC mode encryption, ESSIV is also used. Specifically, each IV
462 is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
465 - With `DIRECT_KEY policies`_, the file's nonce is appended to the IV.
468 - With `IV_INO_LBLK_64 policies`_, the logical block number is limited
469 to 32 bits and is placed in bits 0-31 of the IV. The inode number
470 (which is also limited to 32 bits) is placed in bits 32-63.
472 - With `IV_INO_LBLK_32 policies`_, the logical block number is limited
473 to 32 bits and is placed in bits 0-31 of the IV. The inode number
481 --------------------
493 With CTS-CBC, the IV reuse means that when the plaintext filenames share a
497 wide-block encryption modes.
501 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
503 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
504 16, or 32-byte boundary (configurable). 32 is recommended since this
518 ----------------------------
553 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
559 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
572 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
574 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
577 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
578 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
580 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
589 - For v2 encryption policies, ``__reserved`` must be zeroed.
591 - For v1 encryption policies, ``master_key_descriptor`` specifies how
592 to find the master key in a keyring; see `Adding keys`_. It is up
594 master key. The e4crypt and fscrypt tools use the first 8 bytes of
595 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
596 required. Also, the master key need not be in the keyring yet when
604 the kernel returned in the struct fscrypt_add_key_arg must
612 corresponding master key as described in `Adding keys`_, all regular
634 filesystem with one key should consider using dm-crypt instead.
638 - ``EACCES``: the file is not owned by the process's uid, nor does the
641 - ``EEXIST``: the file is already encrypted with an encryption policy
643 - ``EINVAL``: an invalid encryption policy was specified (invalid
647 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
651 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
653 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
654 - ``ENOTTY``: this type of filesystem does not implement encryption
655 - ``EOPNOTSUPP``: the kernel was not configured with encryption
659 kernel config, and the superblock must have had the "encrypt"
660 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
662 - ``EPERM``: this directory may not be encrypted, e.g. because it is
664 - ``EROFS``: the filesystem is readonly
667 ----------------------------
671 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
672 - `FS_IOC_GET_ENCRYPTION_POLICY`_
708 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
710 - ``ENODATA``: the file is not encrypted
711 - ``ENOTTY``: this type of filesystem does not implement encryption,
712 or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
714 - ``EOPNOTSUPP``: the kernel was not configured with encryption
717 - ``EOVERFLOW``: the file is encrypted and uses a recognized
741 Getting the per-filesystem salt
742 -------------------------------
746 generated 16-byte value stored in the filesystem superblock. This
748 from a passphrase or other low-entropy user credential.
754 ---------------------------------
757 On encrypted files and directories it gets the inode's 16-byte nonce.
765 -----------
770 The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
807 - If the key is being added for use by v1 encryption policies, then
818 an *output* field which the kernel fills in with a cryptographic
824 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
828 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
830 type "fscrypt-provisioning" whose payload is
833 Since ``raw`` is variable-length, the total size of this key's
840 allow re-adding keys after a filesystem is unmounted and re-mounted,
843 - ``raw`` is a variable-length field which must contain the actual
847 For v2 policy keys, the kernel keeps track of which user (identified
849 removed by that user --- or by "root", if they use
865 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
869 - ``EDQUOT``: the key quota for this user would be exceeded by adding
871 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
873 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
875 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
877 - ``ENOTTY``: this type of filesystem does not implement encryption
878 - ``EOPNOTSUPP``: the kernel was not configured with encryption
885 For v1 encryption policies, a master encryption key can also be
886 provided by adding it to a process-subscribed keyring, e.g. to a
902 Nevertheless, to add a key to one of the process-subscribed keyrings,
905 "logon"; keys of this type are kept in kernel memory and cannot be
907 followed by the 16-character lower case hex representation of the
921 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
924 with a filesystem-specific prefix such as "ext4:". However, the
925 filesystem-specific prefixes are deprecated and should not be used in
929 -------------
934 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
935 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
938 or removed by non-root users.
941 process-subscribed keyrings mechanism.
943 Before using these ioctls, read the `Kernel memory compromise`_
950 The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
967 - The key to remove is specified by ``key_spec``:
969 - To remove a key used by v1 encryption policies, set
975 - To remove a key used by v2 encryption policies, set
979 For v2 policy keys, this ioctl is usable by non-root users. However,
994 lock files that are still in-use, so this ioctl is expected to be used
1006 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
1007 are still in-use. Not guaranteed to be set in the case where only
1009 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
1014 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
1017 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1018 - ``ENOKEY``: the key object was not found at all, i.e. it was never
1022 - ``ENOTTY``: this type of filesystem does not implement encryption
1023 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1035 only meaningful if non-root users are adding and removing keys.
1042 ------------------
1048 master encryption key. It can be executed on any file or directory on
1071 - To get the status of a key for v1 encryption policies, set
1075 - To get the status of a key for v2 encryption policies, set
1079 On success, 0 is returned and the kernel fills in the output fields:
1081 - ``status`` indicates whether the key is absent, present, or
1082 incompletely removed. Incompletely removed means that the master
1087 - ``status_flags`` can contain the following flags:
1089 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1093 - ``user_count`` specifies the number of users who have added the key.
1099 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1100 - ``ENOTTY``: this type of filesystem does not implement encryption
1101 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1111 the filesystem-level keyring, i.e. the keyring managed by
1115 process-subscribed keyrings.
1121 ------------
1124 symlinks behave very similarly to their unencrypted counterparts ---
1128 - Unencrypted files, or files encrypted with a different encryption
1143 - Direct I/O is supported on encrypted files only under some
1146 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1150 - Online defragmentation of encrypted files is not supported. The
1154 - The ext4 filesystem does not support data journaling with encrypted
1157 - DAX (Direct Access) is not supported on encrypted files.
1159 - The maximum length of an encrypted symlink is 2 bytes shorter than
1169 ---------------
1175 - File metadata may be read, e.g. using stat().
1177 - Directories may be listed, in which case the filenames will be
1188 - Files may be deleted. That is, nondirectory files may be deleted
1190 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
1193 - Symlink targets may be read and followed, but they will be presented
1217 (recursively) will inherit that encryption policy. Special files ---
1218 that is, named pipes, device nodes, and UNIX domain sockets --- will
1225 during ->lookup() to provide limited protection against offline
1229 this by validating all top-level encryption policies prior to access.
1234 By default, fscrypt uses the kernel crypto API for all cryptographic
1236 itself). The kernel crypto API supports hardware crypto accelerators,
1246 through a set of extensions to the block layer called *blk-crypto*.
1247 blk-crypto allows filesystems to attach encryption contexts to bios
1249 in-line. For more information about blk-crypto, see
1250 :ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1253 blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1255 the kernel configuration, and specify the "inlinecrypt" mount option
1260 still fall back to using the kernel crypto API on files where the
1263 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1264 to be usable, it must be enabled in the kernel configuration with
1272 the on-disk format, so users may freely switch back and forth between
1283 the filesystem must be mounted with ``-o inlinecrypt`` and inline
1300 ------------------
1302 An encryption policy is represented on-disk by
1306 exposed by the xattr-related system calls such as getxattr() and
1338 by the kernel and is used as KDF input or as a tweak to cause
1339 different files to be encrypted differently; see `Per-file encryption
1343 -----------------
1352 For the read path (->read_folio()) of regular files, filesystems can
1353 read the ciphertext into the page cache and decrypt it in-place. The
1357 For the write path (->writepage()) of regular files, filesystems
1358 cannot encrypt data in-place in the page cache, since the cached
1366 -----------------------------
1370 filename hashes. When a ->lookup() is requested, the filesystem
1380 i.e. the bytes actually stored on-disk in the directory entries. When
1381 asked to do a ->lookup() with the key, the filesystem just encrypts
1382 the user-supplied name to get the ciphertext.
1386 filenames. Therefore, readdir() must base64url-encode the ciphertext
1387 for presentation. For most filenames, this works fine; on ->lookup(),
1388 the filesystem just base64url-decodes the user-supplied name to get
1395 filesystem-specific hash(es) needed for directory lookups. This
1397 the filename given in ->lookup() back to a particular directory entry
1404 ``rm -r`` work as expected on encrypted directories.
1414 f2fs encryption using `kvm-xfstests
1415 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1417 kvm-xfstests -c ext4,f2fs -g encrypt
1418 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1421 a separate command, and it takes some time for kvm-xfstests to set up
1424 kvm-xfstests -c ubifs -g encrypt
1426 No tests should fail. However, tests that use non-default encryption
1428 algorithms were not built into the kernel's crypto API. Also, tests
1437 kvm-xfstests, use the "encrypt" filesystem configuration::
1439 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1440 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1442 Because this runs many more tests than "-g encrypt" does, it takes
1443 much longer to run; so also consider using `gce-xfstests
1444 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1445 instead of kvm-xfstests::
1447 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1448 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt