Lines Matching +full:cpu +full:- +full:ufs
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
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
102 Read-only kernel memory compromise
105 Unless `hardware-wrapped keys`_ are used, an attacker who gains the
108 compromise all fscrypt keys that are currently in-use. This also
112 However, if hardware-wrapped keys are used, then the fscrypt master
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.
135 - The kernel cannot magically wipe copies of the master key(s) that
144 - In general, decrypted contents and filenames in the kernel VFS
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
167 useful if the attacker is significantly time-limited and/or
168 bandwidth-limited, so they can only exfiltrate some data and need to
177 - There is no verification that the provided master key is correct.
179 with another user's encrypted files to which they have read-only
183 meaning of "read-only access".
185 - A compromise of a per-file key also compromises the master key from
188 - Non-root users cannot securely remove encryption keys.
198 hardware-wrapped keys. The use of hardware-wrapped keys modifies the
199 key hierarchy slightly. For details, see `Hardware-wrapped keys`_.
202 -----------
207 encryption modes being used. For example, if any AES-256 mode is
210 policy and AES-256-XTS is used; such keys must be 64 bytes.
219 **must not** directly use a password as a master key, zero-pad a
227 therefore, if userspace derives the key from a low-entropy secret such
232 -----------------------
241 encryption policies. (No real-world attack is currently known on this
245 For v1 encryption policies, the KDF only supports deriving per-file
247 AES-128-ECB, using the file's 16-byte nonce as the AES key. The
251 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
253 "application-specific information string" is used for each distinct
254 key to be derived. For example, when a per-file encryption key is
255 derived, the application-specific information string is the file's
259 HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
262 used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
264 Per-file encryption keys
265 ------------------------
270 cases, fscrypt does this by deriving per-file keys. When a new
272 fscrypt randomly generates a 16-byte nonce and stores it in the
278 require larger xattrs which would be less likely to fit in-line in the
287 -------------------
291 long IVs --- long enough to hold both an 8-byte data unit index and a
292 16-byte per-file nonce. Also, the overhead of each Adiantum key is
293 greater than that of an AES-256-XTS key.
298 per-file encryption keys are not used. Instead, whenever any data
299 (contents or filenames) is encrypted, the file's 16-byte nonce is
302 - For v1 encryption policies, the encryption is done directly with the
306 - For v2 encryption policies, the encryption is done with a per-mode
311 -----------------------
322 compliant with the UFS standard, which supports only 64 IV bits per
326 -----------------------
329 IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
331 unit index mod 2^32 to produce a 32-bit IV.
340 ---------------
342 For master keys used for v2 encryption policies, a unique 16-byte "key
347 ------------
349 For directories that are indexed using a secret-keyed dirhash over the
350 plaintext filenames, the KDF is also used to derive a 128-bit
351 SipHash-2-4 key per directory in order to hash filenames. This works
352 just like deriving a per-file encryption key, except that a different
353 KDF context is used. Currently, only casefolded ("case-insensitive")
364 ---------------
368 - AES-256-XTS for contents and AES-256-CBC-CTS for filenames
369 - AES-256-XTS for contents and AES-256-HCTR2 for filenames
370 - Adiantum for both contents and filenames
371 - AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames
372 - SM4-XTS for contents and SM4-CBC-CTS for filenames
374 Note: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS.
375 So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.
381 `CBC-ESSIV mode
382 <https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(…
383 or a wide-block cipher. Filenames encryption uses a
384 block cipher in `CBC-CTS mode
385 <https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
388 The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default.
392 The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
393 upgrades the filenames encryption to use a wide-block cipher. (A
394 *wide-block cipher*, also called a tweakable super-pseudorandom
396 entire result.) As described in `Filenames encryption`_, a wide-block
397 cipher is the ideal mode for the problem domain, though CBC-CTS is the
402 of hardware acceleration for AES. Adiantum is a wide-block cipher
403 that uses XChaCha12 and AES-256 as its underlying components. Most of
408 The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair was added to try to
410 in the CPU but do have a non-inline crypto engine such as CAAM or CESA
411 that supports AES-CBC (and not AES-XTS). This is deprecated. It has
412 been shown that just doing AES on the CPU is actually faster.
417 - (SM4-XTS, SM4-CBC-CTS)
425 ---------------------
428 only the basic support from the crypto API needed to use AES-256-XTS
429 and AES-256-CBC-CTS encryption. For optimal performance, it is
430 strongly recommended to also enable any available platform-specific
432 wish to use. Support for any "non-default" encryption modes typically
443 - AES-256-XTS and AES-256-CBC-CTS
444 - Recommended:
445 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
446 - x86: CONFIG_CRYPTO_AES_NI_INTEL
448 - AES-256-HCTR2
449 - Mandatory:
450 - CONFIG_CRYPTO_HCTR2
451 - Recommended:
452 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
453 - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE
454 - x86: CONFIG_CRYPTO_AES_NI_INTEL
455 - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI
457 - Adiantum
458 - Mandatory:
459 - CONFIG_CRYPTO_ADIANTUM
460 - Recommended:
461 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
462 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
463 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
464 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
466 - AES-128-CBC-ESSIV and AES-128-CBC-CTS:
467 - Mandatory:
468 - CONFIG_CRYPTO_ESSIV
469 - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
470 - Recommended:
471 - AES-CBC acceleration
474 -------------------
478 data unit incorporates the zero-based index of the data unit within
488 * Fixed-size data units. This is how all filesystems other than UBIFS
490 is zero-padded if needed. By default, the data unit size is equal
492 a sub-block data unit size via the ``log2_data_unit_size`` field of
495 * Variable-size data units. This is what UBIFS does. Each "UBIFS
497 length, possibly compressed data, zero-padded to the next 16-byte
498 boundary. Users cannot select a sub-block data unit size on UBIFS.
504 Therefore a f2fs-compressed file still uses fixed-size data units, and
508 per-file keys. In this case, the IV for each data unit is simply the
510 encryption setting that does not use per-file keys. For these, some
513 - With `DIRECT_KEY policies`_, the data unit index is placed in bits
514 0-63 of the IV, and the file's nonce is placed in bits 64-191.
516 - With `IV_INO_LBLK_64 policies`_, the data unit index is placed in
517 bits 0-31 of the IV, and the file's inode number is placed in bits
518 32-63. This setting is only allowed when data unit indices and
521 - With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed
523 to 32 bits and placed in bits 0-31 of the IV. This setting is only
530 passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
531 key is the SHA-256 hash of the file's contents encryption key.
534 --------------------
546 With CBC-CTS, the IV reuse means that when the plaintext filenames share a
550 wide-block encryption modes.
554 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
556 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
557 16, or 32-byte boundary (configurable). 32 is recommended since this
571 ----------------------------
607 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
613 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
626 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
628 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
631 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
632 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
634 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
643 - ``log2_data_unit_size`` is the log2 of the data unit size in bytes,
647 underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
666 - For v2 encryption policies, ``__reserved`` must be zeroed.
668 - For v1 encryption policies, ``master_key_descriptor`` specifies how
672 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
711 filesystem with one key should consider using dm-crypt instead.
715 - ``EACCES``: the file is not owned by the process's uid, nor does the
718 - ``EEXIST``: the file is already encrypted with an encryption policy
720 - ``EINVAL``: an invalid encryption policy was specified (invalid
724 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
728 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
730 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
731 - ``ENOTTY``: this type of filesystem does not implement encryption
732 - ``EOPNOTSUPP``: the kernel was not configured with encryption
737 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
739 - ``EPERM``: this directory may not be encrypted, e.g. because it is
741 - ``EROFS``: the filesystem is readonly
744 ----------------------------
748 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
749 - `FS_IOC_GET_ENCRYPTION_POLICY`_
785 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
787 - ``ENODATA``: the file is not encrypted
788 - ``ENOTTY``: this type of filesystem does not implement encryption,
791 - ``EOPNOTSUPP``: the kernel was not configured with encryption
794 - ``EOVERFLOW``: the file is encrypted and uses a recognized
818 Getting the per-filesystem salt
819 -------------------------------
823 generated 16-byte value stored in the filesystem superblock. This
825 from a passphrase or other low-entropy user credential.
831 ---------------------------------
834 On encrypted files and directories it gets the inode's 16-byte nonce.
842 -----------
886 - If the key is being added for use by v1 encryption policies, then
903 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
907 - ``key_id`` is 0 if the key is given directly in the ``raw`` field.
909 "fscrypt-provisioning" whose payload is struct
913 variable-length, the total size of this key's payload must be
919 allow re-adding keys after a filesystem is unmounted and re-mounted,
922 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
924 - FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED: This denotes that the key is a
925 hardware-wrapped key. See `Hardware-wrapped keys`_. This flag
928 - ``raw`` is a variable-length field which must contain the actual
936 removed by that user --- or by "root", if they use
952 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
956 - ``EBADMSG``: invalid hardware-wrapped key
957 - ``EDQUOT``: the key quota for this user would be exceeded by adding
959 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
961 - ``EKEYREJECTED``: the key was specified by Linux key ID, but the key
963 - ``ENOKEY``: the key was specified by Linux key ID, but no key exists
965 - ``ENOTTY``: this type of filesystem does not implement encryption
966 - ``EOPNOTSUPP``: the kernel was not configured with encryption
970 does not support hardware-wrapped keys
976 provided by adding it to a process-subscribed keyring, e.g. to a
992 Nevertheless, to add a key to one of the process-subscribed keyrings,
997 followed by the 16-character lower case hex representation of the
1011 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
1014 with a filesystem-specific prefix such as "ext4:". However, the
1015 filesystem-specific prefixes are deprecated and should not be used in
1019 -------------
1024 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
1025 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
1028 or removed by non-root users.
1031 process-subscribed keyrings mechanism.
1056 - The key to remove is specified by ``key_spec``:
1058 - To remove a key used by v1 encryption policies, set
1064 - To remove a key used by v2 encryption policies, set
1068 For v2 policy keys, this ioctl is usable by non-root users. However,
1083 lock files that are still in-use, so this ioctl is expected to be used
1095 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
1096 are still in-use. Not guaranteed to be set in the case where only
1098 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
1103 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
1106 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1107 - ``ENOKEY``: the key object was not found at all, i.e. it was never
1111 - ``ENOTTY``: this type of filesystem does not implement encryption
1112 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1124 only meaningful if non-root users are adding and removing keys.
1131 ------------------
1160 - To get the status of a key for v1 encryption policies, set
1164 - To get the status of a key for v2 encryption policies, set
1170 - ``status`` indicates whether the key is absent, present, or
1176 - ``status_flags`` can contain the following flags:
1178 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1182 - ``user_count`` specifies the number of users who have added the key.
1188 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1189 - ``ENOTTY``: this type of filesystem does not implement encryption
1190 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1200 the filesystem-level keyring, i.e. the keyring managed by
1204 process-subscribed keyrings.
1210 ------------
1213 symlinks behave very similarly to their unencrypted counterparts ---
1217 - Unencrypted files, or files encrypted with a different encryption
1232 - Direct I/O is supported on encrypted files only under some
1235 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1239 - Online defragmentation of encrypted files is not supported. The
1243 - The ext4 filesystem does not support data journaling with encrypted
1246 - DAX (Direct Access) is not supported on encrypted files.
1248 - The maximum length of an encrypted symlink is 2 bytes shorter than
1258 ---------------
1264 - File metadata may be read, e.g. using stat().
1266 - Directories may be listed, in which case the filenames will be
1277 - Files may be deleted. That is, nondirectory files may be deleted
1279 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
1282 - Symlink targets may be read and followed, but they will be presented
1306 (recursively) will inherit that encryption policy. Special files ---
1307 that is, named pipes, device nodes, and UNIX domain sockets --- will
1314 during ->lookup() to provide limited protection against offline
1318 this by validating all top-level encryption policies prior to access.
1326 extensions to the block layer called *blk-crypto*. blk-crypto allows
1328 specify how the data will be encrypted or decrypted in-line. For more
1329 information about blk-crypto, see
1330 :ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1333 blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1343 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1346 protected by a raw key rather than a hardware-wrapped key.)
1353 the on-disk format, so users may freely switch back and forth between
1355 files that are protected by a hardware-wrapped key can only be
1358 more information about hardware-wrapped keys, see below.
1360 Hardware-wrapped keys
1361 ---------------------
1363 fscrypt supports using *hardware-wrapped keys* when the inline
1373 Note that hardware-wrapped keys aren't specific to fscrypt; they are a
1374 block layer feature (part of *blk-crypto*). For more details about
1375 hardware-wrapped keys, see the block layer documentation at
1376 :ref:`Documentation/block/inline-encryption.rst
1378 the details of how fscrypt can use hardware-wrapped keys.
1380 fscrypt supports hardware-wrapped keys by allowing the fscrypt master
1381 keys to be hardware-wrapped keys as an alternative to raw keys. To
1382 add a hardware-wrapped key with `FS_IOC_ADD_ENCRYPTION_KEY`_,
1386 applicable. The key must be in ephemerally-wrapped form, not
1387 long-term wrapped form.
1389 Some limitations apply. First, files protected by a hardware-wrapped
1393 currently the hardware-wrapped key support is only compatible with
1397 this limitation by passing per-file nonces down the storage stack to
1398 allow the hardware to derive per-file keys.
1400 Implementation-wise, to encrypt/decrypt the contents of files that are
1401 protected by a hardware-wrapped key, fscrypt uses blk-crypto,
1402 attaching the hardware-wrapped key to the bio crypt contexts. As is
1405 hardware-wrapped key, the hardware doesn't program the given key
1416 key from a hardware-wrapped key, fscrypt asks the inline encryption
1418 the hardware-wrapped key. fscrypt uses this "software secret" to key
1421 Note that this implies that the hardware-wrapped key feature only
1433 the filesystem must be mounted with ``-o inlinecrypt`` and inline
1450 ------------------
1452 An encryption policy is represented on-disk by
1456 exposed by the xattr-related system calls such as getxattr() and
1490 different files to be encrypted differently; see `Per-file encryption
1494 -----------------
1503 For the read path (->read_folio()) of regular files, filesystems can
1504 read the ciphertext into the page cache and decrypt it in-place. The
1508 For the write path (->writepages()) of regular files, filesystems
1509 cannot encrypt data in-place in the page cache, since the cached
1517 -----------------------------
1521 filename hashes. When a ->lookup() is requested, the filesystem
1531 i.e. the bytes actually stored on-disk in the directory entries. When
1532 asked to do a ->lookup() with the key, the filesystem just encrypts
1533 the user-supplied name to get the ciphertext.
1537 filenames. Therefore, readdir() must base64url-encode the ciphertext
1538 for presentation. For most filenames, this works fine; on ->lookup(),
1539 the filesystem just base64url-decodes the user-supplied name to get
1546 filesystem-specific hash(es) needed for directory lookups. This
1548 the filename given in ->lookup() back to a particular directory entry
1555 ``rm -r`` work as expected on encrypted directories.
1565 f2fs encryption using `kvm-xfstests
1566 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1568 kvm-xfstests -c ext4,f2fs -g encrypt
1569 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1572 a separate command, and it takes some time for kvm-xfstests to set up
1575 kvm-xfstests -c ubifs -g encrypt
1577 No tests should fail. However, tests that use non-default encryption
1588 kvm-xfstests, use the "encrypt" filesystem configuration::
1590 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1591 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1593 Because this runs many more tests than "-g encrypt" does, it takes
1594 much longer to run; so also consider using `gce-xfstests
1595 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1596 instead of kvm-xfstests::
1598 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1599 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt