From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DBF1F334389; Fri, 6 Feb 2026 18:43:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1770403412; cv=none; b=AnxmxNfPFvwE6IFnUxnElItwAFMrKQ9w/6e3lqqGlmEhDwXy4RgWVmyYFQF5nRCQniExny7cVZfrXo8zNmxNiU9yBM7mD5lwqV5vmzQWQgE0UJ2sddZS1rM3n7GYphulPTAiVe27Gf4O5Cy0RICN0Chx2csFtu7P2sIs1avySN0= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1770403412; c=relaxed/simple; bh=m2u3aS6qyIKpZ+B5yYweZY5yt2FWLknmxlOhLyDMYlo=; h=Message-ID:Date:MIME-Version:Subject:To:Cc:References:From: In-Reply-To:Content-Type; b=SXRwQSewyoHuYUrS13j9lue2BOUNkVK+l/hWsOo3b1fsN2jeZ3zPj623azbDza7kS9t0EYB3e7Gvnb3krlVIIoPQ/yqhc4NmDqfBVrh8BcA+yM6g94xPhnZHoothmBX81ciGbzqsd+EY4YsiQm9WXxxn6sJQOo9XsnH3zwxKICU= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=ghSgZxc3; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="ghSgZxc3" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: Content-Type:In-Reply-To:From:References:Cc:To:Subject:MIME-Version:Date: Message-ID:Sender:Reply-To:Content-ID:Content-Description; bh=5QgLdcZSJhE8gvGsOPWe5bcX4FmYEvLxJG2bZjeJSzs=; b=ghSgZxc3NDfOm/juowJcnVFjJb 8ejnGmmUATCsJHB4+E/wg4Rx9oyw7ZQifZ0GGNgxT5qce6NZ7Z9oXZ2A1CBhUPRGUagdBdBYn+P0k mGqVItf+BPVrmcn7p5CL3WwfH6gbB7UfBxteyZCiGze0Pl+AYX5qeNQpyFq07PIdDVvOb76UDR064 3rbbbOqyByC4JrrD3DeRY3hRMaKjpuBdNEovV2e92RgHtIhpA1TfYI8qPJHReax9fuH/6D3xcq5sE LLqZN895XViPjiAUgi1YOR36Dz0gOrrzwKaMeEcYUBbXQeP6pkPND6vNQIJmZj9NNmrECrtu8thjX dIKSkYCQ==; Received: from [50.53.43.113] (helo=[192.168.254.34]) by bombadil.infradead.org with esmtpsa (Exim 4.98.2 #2 (Red Hat Linux)) id 1voQne-0000000Bhm7-3NB0; Fri, 06 Feb 2026 18:43:26 +0000 Message-ID: <64126c50-063e-40e4-a536-233cce94b65e@infradead.org> Date: Fri, 6 Feb 2026 10:43:24 -0800 Precedence: bulk X-Mailing-List: linux-btrfs@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v6 08/43] fscrypt: add documentation about extent encryption To: Daniel Vacek , Chris Mason , Josef Bacik , Eric Biggers , "Theodore Y. Ts'o" , Jaegeuk Kim , Jens Axboe , David Sterba , Jonathan Corbet Cc: linux-block@vger.kernel.org, linux-fscrypt@vger.kernel.org, linux-btrfs@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org References: <20260206182336.1397715-1-neelx@suse.com> <20260206182336.1397715-9-neelx@suse.com> Content-Language: en-US From: Randy Dunlap In-Reply-To: <20260206182336.1397715-9-neelx@suse.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit On 2/6/26 10:22 AM, Daniel Vacek wrote: > From: Josef Bacik > > Add a couple of sections to the fscrypt documentation about per-extent > encryption. > > Signed-off-by: Josef Bacik > Signed-off-by: Daniel Vacek > --- > > 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 `_ 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