On Wed, May 13, 2026 at 10:52:42AM +0200, Daniel Vacek wrote:
> From: Josef Bacik <[email protected]>
>
> 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
