Lines Matching +full:as +full:- +full:is
2 Filesystem-level encryption (fscrypt)
8 fscrypt is a library which filesystems can hook into to support
11 Note: "fscrypt" in this document refers to the kernel-level portion,
12 implemented in ``fs/crypto/``, as opposed to the userspace tool
14 covers the kernel-level portion. For command-line examples of how to
16 <https://github.com/google/fscrypt>`_. Also, it is recommended to use
17 the fscrypt userspace tool, or other existing userspace tools such as
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.
33 Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated
34 directly into supported filesystems --- currently ext4, F2FS, UBIFS,
38 line with unencrypted files. Similarly, half as many dentries and
44 fscrypt does not support encrypting files in-place. Instead, it
45 supports marking an empty directory as encrypted. Then, after
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.
65 fscrypt is not guaranteed to protect confidentiality or authenticity
66 if an attacker is able to manipulate the filesystem offline prior to
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
91 system. Instead, existing access control mechanisms such as file mode
94 (For the reasoning behind this, understand that while the key is
96 system itself, is *not* protected by the mathematical properties 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.
124 encrypted files and directories before removing a master key, as
125 well as kill any processes whose working directory is in an affected
128 - The kernel cannot magically wipe copies of the master key(s) that
129 userspace might have as well. Therefore, userspace must wipe all
130 copies of the master key(s) it makes as well; normally this should
134 follow other security precautions such as mlock()ing memory
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.
168 this reason among others, it is recommended to use v2 encryption
175 -----------
177 Each encrypted directory tree is protected by a *master key*. Master
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
182 stricter requirement applies if the key is used by a v1 encryption
183 policy and AES-256-XTS is used; such keys must be 64 bytes.
192 **must not** directly use a password as a master key, zero-pad a
194 if userspace makes any such error, as the cryptographic proofs and
200 therefore, if userspace derives the key from a low-entropy secret such
201 as a passphrase, it is critical that a KDF designed for this purpose
202 be used, such as scrypt, PBKDF2, or Argon2.
205 -----------------------
208 encryption directly. Instead, they are only used as input to a KDF
212 the key is used for v1 encryption policies or for v2 encryption
214 encryption policies. (No real-world attack is currently known on this
218 For v1 encryption policies, the KDF only supports deriving per-file
220 AES-128-ECB, using the file's 16-byte nonce as the AES key. The
221 resulting ciphertext is used as the derived key. If the ciphertext is
222 longer than needed, then it is truncated to the needed length.
224 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
225 passed as the "input keying material", no salt is used, and a distinct
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
233 HKDF is more flexible, is nonreversible, and evenly distributes
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
244 encrypted inode (regular file, directory, or symlink) is created,
245 fscrypt randomly generates a 16-byte nonce and stores it in the
246 inode's encryption xattr. Then, it uses a KDF (as described in `Key
251 require larger xattrs which would be less likely to fit in-line in the
254 there is no requirement to support unlocking a file with multiple
256 the master keys may be wrapped in userspace, e.g. as is done by the
260 -------------------
262 The Adiantum encryption mode (see `Encryption modes and usage`_) is
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.
269 "direct key" configuration is supported. When the user has enabled
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 -----------------------
286 When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy,
294 This format is optimized for use with inline encryption hardware
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 data
304 unit index mod 2^32 to produce a 32-bit IV.
306 This format is optimized for use with inline encryption hardware
313 ---------------
315 For master keys used for v2 encryption policies, a unique 16-byte "key
316 identifier" is also derived using the KDF. This value is stored in
317 the clear, since it is needed to reliably identify the key itself.
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.
362 It is also the only option that is *guaranteed* to always be supported
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
374 Adiantum is recommended on systems where AES is too slow due to lack
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
377 the work is done by XChaCha12, which is much faster than AES when AES
378 acceleration is unavailable. For more information about Adiantum, see
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
383 accelerator such as CAAM or CESA that does not support XTS.
387 - (SM4-XTS, SM4-CBC-CTS)
390 receive limited security review compared to the usual choices such as
391 AES and ChaCha. They also don't bring much new to the table. It is
392 suggested to only use these ciphers where their use is mandated.
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
403 requires extra kconfig options as well.
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
447 acceleration is recommended:
449 - SHA-512
450 - Recommended:
451 - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
452 - x86: CONFIG_CRYPTO_SHA512_SSSE3
455 -------------------
457 For contents encryption, each file's contents is divided into "data
458 units". Each data unit is encrypted independently. The IV for each
459 data unit incorporates the zero-based index of the data unit within
460 the file. This ensures that each data unit within a file is encrypted
461 differently, which is essential to prevent leaking information.
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
477 data node" is treated as a crypto data unit. Each contains variable
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.
481 In the case of compression + encryption, the compressed data is
482 encrypted. UBIFS compression works as described above. f2fs
485 Therefore a f2fs-compressed file still uses fixed-size data units, and
486 it is encrypted in a similar way to a file containing holes.
488 As mentioned in `Key hierarchy`_, the default encryption setting uses
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
492 kind of file identifier is incorporated into the IVs as follows:
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
503 and added to the data unit index. The resulting value is truncated
504 to 32 bits and placed in bits 0-31 of the IV. This setting is only
507 The byte order of the IV is always little endian.
510 ESSIV layer is automatically included. In this case, before the IV is
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 --------------------
517 For filenames, each full filename is encrypted at once. Because of
519 filenames of up to 255 bytes, the same IV is used for every filename
525 Thus, IV reuse is limited to within a single directory.
527 With CBC-CTS, the IV reuse means that when the plaintext filenames share a
528 common prefix at least as long as the cipher block size (16 bytes for AES), the
529 corresponding encrypted filenames will also share a common prefix. This is
530 undesirable. Adiantum and HCTR2 do not have this weakness, as they are
531 wide-block encryption modes.
534 >= 16 bytes; cipher block alignment is not required. However,
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
540 entries consume slightly more space. Note that since NUL (``\0``) is
545 encrypted in the same way as filenames in directory entries, except
546 that IV reuse is not a problem as each symlink has its own inode.
552 ----------------------------
560 struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
586 This structure must be initialized as follows:
588 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
589 struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if
590 struct fscrypt_policy_v2 is used. (Note: we refer to the original
591 policy version as "v1", though its version code is really 0.)
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,
625 or 0 to select the default data unit size. The data unit size is
628 underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
637 The main use case for ``log2_data_unit_size`` is for selecting a
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
655 FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added
659 replaced with ``master_key_identifier``, which is longer and cannot
663 be used as the ``master_key_identifier`` in
666 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
667 verifies that the file is an empty directory. If so, the specified
668 encryption policy is assigned to the directory, turning it into an
670 corresponding master key as described in `Adding keys`_, all regular
673 The filenames in the directory's entries will be encrypted as well.
675 Alternatively, if the file is already encrypted, then
681 When a v2 encryption policy is assigned to a directory, it is also
684 (This is needed to prevent a user from encrypting their data with
686 FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new
691 encrypted, even if it is empty. Users who want to encrypt an entire
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
704 flag enabled (casefolding is incompatible with v1 policies).
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`_
732 The extended (_EX) version of the ioctl is more general and is
734 original ioctl is available. Applications should try the extended
745 defined as follows::
759 On success, the policy struct is returned in ``policy``, and its
760 actual size is returned in ``policy_size``. ``policy.version`` should
762 version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
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,
770 or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
772 - ``EOPNOTSUPP``: the kernel was not configured with encryption
775 - ``EOVERFLOW``: the file is encrypted and uses a recognized
779 Note: if you only need to know whether a file is encrypted or not, on
780 most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
794 The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
796 FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
799 Getting the per-filesystem salt
800 -------------------------------
802 Some filesystems, such as ext4 and F2FS, also support the deprecated
804 generated 16-byte value stored in the filesystem superblock. This
805 value is intended to used as a salt when deriving an encryption key
806 from a passphrase or other low-entropy user credential.
808 FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to
812 ---------------------------------
814 Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported.
815 On encrypted files and directories it gets the inode's 16-byte nonce.
819 encryption is being done correctly. It is not needed for normal use
823 -----------
832 but using the filesystem's root directory is recommended. It takes in
833 a pointer to struct fscrypt_add_key_arg, defined as follows::
863 as follows:
865 - If the key is being added for use by v1 encryption policies, then
873 Alternatively, if the key is being added for use by v2 encryption
875 FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is
879 added is limited by the user's quota for the keyrings service (see
882 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
883 Alternatively, if ``key_id`` is nonzero, this field must be 0, since
884 in that case the size is implied by the specified Linux keyring key.
886 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
887 field. Otherwise ``key_id`` is the ID of a Linux keyring key of
888 type "fscrypt-provisioning" whose payload is
891 Since ``raw`` is variable-length, the total size of this key's
897 The support for specifying a Linux keyring key is intended mainly to
898 allow re-adding keys after a filesystem is unmounted and re-mounted,
901 - ``raw`` is a variable-length field which must contain the actual
902 key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is
903 nonzero, then this field is unused.
907 removed by that user --- or by "root", if they use
916 must still be provided, as a proof of knowledge).
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
945 session keyring, or to a user keyring if the user keyring is linked
948 This method is deprecated (and not supported for v2 encryption
951 so for removing a key a workaround such as keyctl_unlink() in
955 be in plaintext form or in ciphertext form) is global. This mismatch
956 has caused much confusion as well as real problems when processes
957 running under different UIDs, such as a ``sudo`` command, need to
960 Nevertheless, to add a key to one of the process-subscribed keyrings,
965 followed by the 16-character lower case hex representation of the
977 ``mode`` is ignored; just set it to 0. The actual key is provided in
978 ``raw`` with ``size`` indicating its size in bytes. That is, 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
987 -------------
992 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
993 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
996 or removed by non-root users.
999 process-subscribed keyrings mechanism.
1011 filesystem, but using the filesystem's root directory is recommended.
1013 as follows::
1023 This structure must be zeroed, then initialized as follows:
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,
1040 Only after all claims are removed is the key really removed.
1044 FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if
1047 once *both* are removed is the key really removed. (Think of it like
1052 lock files that are still in-use, so this ioctl is expected to be used
1061 of these cases, ``removal_status_flags`` is filled in with the
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
1088 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
1092 removed, no matter how many users have added it. This difference is
1093 only meaningful if non-root users are adding and removing keys.
1100 ------------------
1107 the target filesystem, but using the filesystem's root directory is
1109 struct fscrypt_get_key_status_arg, defined as follows::
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
1137 On success, 0 is returned and the kernel fills in the output fields:
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
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 ---
1183 after all, the encryption is intended to be transparent. However,
1186 - Unencrypted files, or files encrypted with a different encryption
1194 with the `mv` program, is implemented in userspace by a copy
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
1223 Note that mmap *is* supported. This is possible because the pagecache
1227 ---------------
1233 - File metadata may be read, e.g. using stat().
1235 - Directories may be listed, in which case the filenames will be
1237 current encoding algorithm is described in `Filename hashing and
1238 encoding`_. The algorithm is subject to change, but it is
1246 - Files may be deleted. That is, nondirectory files may be deleted
1247 with unlink() as usual, and empty directories may be deleted with
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
1257 regular file operations that require a file descriptor, such as
1266 It is not currently possible to backup and restore encrypted files
1275 (recursively) will inherit that encryption policy. Special files ---
1276 that is, named pipes, device nodes, and UNIX domain sockets --- will
1279 Except for those special files, it is forbidden to have unencrypted
1282 an encrypted directory will fail with EXDEV. This is also enforced
1283 during ->lookup() to provide limited protection against offline
1285 where applications may later write sensitive data. It is recommended
1287 this by validating all top-level encryption policies prior to access.
1302 encryption hardware* that can encrypt/decrypt data while it is on its
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
1325 Currently fscrypt always uses the filesystem block size (which is
1326 usually 4096 bytes) as the data unit size. Therefore, it can only use
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
1343 is also available. For details, see `Inline encryption support`_.
1346 This means that the file position the I/O is targeting, the lengths
1351 If either of the above conditions is not met, then direct I/O on the
1358 ------------------
1360 An encryption policy is represented on-disk by
1361 struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to
1364 exposed by the xattr-related system calls such as getxattr() and
1368 directory.) These structs are defined as follows::
1394 The context structs contain the same information as the corresponding
1396 context structs also contain a nonce. The nonce is randomly generated
1397 by the kernel and is used as KDF input or as a tweak to cause
1398 different files to be encrypted differently; see `Per-file encryption
1402 -----------------
1404 When inline encryption is used, filesystems just need to associate
1409 the file contents themselves, as described below:
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
1420 buffer. Some filesystems, such as UBIFS, already use temporary
1421 buffers regardless of encryption. Other filesystems, such as ext4 and
1425 -----------------------------
1428 directories. An indexed directory is organized as a tree keyed by
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
1461 without the key is subject to change in the future. It is only meant
1462 as a way to temporarily present valid filenames so that commands like
1463 ``rm -r`` work as expected on encrypted directories.
1468 To test fscrypt, use xfstests, which is Linux's de facto standard
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
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