Documentation/filesystems/fscrypt.rst

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
21 using the kernel's API directly.  Using existing tools reduces the
23 completeness this documentation covers the kernel's API anyway.)
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
97 encryption but rather only by the correctness of the kernel.
98 Therefore, any encryption-specific access control checks would merely
99 be enforced by kernel *code* and therefore would be largely redundant
102 Kernel memory compromise
106 memory, e.g. by mounting a physical attack or by exploiting a kernel
110 However, fscrypt allows encryption keys to be removed from the kernel,
114 FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
115 encryption key from kernel memory.  If it does so, it will also try to
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
128 - The kernel cannot magically wipe copies of the master key(s) that
130   copies of the master key(s) it makes as well; normally this should
137 - In general, decrypted contents and filenames in the kernel VFS
141   your kernel command line.  However, this has a performance cost.
143 - Secret keys might still exist in CPU registers, in crypto
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.
173 Master Keys
174 -----------
176 Each encrypted directory tree is protected by a *master key*.  Master
179 encryption modes being used.  For example, if any AES-256 mode is
180 used, the master key must be at least 256 bits, i.e. 32 bytes.  A
182 policy and AES-256-XTS is used; such keys must be 64 bytes.
185 appropriate master key.  There can be any number of master keys, each
189 Master keys must be real cryptographic keys, i.e. indistinguishable
191 **must not** directly use a password as a master key, zero-pad a
196 Instead, users should generate master keys either using a
198 (Key Derivation Function).  The kernel does not do any key stretching;
199 therefore, if userspace derives the key from a low-entropy secret such
204 -----------------------
206 With one exception, fscrypt never uses the master key(s) for
210 The KDF used for a particular master key differs depending on whether
213 encryption policies.  (No real-world attack is currently known on this
217 For v1 encryption policies, the KDF only supports deriving per-file
218 encryption keys.  It works by encrypting the master key with
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
233 entropy from the master key.  HKDF is also standardized and widely
234 used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
236 Per-file encryption keys
237 ------------------------
239 Since each master key can protect many files, it is necessary to
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
246 derivation function`_) to derive the file's key from the master key
250 require larger xattrs which would be less likely to fit in-line in the
254 alternative master keys or to support rotating master keys.  Instead,
255 the master keys may be wrapped in userspace, e.g. as is done by 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
275   master key.  Because of this, users **must not** use the same master
278 - For v2 encryption policies, the encryption is done with a per-mode
279   key derived using the KDF.  Users may use the same master key for
283 -----------------------
286 the encryption keys are derived from the master key, encryption mode
288 protected by the same master key sharing a single contents encryption
298 -----------------------
301 IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
302 SipHash key is derived from the master key) and added to the file data
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.
362 if the kernel supports fscrypt at all; see `Kernel config options`_.
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 exists only to support
381 systems whose only form of AES acceleration is an off-CPU crypto
386 - (SM4-XTS, SM4-CBC-CTS)
393 Kernel config options
394 ---------------------
397 only the basic support from the crypto API needed to use AES-256-XTS
398 and AES-256-CBC-CTS encryption.  For optimal performance, it is
399 strongly recommended to also enable any available platform-specific
401 wish to use.  Support for any "non-default" encryption modes typically
408 kernel crypto API (see `Inline encryption support`_); in that case,
409 the file contents mode doesn't need to supported in the kernel crypto
412 - AES-256-XTS and AES-256-CBC-CTS
413     - Recommended:
414         - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
415         - x86: CONFIG_CRYPTO_AES_NI_INTEL
417 - AES-256-HCTR2
418     - Mandatory:
419         - CONFIG_CRYPTO_HCTR2
420     - Recommended:
421         - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK
422         - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE
423         - x86: CONFIG_CRYPTO_AES_NI_INTEL
424         - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI
426 - Adiantum
427     - Mandatory:
428         - CONFIG_CRYPTO_ADIANTUM
429     - Recommended:
430         - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON
431         - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON
432         - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2
433         - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2
435 - AES-128-CBC-ESSIV and AES-128-CBC-CTS:
436     - Mandatory:
437         - CONFIG_CRYPTO_ESSIV
438         - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation
439     - Recommended:
440         - AES-CBC acceleration
442 fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512
445 - SHA-512
446     - Recommended:
447         - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE
448         - x86: CONFIG_CRYPTO_SHA512_SSSE3
451 -------------------
455 data unit incorporates the zero-based index of the data unit within
465 * Fixed-size data units.  This is how all filesystems other than UBIFS
467   is zero-padded if needed.  By default, the data unit size is equal
469   a sub-block data unit size via the ``log2_data_unit_size`` field of
472 * Variable-size data units.  This is what UBIFS does.  Each "UBIFS
474   length, possibly compressed data, zero-padded to the next 16-byte
475   boundary.  Users cannot select a sub-block data unit size on UBIFS.
481 Therefore a f2fs-compressed file still uses fixed-size data units, and
485 per-file keys.  In this case, the IV for each data unit is simply the
487 encryption setting that does not use per-file keys.  For these, some
490 - With `DIRECT_KEY policies`_, the data unit index is placed in bits
491   0-63 of the IV, and the file's nonce is placed in bits 64-191.
493 - With `IV_INO_LBLK_64 policies`_, the data unit index is placed in
494   bits 0-31 of the IV, and the file's inode number is placed in bits
495   32-63.  This setting is only allowed when data unit indices and
498 - With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed
500   to 32 bits and placed in bits 0-31 of the IV.  This setting is only
507 passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256
508 key is the SHA-256 hash of the file's contents encryption key.
511 --------------------
523 With CBC-CTS, the IV reuse means that when the plaintext filenames share a
527 wide-block encryption modes.
531 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
533 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
534 16, or 32-byte boundary (configurable).  32 is recommended since this
548 ----------------------------
584 - ``version`` must be FSCRYPT_POLICY_V1 (0) if
590 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
603 - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
605   - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
608   - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
609   - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
611   - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
620 - ``log2_data_unit_size`` is the log2 of the data unit size in bytes,
624   underlying encryption algorithm (such as AES-256-XTS) in 4096-byte
643 - For v2 encryption policies, ``__reserved`` must be zeroed.
645 - For v1 encryption policies, ``master_key_descriptor`` specifies how
646   to find the master key in a keyring; see `Adding keys`_.  It is up
648   master key.  The e4crypt and fscrypt tools use the first 8 bytes of
649   ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
650   required.  Also, the master key need not be in the keyring yet when
658   the kernel returned in the struct fscrypt_add_key_arg must
666 corresponding master key as described in `Adding keys`_, all regular
688 filesystem with one key should consider using dm-crypt instead.
692 - ``EACCES``: the file is not owned by the process's uid, nor does the
695 - ``EEXIST``: the file is already encrypted with an encryption policy
697 - ``EINVAL``: an invalid encryption policy was specified (invalid
701 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
705 - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
707 - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
708 - ``ENOTTY``: this type of filesystem does not implement encryption
709 - ``EOPNOTSUPP``: the kernel was not configured with encryption
713   kernel config, and the superblock must have had the "encrypt"
714   feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
716 - ``EPERM``: this directory may not be encrypted, e.g. because it is
718 - ``EROFS``: the filesystem is readonly
721 ----------------------------
725 - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
726 - `FS_IOC_GET_ENCRYPTION_POLICY`_
762 - ``EINVAL``: the file is encrypted, but it uses an unrecognized
764 - ``ENODATA``: the file is not encrypted
765 - ``ENOTTY``: this type of filesystem does not implement encryption,
766   or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
768 - ``EOPNOTSUPP``: the kernel was not configured with encryption
771 - ``EOVERFLOW``: the file is encrypted and uses a recognized
795 Getting the per-filesystem salt
796 -------------------------------
800 generated 16-byte value stored in the filesystem superblock.  This
802 from a passphrase or other low-entropy user credential.
808 ---------------------------------
811 On encrypted files and directories it gets the inode's 16-byte nonce.
819 -----------
824 The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
861 - If the key is being added for use by v1 encryption policies, then
872   an *output* field which the kernel fills in with a cryptographic
878 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
882 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
884   type "fscrypt-provisioning" whose payload is
887   Since ``raw`` is variable-length, the total size of this key's
894   allow re-adding keys after a filesystem is unmounted and re-mounted,
897 - ``raw`` is a variable-length field which must contain the actual
901 For v2 policy keys, the kernel keeps track of which user (identified
903 removed by that user --- or by "root", if they use
919 - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
923 - ``EDQUOT``: the key quota for this user would be exceeded by adding
925 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
927 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
929 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
931 - ``ENOTTY``: this type of filesystem does not implement encryption
932 - ``EOPNOTSUPP``: the kernel was not configured with encryption
939 For v1 encryption policies, a master encryption key can also be
940 provided by adding it to a process-subscribed keyring, e.g. to a
956 Nevertheless, to add a key to one of the process-subscribed keyrings,
959 "logon"; keys of this type are kept in kernel memory and cannot be
961 followed by the 16-character lower case hex representation of the
975 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
978 with a filesystem-specific prefix such as "ext4:".  However, the
979 filesystem-specific prefixes are deprecated and should not be used in
983 -------------
988 - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
989 - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
992 or removed by non-root users.
995 process-subscribed keyrings mechanism.
997 Before using these ioctls, read the `Kernel memory compromise`_
1004 The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
1021 - The key to remove is specified by ``key_spec``:
1023     - To remove a key used by v1 encryption policies, set
1029     - To remove a key used by v2 encryption policies, set
1033 For v2 policy keys, this ioctl is usable by non-root users.  However,
1048 lock files that are still in-use, so this ioctl is expected to be used
1060 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
1061   are still in-use.  Not guaranteed to be set in the case where only
1063 - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
1068 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
1071 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1072 - ``ENOKEY``: the key object was not found at all, i.e. it was never
1076 - ``ENOTTY``: this type of filesystem does not implement encryption
1077 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1089 only meaningful if non-root users are adding and removing keys.
1096 ------------------
1102 master encryption key.  It can be executed on any file or directory on
1125     - To get the status of a key for v1 encryption policies, set
1129     - To get the status of a key for v2 encryption policies, set
1133 On success, 0 is returned and the kernel fills in the output fields:
1135 - ``status`` indicates whether the key is absent, present, or
1141 - ``status_flags`` can contain the following flags:
1143     - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1147 - ``user_count`` specifies the number of users who have added the key.
1153 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1154 - ``ENOTTY``: this type of filesystem does not implement encryption
1155 - ``EOPNOTSUPP``: the kernel was not configured with encryption
1165 the filesystem-level keyring, i.e. the keyring managed by
1169 process-subscribed keyrings.
1175 ------------
1178 symlinks behave very similarly to their unencrypted counterparts ---
1182 - Unencrypted files, or files encrypted with a different encryption
1197 - Direct I/O is supported on encrypted files only under some
1200 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1204 - Online defragmentation of encrypted files is not supported.  The
1208 - The ext4 filesystem does not support data journaling with encrypted
1211 - DAX (Direct Access) is not supported on encrypted files.
1213 - The maximum length of an encrypted symlink is 2 bytes shorter than
1223 ---------------
1229 - File metadata may be read, e.g. using stat().
1231 - Directories may be listed, in which case the filenames will be
1242 - Files may be deleted.  That is, nondirectory files may be deleted
1244   rmdir() as usual.  Therefore, ``rm`` and ``rm -r`` will work as
1247 - Symlink targets may be read and followed, but they will be presented
1271 (recursively) will inherit that encryption policy.  Special files ---
1272 that is, named pipes, device nodes, and UNIX domain sockets --- will
1279 during ->lookup() to provide limited protection against offline
1283 this by validating all top-level encryption policies prior to access.
1288 By default, fscrypt uses the kernel crypto API for all cryptographic
1290 itself).  The kernel crypto API supports hardware crypto accelerators,
1300 through a set of extensions to the block layer called *blk-crypto*.
1301 blk-crypto allows filesystems to attach encryption contexts to bios
1303 in-line.  For more information about blk-crypto, see
1304 :ref:`Documentation/block/inline-encryption.rst <inline_encryption>`.
1307 blk-crypto instead of the kernel crypto API to encrypt/decrypt file
1309 the kernel configuration, and specify the "inlinecrypt" mount option
1314 still fall back to using the kernel crypto API on files where the
1317 and where blk-crypto-fallback is unusable.  (For blk-crypto-fallback
1318 to be usable, it must be enabled in the kernel configuration with
1326 the on-disk format, so users may freely switch back and forth between
1337   the filesystem must be mounted with ``-o inlinecrypt`` and inline
1354 ------------------
1356 An encryption policy is represented on-disk by
1360 exposed by the xattr-related system calls such as getxattr() and
1393 by the kernel and is used as KDF input or as a tweak to cause
1394 different files to be encrypted differently; see `Per-file encryption
1398 -----------------
1407 For the read path (->read_folio()) of regular files, filesystems can
1408 read the ciphertext into the page cache and decrypt it in-place.  The
1412 For the write path (->writepage()) of regular files, filesystems
1413 cannot encrypt data in-place in the page cache, since the cached
1421 -----------------------------
1425 filename hashes.  When a ->lookup() is requested, the filesystem
1435 i.e. the bytes actually stored on-disk in the directory entries.  When
1436 asked to do a ->lookup() with the key, the filesystem just encrypts
1437 the user-supplied name to get the ciphertext.
1441 filenames.  Therefore, readdir() must base64url-encode the ciphertext
1442 for presentation.  For most filenames, this works fine; on ->lookup(),
1443 the filesystem just base64url-decodes the user-supplied name to get
1450 filesystem-specific hash(es) needed for directory lookups.  This
1452 the filename given in ->lookup() back to a particular directory entry
1459 ``rm -r`` work as expected on encrypted directories.
1469 f2fs encryption using `kvm-xfstests
1470 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
1472     kvm-xfstests -c ext4,f2fs -g encrypt
1473     kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
1476 a separate command, and it takes some time for kvm-xfstests to set up
1479     kvm-xfstests -c ubifs -g encrypt
1481 No tests should fail.  However, tests that use non-default encryption
1483 algorithms were not built into the kernel's crypto API.  Also, tests
1492 kvm-xfstests, use the "encrypt" filesystem configuration::
1494     kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1495     kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
1497 Because this runs many more tests than "-g encrypt" does, it takes
1498 much longer to run; so also consider using `gce-xfstests
1499 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
1500 instead of kvm-xfstests::
1502     gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1503     gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt