[PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[Andy Lutomirski]

The current text reflects the general worry in the kernel about
recipients of O_PATH fds being able to hardlink the referenced files.
It turns out that it was possible to link these files regardless of
any possible security concerns.

Linux 3.11 removes the capability chech in AT_EMPTY_PATH.  I expect
that this functionality will be generally useful, so let's document it
better.

Signed-off-by: Andy Lutomirski <luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org>
---
 man2/linkat.2 | 28 ++++++++++++++++++----------
 man2/open.2   |  8 +++++++-
 2 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/man2/linkat.2 b/man2/linkat.2
index 701d341..003204d 100644
--- a/man2/linkat.2
+++ b/man2/linkat.2
@@ -110,16 +110,16 @@ is an empty string, create a link to the file referenced by
 flag).
 In this case,
 .I olddirfd
-can refer to any type of file, not just a directory.
-The caller must have the
+can refer to any type of file, not just a directory.  This will
+generally not work if the file has a link count of zero (files
+created with
+.BR O_TMPFILE
+and without
+.BR O_EXCL
+are an exception).  Prior to
+Linux 3.11, the caller must have the
 .BR CAP_DAC_READ_SEARCH
-capability in order to use this flag;
-this prevents arbitrary users from creating hard links
-using file descriptors received via a UNIX domain socket
-(see the discussion of
-.BR SCM_RIGHTS
-in
-.BR unix (7)).
+capability in order to use this flag.
 .TP
 .BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)"
 By default,
@@ -134,7 +134,15 @@ can be specified in
 .I flags
 to cause
 .I oldpath
-to be dereferenced if it is a symbolic link.
+to be dereferenced if it is a symbolic link.  If procfs is mounted,
+this can be used as an alternative to AT_EMPTY_PATH, even by
+unprivileged processes on Linux versions before 3.11, like this:
+.RS
+.PP
+.EX
+linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd, newname, AT_SYMLINK_FOLLOW);
+.EE
+.RE
 .PP
 Before kernel 2.6.18, the
 .I flags
diff --git a/man2/open.2 b/man2/open.2
index 9ebc0a0..cb5d489 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -499,7 +499,13 @@ Passing the file descriptor as the
 .IR dirfd
 argument of
 .BR openat (2)
-and the other "*at()" system calls.
+and the other "*at()" system calls.  This includes
+.BR linkat (2)
+with
+.BR AT_EMPTY_PATH
+(or via procfs using
+.BR AT_SYMLINK_FOLLOW )
+even if the file is not a directory.
 .IP *
 Passing the file descriptor to another process via a UNIX domain socket
 (see
-- 
1.8.3.1

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[Andy Lutomirski]

On Fri, Aug 9, 2013 at 11:58 AM, Andy Lutomirski <luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org> wrote:
> The current text reflects the general worry in the kernel about
> recipients of O_PATH fds being able to hardlink the referenced files.
> It turns out that it was possible to link these files regardless of
> any possible security concerns.
>
> Linux 3.11 removes the capability chech in AT_EMPTY_PATH.  I expect
> that this functionality will be generally useful, so let's document it
> better.
>
> Signed-off-by: Andy Lutomirski <luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org>

For reference, the relevant change is:

https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=bb2314b47996491bbc5add73633905c3120b6268

Also, I can't spell "check".  Oh, well.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[Michael Kerrisk (man-pages)]

On 08/09/2013 08:58 PM, Andy Lutomirski wrote:
> The current text reflects the general worry in the kernel about
> recipients of O_PATH fds being able to hardlink the referenced files.
> It turns out that it was possible to link these files regardless of
> any possible security concerns.
> 
> Linux 3.11 removes the capability chech in AT_EMPTY_PATH.  I expect
> that this functionality will be generally useful, so let's document it
> better.

Andy,

Again, long after the fact, sorry. But, I've applied this now (with 
your spelling "chech" fixed in the change log, as you mentioned in the
follow-on mail).

Nicely constructed patch by the way: I liked the way that the additions
to the linkat() text explained why capability check (and thus the man 
page text describing the need for that check) was removed.

Cheers,

Michael


