Re: [PATCH v7 08/43] fscrypt: add documentation about extent encryption

[Eric Biggers <ebiggers@kernel.org>]

On Wed, May 13, 2026 at 10:52:42AM +0200, Daniel Vacek wrote:
> From: Josef Bacik <josef@toxicpanda.com>
> 
> Add a couple of sections to the fscrypt documentation about per-extent
> encryption.

A few things that were missed:

- "Contents encryption" section should be updated to document how
  extents are encrypted

- btrfs should be added to the list of filesystems in the introduction
  section and in the "Tests" section

- "Read-only kernel memory compromise" should be updated to mention the
  new limitation which extent-based encryption creates.
  Maybe after the sentence "Per-file keys for in-use files will *not* be
  removed or wiped.", insert "On filesystems that use per-extent
  encryption, master keys for in-use files will not be wiped either."

The list of filesystems can also be found in the help text for the
CONFIG_FS_ENCRYPTION kconfig.  That should be updated too.

> +For certain file systems, such as btrfs, it's desired to derive a
> +per-extent encryption key.  This is to enable features such as snapshots

It's necessary, not just "desired".  The per-file keys just don't work
when multiple files can share the same extents.

> +Currently the inode's master key and encryption policy must match the
> +extent, so you cannot share extents between inodes that were encrypted
> +differently.

Here's another instance of "the inode".  It should say something like:
Currently, each extent's master key and encryption mode always match the
corresponding values from each inode that shares the extent.

> +The extent encryption context mirrors the important parts of the above
> +`Encryption context`_, with a few omissions.  The struct is defined as
> +follows::
> +
> +        struct fscrypt_extent_context {
> +                u8 version;
> +                u8 encryption_mode;
> +                u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
> +                u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
> +        };
> +
> +Currently all fields much match the containing inode's encryption
> +context, with the exception of the nonce.
> +
> +Additionally extent encryption is only supported with
> +FSCRYPT_EXTENT_CONTEXT_V2 using the standard policy; all other policies
> +are disallowed.

FSCRYPT_EXTENT_CONTEXT_V2 should say FSCRYPT_EXTENT_CONTEXT_V1.

Both version and nonce are exceptions, not just nonce.

Unclear what "the standard policy" is.

- Eric