Lines Matching +full:status +full:- +full:sizes
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
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
144 - Secret keys might still exist in CPU registers or in other places
153 - There is no verification that the provided master key is correct.
155 with another user's encrypted files to which they have read-only
159 meaning of "read-only access".
161 - A compromise of a per-file key also compromises the master key from
164 - Non-root users cannot securely remove encryption keys.
174 -----------
179 encryption modes being used. For example, if any AES-256 mode is
182 policy and AES-256-XTS is used; such keys must be 64 bytes.
191 **must not** directly use a password as a master key, zero-pad a
199 therefore, if userspace derives the key from a low-entropy secret such
204 -----------------------
213 encryption policies. (No real-world attack is currently known on this
217 For v1 encryption policies, the KDF only supports deriving per-file
219 AES-128-ECB, using the file's 16-byte nonce as the AES key. The
223 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
225 "application-specific information string" is used for each distinct
226 key to be derived. For example, when a per-file encryption key is
227 derived, the application-specific information string is the file's
231 HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
234 used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
236 Per-file encryption keys
237 ------------------------
242 cases, fscrypt does this by deriving per-file keys. When a new
244 fscrypt randomly generates a 16-byte nonce and stores it in the
250 require larger xattrs which would be less likely to fit in-line in the
259 -------------------
263 long IVs --- long enough to hold both an 8-byte data unit index and a
264 16-byte per-file nonce. Also, the overhead of each Adiantum key is
265 greater than that of an AES-256-XTS key.
270 per-file encryption keys are not used. Instead, whenever any data
271 (contents or filenames) is encrypted, the file's 16-byte nonce is
274 - For v1 encryption policies, the encryption is done directly with the
278 - For v2 encryption policies, the encryption is done with a per-mode
283 -----------------------
298 -----------------------
301 IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
303 unit index mod 2^32 to produce a 32-bit IV.
312 ---------------
314 For master keys used for v2 encryption policies, a unique 16-byte "key
319 ------------
321 For directories that are indexed using a secret-keyed dirhash over the
322 plaintext filenames, the KDF is also used to derive a 128-bit
323 SipHash-2-4 key per directory in order to hash filenames. This works
324 just like deriving a per-file encryption key, except that a different
325 KDF context is used. Currently, only casefolded ("case-insensitive")
336 ---------------
340 - AES-256-XTS for contents and AES-256-CBC-CTS for filenames
341 - AES-256-XTS for contents and AES-256-HCTR2 for filenames
342 - Adiantum for both contents and filenames
343 - AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames
344 - SM4-XTS for contents and SM4-CBC-CTS for filenames
346 Note: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS.
347 So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.
353 `CBC-ESSIV mode
354 <https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(…
355 or a wide-block cipher. Filenames encryption uses a
356 block cipher in `CBC-CTS mode
357 <https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block
360 The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default.
364 The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that
365 upgrades the filenames encryption to use a wide-block cipher. (A
366 *wide-block cipher*, also called a tweakable super-pseudorandom
368 entire result.) As described in `Filenames encryption`_, a wide-block
369 cipher is the ideal mode for the problem domain, though CBC-CTS is the
374 of hardware acceleration for AES. Adiantum is a wide-block cipher
375 that uses XChaCha12 and AES-256 as its underlying components. Most of
380 The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair was added to try to
382 in the CPU but do have a non-inline crypto engine such as CAAM or CESA
383 that supports AES-CBC (and not AES-XTS). This is deprecated. It has
389 - (SM4-XTS, SM4-CBC-CTS)
397 ---------------------
400 only the basic support from the crypto API needed to use AES-256-XTS
401 and AES-256-CBC-CTS encryption. For optimal performance, it is
402 strongly recommended to also enable any available platform-specific
404 wish to use. Support for any "non-default" encryption modes typically
415 - AES-256-XTS and AES-256-CBC-CTS
416 - Recommended:
417 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
418 - x86: CONFIG_CRYPTO_AES_NI_INTEL
420 - AES-256-HCTR2
421 - Mandatory:
422 - CONFIG_CRYPTO_HCTR2
423 - Recommended:
424 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
425 - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE
426 - x86: CONFIG_CRYPTO_AES_NI_INTEL
427 - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI
429 - Adiantum
430 - Mandatory:
431 - CONFIG_CRYPTO_ADIANTUM
432 - Recommended:
433 - arm32: CONFIG_CRYPTO_CHACHA20_NEON
434 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
435 - arm64: CONFIG_CRYPTO_CHACHA20_NEON
436 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
437 - x86: CONFIG_CRYPTO_CHACHA20_X86_64
438 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
439 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
441 - AES-128-CBC-ESSIV and AES-128-CBC-CTS:
442 - Mandatory:
443 - CONFIG_CRYPTO_ESSIV
444 - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
445 - Recommended:
446 - AES-CBC acceleration
448 fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512
451 - SHA-512
452 - Recommended:
453 - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
454 - x86: CONFIG_CRYPTO_SHA512_SSSE3
457 -------------------
461 data unit incorporates the zero-based index of the data unit within
469 There are two cases for the sizes of the data units:
471 * Fixed-size data units. This is how all filesystems other than UBIFS
473 is zero-padded if needed. By default, the data unit size is equal
475 a sub-block data unit size via the ``log2_data_unit_size`` field of
478 * Variable-size data units. This is what UBIFS does. Each "UBIFS
480 length, possibly compressed data, zero-padded to the next 16-byte
481 boundary. Users cannot select a sub-block data unit size on UBIFS.
487 Therefore a f2fs-compressed file still uses fixed-size data units, and
491 per-file keys. In this case, the IV for each data unit is simply the
493 encryption setting that does not use per-file keys. For these, some
496 - With `DIRECT_KEY policies`_, the data unit index is placed in bits
497 0-63 of the IV, and the file's nonce is placed in bits 64-191.
499 - With `IV_INO_LBLK_64 policies`_, the data unit index is placed in
500 bits 0-31 of the IV, and the file's inode number is placed in bits
501 32-63. This setting is only allowed when data unit indices and
504 - With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed
506 to 32 bits and placed in bits 0-31 of the IV. This setting is only
513 passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
514 key is the SHA-256 hash of the file's contents encryption key.
517 --------------------
529 With CBC-CTS, the IV reuse means that when the plaintext filenames share a
533 wide-block encryption modes.
537 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
539 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
540 16, or 32-byte boundary (configurable). 32 is recommended since this
554 ----------------------------
590 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
596 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
609 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
611 - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
614 - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
615 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
617 - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
626 - ``log2_data_unit_size`` is the log2 of the data unit size in bytes,
630 underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
642 smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be
643 useful for checking which data unit sizes are supported by a
649 - For v2 encryption policies, ``__reserved`` must be zeroed.
651 - For v1 encryption policies, ``master_key_descriptor`` specifies how
655 ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
694 filesystem with one key should consider using dm-crypt instead.
698 - ``EACCES``: the file is not owned by the process's uid, nor does the
701 - ``EEXIST``: the file is already encrypted with an encryption policy
703 - ``EINVAL``: an invalid encryption policy was specified (invalid
707 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
711 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
713 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
714 - ``ENOTTY``: this type of filesystem does not implement encryption
715 - ``EOPNOTSUPP``: the kernel was not configured with encryption
720 feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
722 - ``EPERM``: this directory may not be encrypted, e.g. because it is
724 - ``EROFS``: the filesystem is readonly
727 ----------------------------
731 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
732 - `FS_IOC_GET_ENCRYPTION_POLICY`_
768 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
770 - ``ENODATA``: the file is not encrypted
771 - ``ENOTTY``: this type of filesystem does not implement encryption,
774 - ``EOPNOTSUPP``: the kernel was not configured with encryption
777 - ``EOVERFLOW``: the file is encrypted and uses a recognized
801 Getting the per-filesystem salt
802 -------------------------------
806 generated 16-byte value stored in the filesystem superblock. This
808 from a passphrase or other low-entropy user credential.
814 ---------------------------------
817 On encrypted files and directories it gets the inode's 16-byte nonce.
825 -----------
867 - If the key is being added for use by v1 encryption policies, then
884 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
888 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
890 type "fscrypt-provisioning" whose payload is
893 Since ``raw`` is variable-length, the total size of this key's
900 allow re-adding keys after a filesystem is unmounted and re-mounted,
903 - ``raw`` is a variable-length field which must contain the actual
909 removed by that user --- or by "root", if they use
925 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
929 - ``EDQUOT``: the key quota for this user would be exceeded by adding
931 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
933 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
935 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
937 - ``ENOTTY``: this type of filesystem does not implement encryption
938 - ``EOPNOTSUPP``: the kernel was not configured with encryption
946 provided by adding it to a process-subscribed keyring, e.g. to a
956 locked/unlocked status of encrypted files (i.e. whether they appear to
962 Nevertheless, to add a key to one of the process-subscribed keyrings,
967 followed by the 16-character lower case hex representation of the
981 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
984 with a filesystem-specific prefix such as "ext4:". However, the
985 filesystem-specific prefixes are deprecated and should not be used in
989 -------------
994 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
995 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
998 or removed by non-root users.
1001 process-subscribed keyrings mechanism.
1027 - The key to remove is specified by ``key_spec``:
1029 - To remove a key used by v1 encryption policies, set
1035 - To remove a key used by v2 encryption policies, set
1039 For v2 policy keys, this ioctl is usable by non-root users. However,
1054 lock files that are still in-use, so this ioctl is expected to be used
1064 following informational status flags:
1066 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
1067 are still in-use. Not guaranteed to be set in the case where only
1069 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
1074 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
1077 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1078 - ``ENOKEY``: the key object was not found at all, i.e. it was never
1082 - ``ENOTTY``: this type of filesystem does not implement encryption
1083 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1095 only meaningful if non-root users are adding and removing keys.
1101 Getting key status
1102 ------------------
1107 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
1122 __u32 status;
1131 - To get the status of a key for v1 encryption policies, set
1135 - To get the status of a key for v2 encryption policies, set
1141 - ``status`` indicates whether the key is absent, present, or
1145 status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.
1147 - ``status_flags`` can contain the following flags:
1149 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1153 - ``user_count`` specifies the number of users who have added the key.
1159 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1160 - ``ENOTTY``: this type of filesystem does not implement encryption
1161 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1170 FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
1171 the filesystem-level keyring, i.e. the keyring managed by
1173 cannot get the status of a key that has only been added for use by v1
1175 process-subscribed keyrings.
1181 ------------
1184 symlinks behave very similarly to their unencrypted counterparts ---
1188 - Unencrypted files, or files encrypted with a different encryption
1203 - Direct I/O is supported on encrypted files only under some
1206 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1210 - Online defragmentation of encrypted files is not supported. The
1214 - The ext4 filesystem does not support data journaling with encrypted
1217 - DAX (Direct Access) is not supported on encrypted files.
1219 - The maximum length of an encrypted symlink is 2 bytes shorter than
1229 ---------------
1235 - File metadata may be read, e.g. using stat().
1237 - Directories may be listed, in which case the filenames will be
1248 - Files may be deleted. That is, nondirectory files may be deleted
1250 rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
1253 - Symlink targets may be read and followed, but they will be presented
1277 (recursively) will inherit that encryption policy. Special files ---
1278 that is, named pipes, device nodes, and UNIX domain sockets --- will
1285 during ->lookup() to provide limited protection against offline
1289 this by validating all top-level encryption policies prior to access.
1297 extensions to the block layer called *blk-crypto*. blk-crypto allows
1299 specify how the data will be encrypted or decrypted in-line. For more
1300 information about blk-crypto, see
1301 :ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1304 blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1314 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1323 the on-disk format, so users may freely switch back and forth between
1334 the filesystem must be mounted with ``-o inlinecrypt`` and inline
1351 ------------------
1353 An encryption policy is represented on-disk by
1357 exposed by the xattr-related system calls such as getxattr() and
1391 different files to be encrypted differently; see `Per-file encryption
1395 -----------------
1404 For the read path (->read_folio()) of regular files, filesystems can
1405 read the ciphertext into the page cache and decrypt it in-place. The
1409 For the write path (->writepage()) of regular files, filesystems
1410 cannot encrypt data in-place in the page cache, since the cached
1418 -----------------------------
1422 filename hashes. When a ->lookup() is requested, the filesystem
1432 i.e. the bytes actually stored on-disk in the directory entries. When
1433 asked to do a ->lookup() with the key, the filesystem just encrypts
1434 the user-supplied name to get the ciphertext.
1438 filenames. Therefore, readdir() must base64url-encode the ciphertext
1439 for presentation. For most filenames, this works fine; on ->lookup(),
1440 the filesystem just base64url-decodes the user-supplied name to get
1447 filesystem-specific hash(es) needed for directory lookups. This
1449 the filename given in ->lookup() back to a particular directory entry
1456 ``rm -r`` work as expected on encrypted directories.
1466 f2fs encryption using `kvm-xfstests
1467 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1469 kvm-xfstests -c ext4,f2fs -g encrypt
1470 kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1473 a separate command, and it takes some time for kvm-xfstests to set up
1476 kvm-xfstests -c ubifs -g encrypt
1478 No tests should fail. However, tests that use non-default encryption
1489 kvm-xfstests, use the "encrypt" filesystem configuration::
1491 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1492 kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1494 Because this runs many more tests than "-g encrypt" does, it takes
1495 much longer to run; so also consider using `gce-xfstests
1496 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1497 instead of kvm-xfstests::
1499 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1500 gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt