On 2/6/26 10:22 AM, Daniel Vacek wrote:
> From: Josef Bacik <josef@toxicpanda.com>
>
> Add a couple of sections to the fscrypt documentation about per-extent
> encryption.
>
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>
> Signed-off-by: Daniel Vacek <neelx@suse.com>
> ---
>
> v5: https://lore.kernel.org/linux-btrfs/7b2cc4dd423c3930e51b1ef5dd209164ff11c05a.1706116485.git.josef@toxicpanda.com/
> * No changes since.
> ---
> Documentation/filesystems/fscrypt.rst | 41 +++++++++++++++++++++++++++
> 1 file changed, 41 insertions(+)
>
> diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
> index 70af896822e1..8afec55dd913 100644
> --- a/Documentation/filesystems/fscrypt.rst
> +++ b/Documentation/filesystems/fscrypt.rst
> @@ -283,6 +283,21 @@ alternative master keys or to support rotating master keys. Instead,
> the master keys may be wrapped in userspace, e.g. as is done by the
> `fscrypt <https://github.com/google/fscrypt>`_ tool.
>
> +Per-extent encryption keys
> +--------------------------
> +
> +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
> +and reflink, where you could have different inodes pointing at the same
> +extent. When a new extent is created fscrypt randomly generates a
> +16-byte nonce and the file system stores it along side the extent.
alongside
> +Then, it uses a KDF (as described in `Key derivation function`_) to
> +derive the extent's key from the master key and nonce.
> +
> +Currently the inode's master key and encryption policy must match the
> +extent, so you cannot share extents between inodes that were encrypted
> +differently.
> +
> DIRECT_KEY policies
> -------------------
>
> @@ -1488,6 +1503,27 @@ by the kernel and is used as KDF input or as a tweak to cause
> different files to be encrypted differently; see `Per-file encryption
> keys`_ and `DIRECT_KEY policies`_.
>
> +Extent encryption context
> +-------------------------
> +
> +The extent encryption context mirrors the important parts of the above
> +`Encryption context`_, with a few ommisions. The struct is defined as
omissions
> +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
policy; all other policies
> +are disallowed.
> +
> Data path changes
> -----------------
>
> @@ -1511,6 +1547,11 @@ buffer. Some filesystems, such as UBIFS, already use temporary
> buffers regardless of encryption. Other filesystems, such as ext4 and
> F2FS, have to allocate bounce pages specially for encryption.
>
> +Inline encryption is not optional for extent encryption based file
> +systems, the amount of objects required to be kept around is too much.
systems; the amount of
> +Inline encryption handles the object lifetime details which results in a
> +cleaner implementation.
> +
> Filename hashing and encoding
> -----------------------------
>
--
~Randy