> 
> Signed-off-by: Andy Lutomirski <luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org>
> ---
>  man2/linkat.2 | 28 ++++++++++++++++++----------
>  man2/open.2   |  8 +++++++-
>  2 files changed, 25 insertions(+), 11 deletions(-)
> 
> diff --git a/man2/linkat.2 b/man2/linkat.2
> index 701d341..003204d 100644
> --- a/man2/linkat.2
> +++ b/man2/linkat.2
> @@ -110,16 +110,16 @@ is an empty string, create a link to the file referenced by
>  flag).
>  In this case,
>  .I olddirfd
> -can refer to any type of file, not just a directory.
> -The caller must have the
> +can refer to any type of file, not just a directory.  This will
> +generally not work if the file has a link count of zero (files
> +created with
> +.BR O_TMPFILE
> +and without
> +.BR O_EXCL
> +are an exception).  Prior to
> +Linux 3.11, the caller must have the
>  .BR CAP_DAC_READ_SEARCH
> -capability in order to use this flag;
> -this prevents arbitrary users from creating hard links
> -using file descriptors received via a UNIX domain socket
> -(see the discussion of
> -.BR SCM_RIGHTS
> -in
> -.BR unix (7)).
> +capability in order to use this flag.
>  .TP
>  .BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)"
>  By default,
> @@ -134,7 +134,15 @@ can be specified in
>  .I flags
>  to cause
>  .I oldpath
> -to be dereferenced if it is a symbolic link.
> +to be dereferenced if it is a symbolic link.  If procfs is mounted,
> +this can be used as an alternative to AT_EMPTY_PATH, even by
> +unprivileged processes on Linux versions before 3.11, like this:
> +.RS
> +.PP
> +.EX
> +linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd, newname, AT_SYMLINK_FOLLOW);
> +.EE
> +.RE
>  .PP
>  Before kernel 2.6.18, the
>  .I flags
> diff --git a/man2/open.2 b/man2/open.2
> index 9ebc0a0..cb5d489 100644
> --- a/man2/open.2
> +++ b/man2/open.2
> @@ -499,7 +499,13 @@ Passing the file descriptor as the
>  .IR dirfd
>  argument of
>  .BR openat (2)
> -and the other "*at()" system calls.
> +and the other "*at()" system calls.  This includes
> +.BR linkat (2)
> +with
> +.BR AT_EMPTY_PATH
> +(or via procfs using
> +.BR AT_SYMLINK_FOLLOW )
> +even if the file is not a directory.
>  .IP *
>  Passing the file descriptor to another process via a UNIX domain socket
>  (see
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[Andy Lutomirski]

On Thu, May 8, 2014 at 2:45 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 08/09/2013 08:58 PM, Andy Lutomirski wrote:
>> The current text reflects the general worry in the kernel about
>> recipients of O_PATH fds being able to hardlink the referenced files.
>> It turns out that it was possible to link these files regardless of
>> any possible security concerns.
>>
>> Linux 3.11 removes the capability chech in AT_EMPTY_PATH.  I expect
>> that this functionality will be generally useful, so let's document it
>> better.
>
> Andy,
>
> Again, long after the fact, sorry. But, I've applied this now (with
> your spelling "chech" fixed in the change log, as you mentioned in the
> follow-on mail).
>
> Nicely constructed patch by the way: I liked the way that the additions
> to the linkat() text explained why capability check (and thus the man
> page text describing the need for that check) was removed.

