diff options
Diffstat (limited to 'Documentation/filesystems')
| -rw-r--r-- | Documentation/filesystems/btrfs.rst | 16 | ||||
| -rw-r--r-- | Documentation/filesystems/f2fs.rst | 13 | ||||
| -rw-r--r-- | Documentation/filesystems/fscrypt.rst | 22 | ||||
| -rw-r--r-- | Documentation/filesystems/fsverity.rst | 53 | ||||
| -rw-r--r-- | Documentation/filesystems/netfs_library.rst | 8 | ||||
| -rw-r--r-- | Documentation/filesystems/overlayfs.rst | 2 |
6 files changed, 73 insertions, 41 deletions
diff --git a/Documentation/filesystems/btrfs.rst b/Documentation/filesystems/btrfs.rst index d0904f602819..992eddb0e11b 100644 --- a/Documentation/filesystems/btrfs.rst +++ b/Documentation/filesystems/btrfs.rst @@ -19,13 +19,23 @@ The main Btrfs features include: * Subvolumes (separate internal filesystem roots) * Object level mirroring and striping * Checksums on data and metadata (multiple algorithms available) - * Compression + * Compression (multiple algorithms available) + * Reflink, deduplication + * Scrub (on-line checksum verification) + * Hierarchical quota groups (subvolume and snapshot support) * Integrated multiple device support, with several raid algorithms * Offline filesystem check - * Efficient incremental backup and FS mirroring + * Efficient incremental backup and FS mirroring (send/receive) + * Trim/discard * Online filesystem defragmentation + * Swapfile support + * Zoned mode + * Read/write metadata verification + * Online resize (shrink, grow) -For more information please refer to the wiki +For more information please refer to the documentation site or wiki + + https://btrfs.readthedocs.io https://btrfs.wiki.kernel.org diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index ad8dc8c040a2..98dc24f5c6f0 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -818,10 +818,11 @@ Compression implementation Instead, the main goal is to reduce data writes to flash disk as much as possible, resulting in extending disk life time as well as relaxing IO congestion. Alternatively, we've added ioctl(F2FS_IOC_RELEASE_COMPRESS_BLOCKS) - interface to reclaim compressed space and show it to user after putting the - immutable bit. Immutable bit, after release, it doesn't allow writing/mmaping - on the file, until reserving compressed space via - ioctl(F2FS_IOC_RESERVE_COMPRESS_BLOCKS) or truncating filesize to zero. + interface to reclaim compressed space and show it to user after setting a + special flag to the inode. Once the compressed space is released, the flag + will block writing data to the file until either the compressed space is + reserved via ioctl(F2FS_IOC_RESERVE_COMPRESS_BLOCKS) or the file size is + truncated to zero. Compress metadata layout:: @@ -830,12 +831,12 @@ Compress metadata layout:: | cluster 1 | cluster 2 | ......... | cluster N | +-----------------------------------------------+ . . . . - . . . . + . . . . . Compressed Cluster . . Normal Cluster . +----------+---------+---------+---------+ +---------+---------+---------+---------+ |compr flag| block 1 | block 2 | block 3 | | block 1 | block 2 | block 3 | block 4 | +----------+---------+---------+---------+ +---------+---------+---------+---------+ - . . + . . . . . . +-------------+-------------+----------+----------------------------+ diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 2e9aaa295125..5ba5817c17c2 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -337,6 +337,7 @@ Currently, the following pairs of encryption modes are supported: - AES-256-XTS for contents and AES-256-CTS-CBC for filenames - AES-128-CBC for contents and AES-128-CTS-CBC for filenames - Adiantum for both contents and filenames +- AES-256-XTS for contents and AES-256-HCTR2 for filenames (v2 policies only) If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. @@ -357,6 +358,17 @@ To use Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast implementations of ChaCha and NHPoly1305 should be enabled, e.g. CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. +AES-256-HCTR2 is another true wide-block encryption mode that is intended for +use on CPUs with dedicated crypto instructions. AES-256-HCTR2 has the property +that a bitflip in the plaintext changes the entire ciphertext. This property +makes it desirable for filename encryption since initialization vectors are +reused within a directory. For more details on AES-256-HCTR2, see the paper +"Length-preserving encryption with HCTR2" +(https://eprint.iacr.org/2021/1441.pdf). To use AES-256-HCTR2, +CONFIG_CRYPTO_HCTR2 must be enabled. Also, fast implementations of XCTR and +POLYVAL should be enabled, e.g. CRYPTO_POLYVAL_ARM64_CE and +CRYPTO_AES_ARM64_CE_BLK for ARM64. + New encryption modes can be added relatively easily, without changes to individual filesystems. However, authenticated encryption (AE) modes are not currently supported because of the difficulty of dealing @@ -404,11 +416,11 @@ alternatively has the file's nonce (for `DIRECT_KEY policies`_) or inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. Thus, IV reuse is limited to within a single directory. -With CTS-CBC, the IV reuse means that when the plaintext filenames -share a common prefix at least as long as the cipher block size (16 -bytes for AES), the corresponding encrypted filenames will also share -a common prefix. This is undesirable. Adiantum does not have this -weakness, as it is a wide-block encryption mode. +With CTS-CBC, the IV reuse means that when the plaintext filenames share a +common prefix at least as long as the cipher block size (16 bytes for AES), the +corresponding encrypted filenames will also share a common prefix. This is +undesirable. Adiantum and HCTR2 do not have this weakness, as they are +wide-block encryption modes. All supported filenames encryption modes accept any plaintext length >= 16 bytes; cipher block alignment is not required. However, diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index 756f2c215ba1..cb8e7573882a 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -11,9 +11,9 @@ Introduction fs-verity (``fs/verity/``) is a support layer that filesystems can hook into to support transparent integrity and authenticity protection -of read-only files. Currently, it is supported by the ext4 and f2fs -filesystems. Like fscrypt, not too much filesystem-specific code is -needed to support fs-verity. +of read-only files. Currently, it is supported by the ext4, f2fs, and +btrfs filesystems. Like fscrypt, not too much filesystem-specific +code is needed to support fs-verity. fs-verity is similar to `dm-verity <https://www.kernel.org/doc/Documentation/device-mapper/verity.txt>`_ @@ -473,9 +473,9 @@ files being swapped around. Filesystem support ================== -fs-verity is currently supported by the ext4 and f2fs filesystems. -The CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity -on either filesystem. +fs-verity is supported by several filesystems, described below. The +CONFIG_FS_VERITY kconfig option must be enabled to use fs-verity on +any of these filesystems. ``include/linux/fsverity.h`` declares the interface between the ``fs/verity/`` support layer and filesystems. Briefly, filesystems @@ -544,6 +544,13 @@ Currently, f2fs verity only supports a Merkle tree block size of 4096. Also, f2fs doesn't support enabling verity on files that currently have atomic or volatile writes pending. +btrfs +----- + +btrfs supports fs-verity since Linux v5.15. Verity-enabled inodes are +marked with a RO_COMPAT inode flag, and the verity metadata is stored +in separate btree items. + Implementation details ====================== @@ -622,14 +629,14 @@ workqueue, and then the workqueue work does the decryption or verification. Finally, pages where no decryption or verity error occurred are marked Uptodate, and the pages are unlocked. -Files on ext4 and f2fs may contain holes. Normally, ``->readahead()`` -simply zeroes holes and sets the corresponding pages Uptodate; no bios -are issued. To prevent this case from bypassing fs-verity, these -filesystems use fsverity_verify_page() to verify hole pages. +On many filesystems, files can contain holes. Normally, +``->readahead()`` simply zeroes holes and sets the corresponding pages +Uptodate; no bios are issued. To prevent this case from bypassing +fs-verity, these filesystems use fsverity_verify_page() to verify hole +pages. -ext4 and f2fs disable direct I/O on verity files, since otherwise -direct I/O would bypass fs-verity. (They also do the same for -encrypted files.) +Filesystems also disable direct I/O on verity files, since otherwise +direct I/O would bypass fs-verity. Userspace utility ================= @@ -648,7 +655,7 @@ Tests To test fs-verity, use xfstests. For example, using `kvm-xfstests <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: - kvm-xfstests -c ext4,f2fs -g verity + kvm-xfstests -c ext4,f2fs,btrfs -g verity FAQ === @@ -771,15 +778,15 @@ weren't already directly answered in other parts of this document. e.g. magically trigger construction of a Merkle tree. :Q: Does fs-verity support remote filesystems? -:A: Only ext4 and f2fs support is implemented currently, but in - principle any filesystem that can store per-file verity metadata - can support fs-verity, regardless of whether it's local or remote. - Some filesystems may have fewer options of where to store the - verity metadata; one possibility is to store it past the end of - the file and "hide" it from userspace by manipulating i_size. The - data verification functions provided by ``fs/verity/`` also assume - that the filesystem uses the Linux pagecache, but both local and - remote filesystems normally do so. +:A: So far all filesystems that have implemented fs-verity support are + local filesystems, but in principle any filesystem that can store + per-file verity metadata can support fs-verity, regardless of + whether it's local or remote. Some filesystems may have fewer + options of where to store the verity metadata; one possibility is + to store it past the end of the file and "hide" it from userspace + by manipulating i_size. The data verification functions provided + by ``fs/verity/`` also assume that the filesystem uses the Linux + pagecache, but both local and remote filesystems normally do so. :Q: Why is anything filesystem-specific at all? Shouldn't fs-verity be implemented entirely at the VFS level? diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst index 4d19b19bcc08..73a4176144b3 100644 --- a/Documentation/filesystems/netfs_library.rst +++ b/Documentation/filesystems/netfs_library.rst @@ -301,7 +301,7 @@ through which it can issue requests and negotiate:: void (*issue_read)(struct netfs_io_subrequest *subreq); bool (*is_still_valid)(struct netfs_io_request *rreq); int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, - struct folio *folio, void **_fsdata); + struct folio **foliop, void **_fsdata); void (*done)(struct netfs_io_request *rreq); }; @@ -381,8 +381,10 @@ The operations are as follows: allocated/grabbed the folio to be modified to allow the filesystem to flush conflicting state before allowing it to be modified. - It should return 0 if everything is now fine, -EAGAIN if the folio should be - regrabbed and any other error code to abort the operation. + It may unlock and discard the folio it was given and set the caller's folio + pointer to NULL. It should return 0 if everything is now fine (``*foliop`` + left set) or the op should be retried (``*foliop`` cleared) and any other + error code to abort the operation. * ``done`` diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 7da6c30ed596..4c76fda07645 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -607,7 +607,7 @@ can be removed. User xattr ---------- -The the "-o userxattr" mount option forces overlayfs to use the +The "-o userxattr" mount option forces overlayfs to use the "user.overlay." xattr namespace instead of "trusted.overlay.". This is useful for unprivileged mounting of overlayfs. |