linux-man.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY
       [not found] <20191107014420.GD15212@magnolia>
@ 2019-11-07 22:02 ` Eric Biggers
  2019-11-08  0:47   ` Darrick J. Wong
  2019-11-08  8:23   ` walter harms
  0 siblings, 2 replies; 6+ messages in thread
From: Eric Biggers @ 2019-11-07 22:02 UTC (permalink / raw)
  To: linux-man
  Cc: darrick.wong, dhowells, jaegeuk, linux-api, linux-ext4,
	linux-f2fs-devel, linux-fscrypt, linux-fsdevel, tytso,
	victorhsieh

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.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
2.24.0.rc1.363.gb1bccd3e3d-goog


^ permalink raw reply related	[flat|nested] 6+ messages in thread

* Re: [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY
  2019-11-07 22:02 ` [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY Eric Biggers
@ 2019-11-08  0:47   ` Darrick J. Wong
  2019-11-08  8:23   ` walter harms
  1 sibling, 0 replies; 6+ messages in thread
From: Darrick J. Wong @ 2019-11-08  0:47 UTC (permalink / raw)
  To: Eric Biggers
  Cc: linux-man, dhowells, jaegeuk, linux-api, linux-ext4,
	linux-f2fs-devel, linux-fscrypt, linux-fsdevel, tytso,
	victorhsieh

On Thu, Nov 07, 2019 at 02:02:48PM -0800, Eric Biggers wrote:
> 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.

mkerrisk might ask you to start the new sentence on a separate line, but
otherwise looks good to me. :)

--D

>  .SH RETURN VALUE
>  On success, zero is returned.
>  On error, \-1 is returned, and
> -- 
> 2.24.0.rc1.363.gb1bccd3e3d-goog
> 

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY
  2019-11-07 22:02 ` [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY Eric Biggers
  2019-11-08  0:47   ` Darrick J. Wong
@ 2019-11-08  8:23   ` walter harms
  2019-11-08 19:35     ` Eric Biggers
  1 sibling, 1 reply; 6+ messages in thread
From: walter harms @ 2019-11-08  8:23 UTC (permalink / raw)
  To: Eric Biggers
  Cc: linux-man, darrick.wong, dhowells, jaegeuk, linux-api,
	linux-ext4, linux-f2fs-devel, linux-fscrypt, linux-fsdevel,
	tytso, victorhsieh



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.

re,
 wh

>  .SH RETURN VALUE
>  On success, zero is returned.
>  On error, \-1 is returned, and

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY
  2019-11-08  8:23   ` walter harms
@ 2019-11-08 19:35     ` Eric Biggers
  2019-11-09 19:34       ` walter harms
  0 siblings, 1 reply; 6+ messages in thread
From: Eric Biggers @ 2019-11-08 19:35 UTC (permalink / raw)
  To: walter harms
  Cc: linux-man, darrick.wong, dhowells, jaegeuk, linux-api,
	linux-ext4, linux-f2fs-devel, linux-fscrypt, linux-fsdevel,
	tytso, victorhsieh

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.

- Eric

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY
  2019-11-08 19:35     ` Eric Biggers
@ 2019-11-09 19:34       ` walter harms
  2019-11-13 20:31         ` Eric Biggers
  0 siblings, 1 reply; 6+ messages in thread
From: walter harms @ 2019-11-09 19:34 UTC (permalink / raw)
  To: linux-man, darrick.wong, dhowells, jaegeuk, linux-api,
	linux-ext4, linux-f2fs-devel, linux-fscrypt, linux-fsdevel,
	tytso, victorhsieh



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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY
  2019-11-09 19:34       ` walter harms
@ 2019-11-13 20:31         ` Eric Biggers
  0 siblings, 0 replies; 6+ messages in thread
From: Eric Biggers @ 2019-11-13 20:31 UTC (permalink / raw)
  To: walter harms
  Cc: linux-man, darrick.wong, dhowells, jaegeuk, linux-api,
	linux-ext4, linux-f2fs-devel, linux-fscrypt, linux-fsdevel,
	tytso, victorhsieh

On Sat, Nov 09, 2019 at 08:34:51PM +0100, walter harms wrote:
> 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 ?
> 

It's filesystem-specific whether encryption and verity are supported.  I'm not
sure what your concern is, as statx() won't return the bits if the filesystem
doesn't support them.

Also note, if someone really wants the details about fscrypt and fsverity, they
really should read the documentation we maintain in the kernel tree [1][2].

[1] https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html
[2] https://www.kernel.org/doc/html/latest/filesystems/fsverity.html

- Eric

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2019-11-13 20:31 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <20191107014420.GD15212@magnolia>
2019-11-07 22:02 ` [man-pages RFC PATCH] statx.2: document STATX_ATTR_VERITY Eric Biggers
2019-11-08  0:47   ` Darrick J. Wong
2019-11-08  8:23   ` walter harms
2019-11-08 19:35     ` Eric Biggers
2019-11-09 19:34       ` walter harms
2019-11-13 20:31         ` Eric Biggers

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).