Re: [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY

From: walter harms <wharms@bfs.de>
To: linux-man@vger.kernel.org, darrick.wong@oracle.com,
	dhowells@redhat.com, jaegeuk@kernel.org,
	linux-api@vger.kernel.org, linux-ext4@vger.kernel.org,
	linux-f2fs-devel@lists.sourceforge.net,
	linux-fscrypt@vger.kernel.org, linux-fsdevel@vger.kernel.org,
	tytso@mit.edu, victorhsieh@google.com
Subject: Re: [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY
Date: Sat, 09 Nov 2019 20:34:51 +0100	[thread overview]
Message-ID: <5DC714DB.9060007@bfs.de> (raw)
In-Reply-To: <20191108193557.GA12997@gmail.com>

Am 08.11.2019 20:35, schrieb Eric Biggers:
> On Fri, Nov 08, 2019 at 09:23:04AM +0100, walter harms wrote:
>>
>>
>> Am 07.11.2019 23:02, schrieb Eric Biggers:
>>> From: Eric Biggers <ebiggers@google.com>
>>>
>>> Document the verity attribute for statx().
>>>
>>> Signed-off-by: Eric Biggers <ebiggers@google.com>
>>> ---
>>>  man2/statx.2 | 4 ++++
>>>  1 file changed, 4 insertions(+)
>>>
>>> RFC since the kernel patches are currently under review.
>>> The kernel patches can be found here:
>>> https://lkml.kernel.org/linux-fscrypt/20191029204141.145309-1-ebiggers@kernel.org/T/#u
>>>
>>> diff --git a/man2/statx.2 b/man2/statx.2
>>> index d2f1b07b8..713bd1260 100644
>>> --- a/man2/statx.2
>>> +++ b/man2/statx.2
>>> @@ -461,6 +461,10 @@ See
>>>  .TP
>>>  .B STATX_ATTR_ENCRYPTED
>>>  A key is required for the file to be encrypted by the filesystem.
>>> +.TP
>>> +.B STATX_ATTR_VERITY
>>> +The file has fs-verity enabled.  It cannot be written to, and all reads from it
>>> +will be verified against a Merkle tree.
>>
>> Using "Merkle tree" opens a can of worm and what will happen when the methode will change ?
>> Does it matter at all ? i would suggest "filesystem" here.
>>
> 
> Fundamentally, fs-verity guarantees that all data read is verified against a
> cryptographic hash that covers the entire file.  I think it will be helpful to
> convey that here, e.g. to avoid confusion with non-cryptographic, individual
> block checksums supported by filesystems like btrfs and zfs.
> 
> Now, the only sane way to implement this model is with a Merkle tree, and this
> is part of the fs-verity UAPI (via the file hash), so that's where I'm coming
> from here.  Perhaps the phrase "Merkle tree" could be interpreted too strictly,
> though, so it would be better to emphasize the more abstract model.  How about
> the following?:
> 
> 	The file has fs-verity enabled.  It cannot be written to, and all reads
> 	from it will be verified against a cryptographic hash that covers the
> 	entire file, e.g. via a Merkle tree.
> 

"feels" better,. but from a programmers perspective it is important at what level
this is actually done. To see my point look at the line before.
"encrypted by the filesystem" mean i have to read the documentation of the fs first
so if encryption is supported at all. Or do i think to complicated ?

jm2c,
re
 wh