[PATCH] fcntl.2: document F_GET_SEALS on tmpfs peculiarity

[PATCH] fcntl.2: document F_GET_SEALS on tmpfs peculiarity

[Kir Kolyshkin]

Currently, from the description of file sealing it can be deduced that
unless the fd is a memfd, all sealing operations fail with EINVAL.

Apparently, it's not true for tmpfs or hugetlbfs -- F_GET_SEALS returns
1 (F_SEAL_SEAL) for an fd opened on these filesystems (probably because
those are used to back memfd files).

Fix the description to mention that peculiarity. Not knowing this can
result in incorrect code logic (see [1], where the code mistook a
descriptor of a file opened on on tmpfs for a memfd).

While at it, clarify that fcntl does not actually return EINVAL, but
sets errno to it (as it is usually said elsewhere).

[1] https://github.com/opencontainers/runc/pull/3342

Cc: Aleksa Sarai <cyphar@cyphar.com>
Cc: David Herrmann <dh.herrmann@gmail.com>
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 man2/fcntl.2 | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/man2/fcntl.2 b/man2/fcntl.2
index 7b5604e3a..f951b05ff 100644
--- a/man2/fcntl.2
+++ b/man2/fcntl.2
@@ -1402,10 +1402,23 @@ file seals can be applied only to a file descriptor returned by
 (if the
 .B MFD_ALLOW_SEALING
 was employed).
-On other filesystems, all
+On all other filesystems, except
+.BR tmpfs (5)
+and
+.BR hugetlbfs ,
+all
 .BR fcntl ()
-operations that operate on seals will return
+operations that operate on seals will fail with
+.I errno
+set to
 .BR EINVAL .
+For a descriptor from a file on
+.BR tmpfs (5)
+or
+.BR hugetlbfs ,
+.B F_GET_SEALS
+returns
+.BR F_SEAL_SEAL .
 .PP
 Seals are a property of an inode.
 Thus, all open file descriptors referring to the same inode share
-- 
2.33.1

Re: [PATCH] fcntl.2: document F_GET_SEALS on tmpfs peculiarity

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 2079 bytes --]

Adding the maintainers of mm/{shmem,memfd}.c and fs/hugetlbfs/ just in
case this was not intended behaviour.

On 2022-01-21, Kir Kolyshkin <kolyshkin@gmail.com> wrote:
> Currently, from the description of file sealing it can be deduced that
> unless the fd is a memfd, all sealing operations fail with EINVAL.
> 
> Apparently, it's not true for tmpfs or hugetlbfs -- F_GET_SEALS returns
> 1 (F_SEAL_SEAL) for an fd opened on these filesystems (probably because
> those are used to back memfd files).
> 
> Fix the description to mention that peculiarity. Not knowing this can
> result in incorrect code logic (see [1], where the code mistook a
> descriptor of a file opened on on tmpfs for a memfd).
> 
> While at it, clarify that fcntl does not actually return EINVAL, but
> sets errno to it (as it is usually said elsewhere).
> 
> [1] https://github.com/opencontainers/runc/pull/3342
> 
> Cc: Aleksa Sarai <cyphar@cyphar.com>
> Cc: David Herrmann <dh.herrmann@gmail.com>
> Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
> ---
>  man2/fcntl.2 | 17 +++++++++++++++--
>  1 file changed, 15 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/fcntl.2 b/man2/fcntl.2
> index 7b5604e3a..f951b05ff 100644
> --- a/man2/fcntl.2
> +++ b/man2/fcntl.2
> @@ -1402,10 +1402,23 @@ file seals can be applied only to a file descriptor returned by
>  (if the
>  .B MFD_ALLOW_SEALING
>  was employed).
> -On other filesystems, all
> +On all other filesystems, except
> +.BR tmpfs (5)
> +and
> +.BR hugetlbfs ,
> +all
>  .BR fcntl ()
> -operations that operate on seals will return
> +operations that operate on seals will fail with
> +.I errno
> +set to
>  .BR EINVAL .
> +For a descriptor from a file on
> +.BR tmpfs (5)
> +or
> +.BR hugetlbfs ,
> +.B F_GET_SEALS
> +returns
> +.BR F_SEAL_SEAL .
>  .PP
>  Seals are a property of an inode.
>  Thus, all open file descriptors referring to the same inode share
> -- 
> 2.33.1
> 

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
<https://www.cyphar.com/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] fcntl.2: document F_GET_SEALS on tmpfs peculiarity

[Hugh Dickins]

On Sat, 22 Jan 2022, Aleksa Sarai wrote:

> Adding the maintainers of mm/{shmem,memfd}.c and fs/hugetlbfs/ just in
> case this was not intended behaviour.