Thanks.  Unfortunately, this was reverted in
f0cc6ffb8ce8961db587e5072168cac0cbc25f05 due to never-quite-explained
security issues. :(

--Andy
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[Michael Kerrisk (man-pages)]

On 05/08/2014 10:34 PM, Andy Lutomirski wrote:
> On Thu, May 8, 2014 at 2:45 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On 08/09/2013 08:58 PM, Andy Lutomirski wrote:
>>> The current text reflects the general worry in the kernel about
>>> recipients of O_PATH fds being able to hardlink the referenced files.
>>> It turns out that it was possible to link these files regardless of
>>> any possible security concerns.
>>>
>>> Linux 3.11 removes the capability chech in AT_EMPTY_PATH.  I expect
>>> that this functionality will be generally useful, so let's document it
>>> better.
>>
>> Andy,
>>
>> Again, long after the fact, sorry. But, I've applied this now (with
>> your spelling "chech" fixed in the change log, as you mentioned in the
>> follow-on mail).
>>
>> Nicely constructed patch by the way: I liked the way that the additions
>> to the linkat() text explained why capability check (and thus the man
>> page text describing the need for that check) was removed.
> 
> Thanks.  Unfortunately, this was reverted in
> f0cc6ffb8ce8961db587e5072168cac0cbc25f05 due to never-quite-explained
> security issues. :(

Ahhh--okay. But still, some parts of your patch are useful, are they not? I mean:

+This will
+generally not work if the file has a link count of zero (files
+created with
+.BR O_TMPFILE
+and without
+.BR O_EXCL
+are an exception).

and

+If procfs is mounted,
+this can be used as an alternative to AT_EMPTY_PATH,

are still correct, right?

I've tweaked the relevant parts of link(2). Do the following pieces now look
okay to you:

       AT_EMPTY_PATH (since Linux 2.6.39)
              If oldpath is an empty string, create a link to the file
              referenced by olddirfd (which  may  have  been  obtained
              using  the open(2) O_PATH flag).  In this case, olddirfd
              can refer to any type of file,  not  just  a  directory.
              This  will  generally  not  work  if the file has a link
              count of zero (files created with O_TMPFILE and  without
              O_EXCL  are  an  exception).   The  caller must have the
              CAP_DAC_READ_SEARCH capability  in  order  to  use  this
              flag.   This  flag is Linux-specific; define _GNU_SOURCE
              to obtain its definition.

       AT_SYMLINK_FOLLOW (since Linux 2.6.18)
              By default, linkat(), does not dereference oldpath if it
              is  a  symbolic  link  (like  link()).  The flag AT_SYM‐
              LINK_FOLLOW can be specified in flags to  cause  oldpath
              to  be dereferenced if it is a symbolic link.  If procfs
              is mounted, this  can  be  used  as  an  alternative  to
              AT_EMPTY_PATH, like this:

                  linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
                         newname, AT_SYMLINK_FOLLOW);

?


Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[Andy Lutomirski]

On Thu, May 8, 2014 at 10:22 PM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 05/08/2014 10:34 PM, Andy Lutomirski wrote:
>> On Thu, May 8, 2014 at 2:45 AM, Michael Kerrisk (man-pages)
>> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> On 08/09/2013 08:58 PM, Andy Lutomirski wrote:
>>>> The current text reflects the general worry in the kernel about
>>>> recipients of O_PATH fds being able to hardlink the referenced files.
>>>> It turns out that it was possible to link these files regardless of
>>>> any possible security concerns.
>>>>
>>>> Linux 3.11 removes the capability chech in AT_EMPTY_PATH.  I expect
>>>> that this functionality will be generally useful, so let's document it
>>>> better.
>>>
>>> Andy,
>>>
>>> Again, long after the fact, sorry. But, I've applied this now (with
>>> your spelling "chech" fixed in the change log, as you mentioned in the
>>> follow-on mail).
>>>
>>> Nicely constructed patch by the way: I liked the way that the additions
>>> to the linkat() text explained why capability check (and thus the man
>>> page text describing the need for that check) was removed.
>>
>> Thanks.  Unfortunately, this was reverted in
>> f0cc6ffb8ce8961db587e5072168cac0cbc25f05 due to never-quite-explained
>> security issues. :(
>
> Ahhh--okay. But still, some parts of your patch are useful, are they not? I mean:
>
> +This will
> +generally not work if the file has a link count of zero (files
> +created with
> +.BR O_TMPFILE
> +and without
> +.BR O_EXCL
> +are an exception).
>
> and
>
> +If procfs is mounted,
> +this can be used as an alternative to AT_EMPTY_PATH,
>
> are still correct, right?
>
> I've tweaked the relevant parts of link(2). Do the following pieces now look
> okay to you:
>
>        AT_EMPTY_PATH (since Linux 2.6.39)
>               If oldpath is an empty string, create a link to the file
>               referenced by olddirfd (which  may  have  been  obtained
>               using  the open(2) O_PATH flag).  In this case, olddirfd
>               can refer to any type of file,  not  just  a  directory.
>               This  will  generally  not  work  if the file has a link
>               count of zero (files created with O_TMPFILE and  without
>               O_EXCL  are  an  exception).   The  caller must have the
>               CAP_DAC_READ_SEARCH capability  in  order  to  use  this
>               flag.   This  flag is Linux-specific; define _GNU_SOURCE
>               to obtain its definition.
>
>        AT_SYMLINK_FOLLOW (since Linux 2.6.18)
>               By default, linkat(), does not dereference oldpath if it
>               is  a  symbolic  link  (like  link()).  The flag AT_SYM‐
>               LINK_FOLLOW can be specified in flags to  cause  oldpath
>               to  be dereferenced if it is a symbolic link.  If procfs
>               is mounted, this  can  be  used  as  an  alternative  to
>               AT_EMPTY_PATH, like this:
>
>                   linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
>                          newname, AT_SYMLINK_FOLLOW);
>
> ?

