Lines Matching +full:hardware +full:- +full:protected
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
63 files is not protected.
70 --------------
75 Side-channel attacks
78 fscrypt is only resistant to side-channel attacks, such as timing or
80 Cryptographic API algorithms or inline encryption hardware are. If a
81 vulnerable algorithm is used, such as a table-based implementation of
96 system itself, is *not* protected by the mathematical properties 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
114 subkeys such as filenames encryption keys) are protected from
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
157 arbitrary kernel code can freely exfiltrate data that is protected by
158 any in-use fscrypt keys. Thus, usually fscrypt provides no meaningful
159 protection in this scenario. (Data that is protected by a key that is
160 absent throughout the entire attack remains protected, modulo the
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 -----------
204 Each encrypted directory tree is protected by a *master key*. Master
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 -----------------------
316 protected by the same master key sharing a single contents encryption
321 This format is optimized for use with inline encryption hardware
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.
333 This format is optimized for use with inline encryption hardware
337 when necessary due to hardware limitations.
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
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
438 also be configured to use inline encryption hardware instead of the
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
658 compatibility with inline encryption hardware that only supports
661 particular system's inline encryption hardware.
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
968 had encryption enabled on it; or a hardware wrapped key was specified
969 but the filesystem does not support inline encryption or the hardware
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.
1324 hardware* that can encrypt/decrypt data while it is on its way to/from
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
1341 inline encryption hardware doesn't have the needed crypto capabilities
1343 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1346 protected by a raw key rather than a hardware-wrapped key.)
1350 inline encryption hardware that supports that data unit size.
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
1356 encrypted/decrypted by the inline encryption hardware and therefore
1358 more information about hardware-wrapped keys, see below.
1360 Hardware-wrapped keys
1361 ---------------------
1363 fscrypt supports using *hardware-wrapped keys* when the inline
1364 encryption hardware supports it. Such keys are only present in kernel
1366 (decrypted) by the inline encryption hardware and are temporally bound
1371 encryption hardware, e.g. filenames encryption.
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
1390 key are tied to the system's inline encryption hardware. Therefore
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
1406 directly into a keyslot but rather unwraps it (using the hardware's
1416 key from a hardware-wrapped key, fscrypt asks the inline encryption
1417 hardware to derive a cryptographically isolated "software secret" from
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
1434 encryption hardware must be present. However, a software fallback
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 -----------------
1498 inline encryption hardware will encrypt/decrypt the file contents.
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