On Fri, 6 Feb 2026 at 19:43, Randy Dunlap <[email protected]> wrote: > On 2/6/26 10:22 AM, Daniel Vacek wrote: > > From: Josef Bacik <[email protected]> > > > > Add a couple of sections to the fscrypt documentation about per-extent > > encryption. > > > > Signed-off-by: Josef Bacik <[email protected]> > > Signed-off-by: Daniel Vacek <[email protected]> > > --- > > > > v5: > > https://lore.kernel.org/linux-btrfs/7b2cc4dd423c3930e51b1ef5dd209164ff11c05a.1706116485.git.jo...@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
Thanks Randy. I'll amend all these in the next iteration. --nX > > +Inline encryption handles the object lifetime details which results in a > > +cleaner implementation. > > + > > Filename hashing and encoding > > ----------------------------- > > > > -- > ~Randy >
