Lines Matching +full:inline +full:- +full:crypto +full:- +full:engine
2 Filesystem-level encryption (fscrypt)
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
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
80 Cryptographic API algorithms or inline encryption hardware are. If a
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 -----------------------
293 This format is optimized for use with inline encryption hardware
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.
305 This format is optimized for use with inline encryption hardware
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
410 also be configured to use inline encryption hardware instead of the
411 kernel crypto API (see `Inline encryption support`_); in that case,
412 the file contents mode doesn't need to supported in the kernel crypto
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
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
479 data node" is treated as a crypto data unit. Each contains variable
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
641 compatibility with inline encryption hardware that only supports
642 smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be
644 particular system's inline encryption hardware.
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
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
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.
1102 ------------------
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
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
1171 the filesystem-level keyring, i.e. the keyring managed by
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.
1291 Inline encryption support
1294 Many newer systems (especially mobile SoCs) have *inline encryption
1296 the storage device. Linux supports inline encryption through a set of
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
1309 Note that the "inlinecrypt" mount option just specifies to use inline
1311 still fall back to using the kernel crypto API on files where the
1312 inline encryption hardware doesn't have the needed crypto capabilities
1314 and where blk-crypto-fallback is unusable. (For blk-crypto-fallback
1320 inline encryption hardware that supports that data unit size.
1322 Inline encryption doesn't affect the ciphertext or other aspects of
1323 the on-disk format, so users may freely switch back and forth between
1333 * The file must be using inline encryption. Usually this means that
1334 the filesystem must be mounted with ``-o inlinecrypt`` and inline
1336 is also available. For details, see `Inline encryption support`_.
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 -----------------
1397 When inline encryption is used, filesystems just need to associate
1399 inline encryption hardware will encrypt/decrypt the file contents.
1401 When inline encryption isn't used, filesystems must encrypt/decrypt
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.
1465 inline encryption support. For example, to test ext4 and
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
1480 algorithms were not built into the kernel's crypto API. Also, tests
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