Kir is correct - thanks - and it is intended behaviour.  Not consciously
intended to make for a difficult manpage, but the implementation was
intended to be simple, so tmpfs and hugetlbfs do not internally
distinguish memfd objects from filesystem files - their filesystem
files simply start off with F_SEAL_SEAL to rule out any sealing.

> 
> On 2022-01-21, Kir Kolyshkin <kolyshkin@gmail.com> wrote:
> > Currently, from the description of file sealing it can be deduced that
> > unless the fd is a memfd, all sealing operations fail with EINVAL.
> > 
> > Apparently, it's not true for tmpfs or hugetlbfs -- F_GET_SEALS returns
> > 1 (F_SEAL_SEAL) for an fd opened on these filesystems (probably because
> > those are used to back memfd files).
> > 
> > Fix the description to mention that peculiarity. Not knowing this can
> > result in incorrect code logic (see [1], where the code mistook a
> > descriptor of a file opened on on tmpfs for a memfd).
> > 
> > While at it, clarify that fcntl does not actually return EINVAL, but
> > sets errno to it (as it is usually said elsewhere).
> > 
> > [1] https://github.com/opencontainers/runc/pull/3342
> > 
> > Cc: Aleksa Sarai <cyphar@cyphar.com>
> > Cc: David Herrmann <dh.herrmann@gmail.com>
> > Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>

Acked-by: Hugh Dickins <hughd@google.com>

> > ---
> >  man2/fcntl.2 | 17 +++++++++++++++--
> >  1 file changed, 15 insertions(+), 2 deletions(-)
> > 
> > diff --git a/man2/fcntl.2 b/man2/fcntl.2
> > index 7b5604e3a..f951b05ff 100644
> > --- a/man2/fcntl.2
> > +++ b/man2/fcntl.2
> > @@ -1402,10 +1402,23 @@ file seals can be applied only to a file descriptor returned by
> >  (if the
> >  .B MFD_ALLOW_SEALING
> >  was employed).
> > -On other filesystems, all
> > +On all other filesystems, except
> > +.BR tmpfs (5)
> > +and
> > +.BR hugetlbfs ,
> > +all
> >  .BR fcntl ()
> > -operations that operate on seals will return
> > +operations that operate on seals will fail with
> > +.I errno
> > +set to
> >  .BR EINVAL .
> > +For a descriptor from a file on
> > +.BR tmpfs (5)
> > +or
> > +.BR hugetlbfs ,
> > +.B F_GET_SEALS
> > +returns
> > +.BR F_SEAL_SEAL .
> >  .PP
> >  Seals are a property of an inode.
> >  Thus, all open file descriptors referring to the same inode share
> > -- 
> > 2.33.1
> > 
> 
> -- 
> Aleksa Sarai
> Senior Software Engineer (Containers)
> SUSE Linux GmbH
> <https://www.cyphar.com/>

Re: [PATCH] fcntl.2: document F_GET_SEALS on tmpfs peculiarity

[Mike Kravetz]

On 1/23/22 20:18, Hugh Dickins wrote:
> On Sat, 22 Jan 2022, Aleksa Sarai wrote:
> 
>> Adding the maintainers of mm/{shmem,memfd}.c and fs/hugetlbfs/ just in
>> case this was not intended behaviour.
> 
> Kir is correct - thanks - and it is intended behaviour.  Not consciously
> intended to make for a difficult manpage, but the implementation was
> intended to be simple, so tmpfs and hugetlbfs do not internally
> distinguish memfd objects from filesystem files - their filesystem
> files simply start off with F_SEAL_SEAL to rule out any sealing.
> 

Thanks Hugh, I agree.

>> On 2022-01-21, Kir Kolyshkin <kolyshkin@gmail.com> wrote:
>>> Currently, from the description of file sealing it can be deduced that
>>> unless the fd is a memfd, all sealing operations fail with EINVAL.
>>>
>>> Apparently, it's not true for tmpfs or hugetlbfs -- F_GET_SEALS returns
>>> 1 (F_SEAL_SEAL) for an fd opened on these filesystems (probably because
>>> those are used to back memfd files).
>>>
>>> Fix the description to mention that peculiarity. Not knowing this can
>>> result in incorrect code logic (see [1], where the code mistook a
>>> descriptor of a file opened on on tmpfs for a memfd).
>>>
>>> While at it, clarify that fcntl does not actually return EINVAL, but
>>> sets errno to it (as it is usually said elsewhere).
>>>
>>> [1] https://github.com/opencontainers/runc/pull/3342
>>>
>>> Cc: Aleksa Sarai <cyphar@cyphar.com>
>>> Cc: David Herrmann <dh.herrmann@gmail.com>
>>> Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
> 
> Acked-by: Hugh Dickins <hughd@google.com>

Acked-by: Mike Kravetz <mike.kravetz@oracle.com>

-- 
Mike Kravetz