linux-kernel - Re: [PATCH v6 08/43] fscrypt: add documentation about extent encryption

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <64126c50-063e-40e4-a536-233cce94b65e@infradead.org>
Date: Fri, 6 Feb 2026 10:43:24 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Daniel Vacek <neelx@...e.com>, Chris Mason <clm@...com>,
 Josef Bacik <josef@...icpanda.com>, Eric Biggers <ebiggers@...nel.org>,
 "Theodore Y. Ts'o" <tytso@....edu>, Jaegeuk Kim <jaegeuk@...nel.org>,
 Jens Axboe <axboe@...nel.dk>, David Sterba <dsterba@...e.com>,
 Jonathan Corbet <corbet@....net>
Cc: linux-block@...r.kernel.org, linux-fscrypt@...r.kernel.org,
 linux-btrfs@...r.kernel.org, linux-kernel@...r.kernel.org,
 linux-doc@...r.kernel.org
Subject: Re: [PATCH v6 08/43] fscrypt: add documentation about extent
 encryption



On 2/6/26 10:22 AM, Daniel Vacek wrote:
> From: Josef Bacik <josef@...icpanda.com>
> 
> Add a couple of sections to the fscrypt documentation about per-extent
> encryption.
> 
> Signed-off-by: Josef Bacik <josef@...icpanda.com>
> Signed-off-by: Daniel Vacek <neelx@...e.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