Yes, looks good.

Thanks,
Andy
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open,linkat: Update AT_EMPTY_PATH and O_PATH documentation

[Michael Kerrisk (man-pages)]

On Sat, May 10, 2014 at 2:59 AM, Andy Lutomirski <luto-kltTT9wpgjJwATOyAt5JVQ@public.gmane.org> wrote:
> On Thu, May 8, 2014 at 10:22 PM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On 05/08/2014 10:34 PM, Andy Lutomirski wrote:
>>> On Thu, May 8, 2014 at 2:45 AM, Michael Kerrisk (man-pages)
>>> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>>> On 08/09/2013 08:58 PM, Andy Lutomirski wrote:
>>>>> The current text reflects the general worry in the kernel about
>>>>> recipients of O_PATH fds being able to hardlink the referenced files.
>>>>> It turns out that it was possible to link these files regardless of
>>>>> any possible security concerns.
>>>>>
>>>>> Linux 3.11 removes the capability chech in AT_EMPTY_PATH.  I expect
>>>>> that this functionality will be generally useful, so let's document it
>>>>> better.
>>>>
>>>> Andy,
>>>>
>>>> Again, long after the fact, sorry. But, I've applied this now (with
>>>> your spelling "chech" fixed in the change log, as you mentioned in the
>>>> follow-on mail).
>>>>
>>>> Nicely constructed patch by the way: I liked the way that the additions
>>>> to the linkat() text explained why capability check (and thus the man
>>>> page text describing the need for that check) was removed.
>>>
>>> Thanks.  Unfortunately, this was reverted in
>>> f0cc6ffb8ce8961db587e5072168cac0cbc25f05 due to never-quite-explained
>>> security issues. :(
>>
>> Ahhh--okay. But still, some parts of your patch are useful, are they not? I mean:
>>
>> +This will
>> +generally not work if the file has a link count of zero (files
>> +created with
>> +.BR O_TMPFILE
>> +and without
>> +.BR O_EXCL
>> +are an exception).
>>
>> and
>>
>> +If procfs is mounted,
>> +this can be used as an alternative to AT_EMPTY_PATH,
>>
>> are still correct, right?
>>
>> I've tweaked the relevant parts of link(2). Do the following pieces now look
>> okay to you:
>>
>>        AT_EMPTY_PATH (since Linux 2.6.39)
>>               If oldpath is an empty string, create a link to the file
>>               referenced by olddirfd (which  may  have  been  obtained
>>               using  the open(2) O_PATH flag).  In this case, olddirfd
>>               can refer to any type of file,  not  just  a  directory.
>>               This  will  generally  not  work  if the file has a link
>>               count of zero (files created with O_TMPFILE and  without
>>               O_EXCL  are  an  exception).   The  caller must have the
>>               CAP_DAC_READ_SEARCH capability  in  order  to  use  this
>>               flag.   This  flag is Linux-specific; define _GNU_SOURCE
>>               to obtain its definition.
>>
>>        AT_SYMLINK_FOLLOW (since Linux 2.6.18)
>>               By default, linkat(), does not dereference oldpath if it
>>               is  a  symbolic  link  (like  link()).  The flag AT_SYM‐
>>               LINK_FOLLOW can be specified in flags to  cause  oldpath
>>               to  be dereferenced if it is a symbolic link.  If procfs
>>               is mounted, this  can  be  used  as  an  alternative  to
>>               AT_EMPTY_PATH, like this:
>>
>>                   linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
>>                          newname, AT_SYMLINK_FOLLOW);
>>
>> ?
>
> Yes, looks good.

Okay -- thanks, Andy.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html