Lines Matching +full:keys +full:- +full:per +full:- +full:group
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
25 Unlike dm-crypt, fscrypt operates at the filesystem level rather than
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.
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
98 Therefore, any encryption-specific access control checks would merely
107 security vulnerability, can compromise all encryption keys that are
110 However, fscrypt allows encryption keys to be removed from the kernel,
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
135 containing keys to prevent it from being swapped out.
137 - In general, decrypted contents and filenames in the kernel VFS
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 -----------
178 keys can be up to 64 bytes long, and must be at least as long as the
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.
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
200 therefore, if userspace derives the key from a low-entropy secret such
205 -----------------------
209 (Key Derivation Function) to derive the actual keys.
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
230 context bytes are used for other types of derived keys.
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
250 Key derivation was chosen over key wrapping because wrapped keys would
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 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.
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 -----------------------
287 the encryption keys are derived from the master key, encryption mode
295 compliant with the UFS standard, which supports only 64 IV bits per
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.
308 per I/O request and may have only a small number of keyslots. This
313 ---------------
315 For master keys used for v2 encryption policies, a unique 16-byte "key
319 Dirhash keys
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-CBC-CTS 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-CBC-CTS for filenames
345 - SM4-XTS for contents and SM4-CBC-CTS for filenames
347 Note: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS.
348 So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.
354 `CBC-ESSIV mode
355 <https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(…
356 or a wide-block cipher. Filenames encryption uses a
357 block cipher in `CBC-CTS mode
358 <https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
361 The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default.
365 The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
366 upgrades the filenames encryption to use a wide-block cipher. (A
367 *wide-block cipher*, also called a tweakable super-pseudorandom
369 entire result.) As described in `Filenames encryption`_, a wide-block
370 cipher is the ideal mode for the problem domain, though CBC-CTS is the
375 of hardware acceleration for AES. Adiantum is a wide-block cipher
376 that uses XChaCha12 and AES-256 as its underlying components. Most of
381 The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair exists only to support
382 systems whose only form of AES acceleration is an off-CPU crypto
387 - (SM4-XTS, SM4-CBC-CTS)
389 Generally speaking, these ciphers aren't "bad" per se, but they
395 ---------------------
398 only the basic support from the crypto API needed to use AES-256-XTS
399 and AES-256-CBC-CTS encryption. For optimal performance, it is
400 strongly recommended to also enable any available platform-specific
402 wish to use. Support for any "non-default" encryption modes typically
413 - AES-256-XTS and AES-256-CBC-CTS
414 - Recommended:
415 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
416 - x86: CONFIG_CRYPTO_AES_NI_INTEL
418 - AES-256-HCTR2
419 - Mandatory:
420 - CONFIG_CRYPTO_HCTR2
421 - Recommended:
422 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
423 - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE
424 - x86: CONFIG_CRYPTO_AES_NI_INTEL
425 - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI
427 - Adiantum
428 - Mandatory:
429 - CONFIG_CRYPTO_ADIANTUM
430 - Recommended:
431 - arm32: CONFIG_CRYPTO_CHACHA20_NEON
432 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
433 - arm64: CONFIG_CRYPTO_CHACHA20_NEON
434 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
435 - x86: CONFIG_CRYPTO_CHACHA20_X86_64
436 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
437 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
439 - AES-128-CBC-ESSIV and AES-128-CBC-CTS:
440 - Mandatory:
441 - CONFIG_CRYPTO_ESSIV
442 - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
443 - Recommended:
444 - AES-CBC acceleration
446 fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512
449 - SHA-512
450 - Recommended:
451 - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
452 - x86: CONFIG_CRYPTO_SHA512_SSSE3
455 -------------------
459 data unit incorporates the zero-based index of the data unit within
469 * Fixed-size data units. This is how all filesystems other than UBIFS
471 is zero-padded if needed. By default, the data unit size is equal
473 a sub-block data unit size via the ``log2_data_unit_size`` field of
476 * Variable-size data units. This is what UBIFS does. Each "UBIFS
478 length, possibly compressed data, zero-padded to the next 16-byte
479 boundary. Users cannot select a sub-block data unit size on UBIFS.
485 Therefore a f2fs-compressed file still uses fixed-size data units, and
489 per-file keys. In this case, the IV for each data unit is simply the
491 encryption setting that does not use per-file keys. For these, some
494 - With `DIRECT_KEY policies`_, the data unit index is placed in bits
495 0-63 of the IV, and the file's nonce is placed in bits 64-191.
497 - With `IV_INO_LBLK_64 policies`_, the data unit index is placed in
498 bits 0-31 of the IV, and the file's inode number is placed in bits
499 32-63. This setting is only allowed when data unit indices and
502 - With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed
504 to 32 bits and placed in bits 0-31 of the IV. This setting is only
511 passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
512 key is the SHA-256 hash of the file's contents encryption key.
515 --------------------
527 With CBC-CTS, the IV reuse means that when the plaintext filenames share a
531 wide-block encryption modes.
535 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
537 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
538 16, or 32-byte boundary (configurable). 32 is recommended since this
552 ----------------------------
588 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
594 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
607 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
609 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
612 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
613 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
615 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
624 - ``log2_data_unit_size`` is the log2 of the data unit size in bytes,
628 underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
647 - For v2 encryption policies, ``__reserved`` must be zeroed.
649 - For v1 encryption policies, ``master_key_descriptor`` specifies how
650 to find the master key in a keyring; see `Adding keys`_. It is up
653 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
670 corresponding master key as described in `Adding keys`_, all regular
692 filesystem with one key should consider using dm-crypt instead.
696 - ``EACCES``: the file is not owned by the process's uid, nor does the
699 - ``EEXIST``: the file is already encrypted with an encryption policy
701 - ``EINVAL``: an invalid encryption policy was specified (invalid
705 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
709 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
711 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
712 - ``ENOTTY``: this type of filesystem does not implement encryption
713 - ``EOPNOTSUPP``: the kernel was not configured with encryption
718 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
720 - ``EPERM``: this directory may not be encrypted, e.g. because it is
722 - ``EROFS``: the filesystem is readonly
725 ----------------------------
729 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
730 - `FS_IOC_GET_ENCRYPTION_POLICY`_
766 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
768 - ``ENODATA``: the file is not encrypted
769 - ``ENOTTY``: this type of filesystem does not implement encryption,
772 - ``EOPNOTSUPP``: the kernel was not configured with encryption
775 - ``EOVERFLOW``: the file is encrypted and uses a recognized
799 Getting the per-filesystem salt
800 -------------------------------
804 generated 16-byte value stored in the filesystem superblock. This
806 from a passphrase or other low-entropy user credential.
812 ---------------------------------
815 On encrypted files and directories it gets the inode's 16-byte nonce.
822 Adding keys
823 -----------
865 - If the key is being added for use by v1 encryption policies, then
878 not need any privileges. However, the number of keys that can be
880 ``Documentation/security/keys/core.rst``).
882 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
886 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
888 type "fscrypt-provisioning" whose payload is
891 Since ``raw`` is variable-length, the total size of this key's
898 allow re-adding keys after a filesystem is unmounted and re-mounted,
899 without having to store the raw keys in userspace memory.
901 - ``raw`` is a variable-length field which must contain the actual
905 For v2 policy keys, the kernel keeps track of which user (identified
907 removed by that user --- or by "root", if they use
923 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
927 - ``EDQUOT``: the key quota for this user would be exceeded by adding
929 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
931 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
933 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
935 - ``ENOTTY``: this type of filesystem does not implement encryption
936 - ``EOPNOTSUPP``: the kernel was not configured with encryption
944 provided by adding it to a process-subscribed keyring, e.g. to a
950 combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
960 Nevertheless, to add a key to one of the process-subscribed keyrings,
962 ``Documentation/security/keys/core.rst``). The key type must be
963 "logon"; keys of this type are kept in kernel memory and cannot be
965 followed by the 16-character lower case hex representation of the
979 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
982 with a filesystem-specific prefix such as "ext4:". However, the
983 filesystem-specific prefixes are deprecated and should not be used in
986 Removing keys
987 -------------
992 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
993 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
995 These two ioctls differ only in cases where v2 policy keys are added
996 or removed by non-root users.
998 These ioctls don't work on keys that were added via the legacy
999 process-subscribed keyrings mechanism.
1025 - The key to remove is specified by ``key_spec``:
1027 - To remove a key used by v1 encryption policies, set
1033 - To remove a key used by v2 encryption policies, set
1037 For v2 policy keys, this ioctl is usable by non-root users. However,
1052 lock files that are still in-use, so this ioctl is expected to be used
1064 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
1065 are still in-use. Not guaranteed to be set in the case where only
1067 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
1072 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
1075 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1076 - ``ENOKEY``: the key object was not found at all, i.e. it was never
1080 - ``ENOTTY``: this type of filesystem does not implement encryption
1081 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1089 `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
1093 only meaningful if non-root users are adding and removing keys.
1100 ------------------
1129 - To get the status of a key for v1 encryption policies, set
1133 - To get the status of a key for v2 encryption policies, set
1139 - ``status`` indicates whether the key is absent, present, or
1145 - ``status_flags`` can contain the following flags:
1147 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1148 has added by the current user. This is only set for keys
1151 - ``user_count`` specifies the number of users who have added the key.
1152 This is only set for keys identified by ``identifier`` rather than
1157 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1158 - ``ENOTTY``: this type of filesystem does not implement encryption
1159 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1168 FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
1169 the filesystem-level keyring, i.e. the keyring managed by
1173 process-subscribed keyrings.
1179 ------------
1182 symlinks behave very similarly to their unencrypted counterparts ---
1186 - Unencrypted files, or files encrypted with a different encryption
1201 - Direct I/O is supported on encrypted files only under some
1204 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1208 - Online defragmentation of encrypted files is not supported. The
1212 - The ext4 filesystem does not support data journaling with encrypted
1215 - DAX (Direct Access) is not supported on encrypted files.
1217 - The maximum length of an encrypted symlink is 2 bytes shorter than
1227 ---------------
1233 - File metadata may be read, e.g. using stat().
1235 - Directories may be listed, in which case the filenames will be
1246 - Files may be deleted. That is, nondirectory files may be deleted
1248 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
1251 - Symlink targets may be read and followed, but they will be presented
1275 (recursively) will inherit that encryption policy. Special files ---
1276 that is, named pipes, device nodes, and UNIX domain sockets --- will
1283 during ->lookup() to provide limited protection against offline
1287 this by validating all top-level encryption policies prior to access.
1304 through a set of extensions to the block layer called *blk-crypto*.
1305 blk-crypto allows filesystems to attach encryption contexts to bios
1307 in-line. For more information about blk-crypto, see
1308 :ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1311 blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1321 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1330 the on-disk format, so users may freely switch back and forth between
1341 the filesystem must be mounted with ``-o inlinecrypt`` and inline
1358 ------------------
1360 An encryption policy is represented on-disk by
1364 exposed by the xattr-related system calls such as getxattr() and
1398 different files to be encrypted differently; see `Per-file encryption
1399 keys`_ and `DIRECT_KEY policies`_.
1402 -----------------
1411 For the read path (->read_folio()) of regular files, filesystems can
1412 read the ciphertext into the page cache and decrypt it in-place. The
1416 For the write path (->writepage()) of regular files, filesystems
1417 cannot encrypt data in-place in the page cache, since the cached
1425 -----------------------------
1429 filename hashes. When a ->lookup() is requested, the filesystem
1439 i.e. the bytes actually stored on-disk in the directory entries. When
1440 asked to do a ->lookup() with the key, the filesystem just encrypts
1441 the user-supplied name to get the ciphertext.
1445 filenames. Therefore, readdir() must base64url-encode the ciphertext
1446 for presentation. For most filenames, this works fine; on ->lookup(),
1447 the filesystem just base64url-decodes the user-supplied name to get
1454 filesystem-specific hash(es) needed for directory lookups. This
1456 the filename given in ->lookup() back to a particular directory entry
1463 ``rm -r`` work as expected on encrypted directories.
1470 group on the relevant filesystem(s). One can also run the tests
1473 f2fs encryption using `kvm-xfstests
1474 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1476 kvm-xfstests -c ext4,f2fs -g encrypt
1477 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1480 a separate command, and it takes some time for kvm-xfstests to set up
1483 kvm-xfstests -c ubifs -g encrypt
1485 No tests should fail. However, tests that use non-default encryption
1491 Besides running the "encrypt" group tests, for ext4 and f2fs it's also
1496 kvm-xfstests, use the "encrypt" filesystem configuration::
1498 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1499 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1501 Because this runs many more tests than "-g encrypt" does, it takes
1502 much longer to run; so also consider using `gce-xfstests
1503 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1504 instead of kvm-xfstests::
1506 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1507 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt