Traditionally, magic-links have not been a well-understood topic in
Linux. Given the new changes in their semantics (related to the link
mode of trailing magic-links), it seems like a good opportunity to shine
more light on magic-links and their semantics.
Signed-off-by: Aleksa Sarai <[email protected]>
---
man7/path_resolution.7 | 15 +++++++++++++++
man7/symlink.7 | 39 ++++++++++++++++++++++++++++++---------
2 files changed, 45 insertions(+), 9 deletions(-)
diff --git a/man7/path_resolution.7 b/man7/path_resolution.7
index 07664ed8faec..46f25ec4cdfa 100644
--- a/man7/path_resolution.7
+++ b/man7/path_resolution.7
@@ -136,6 +136,21 @@ we are just creating it.
The details on the treatment
of the final entry are described in the manual pages of the specific
system calls.
+.PP
+Since Linux 5.FOO, if the final entry is a "magic-link" (see
+.BR symlink (7)),
+and the user is attempting to
+.BR open (2)
+it, then there is an additional permission-related restriction applied to the
+operation: the requested access mode must not exceed the "link mode" of the
+magic-link (unlike ordinary symlinks, magic-links have their own file mode.)
+For example, if
+.I /proc/[pid]/fd/[num]
+has a link mode of
+.BR 0500 ,
+unprivileged users are not permitted to
+.BR open ()
+the magic-link for writing.
.SS . and ..
By convention, every directory has the entries "." and "..",
which refer to the directory itself and to its parent directory,
diff --git a/man7/symlink.7 b/man7/symlink.7
index 9f5bddd5dc21..33f0ec703acd 100644
--- a/man7/symlink.7
+++ b/man7/symlink.7
@@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
are outlined here.
It is important that site-local applications also conform to these rules,
so that the user interface can be as consistent as possible.
+.SS Magic-links
+There is a special class of symlink-like objects known as "magic-links" which
+can be found in certain pseudo-filesystems such as
+.BR proc (5)
+(examples include
+.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
+Unlike normal symlinks, magic-links are not resolved through
+pathname-expansion, but instead act as direct references to the kernel's own
+representation of a file handle. As such, these magic-links allow users to
+access files which cannot be referenced with normal paths (such as unlinked
+files still referenced by a running program.)
+.PP
+Because they can bypass ordinary
+.BR mount_namespaces (7)-based
+restrictions, magic-links have been used as attack vectors in various exploits.
+As such (since Linux 5.FOO), there are additional restrictions placed on the
+re-opening of magic-links (see
+.BR path_resolution (7)
+for more details.)
.SS Symbolic link ownership, permissions, and timestamps
The owner and group of an existing symbolic link can be changed
using
@@ -99,16 +118,18 @@ of a symbolic link can be changed using
or
.BR lutimes (3).
.PP
-On Linux, the permissions of a symbolic link are not used
-in any operations; the permissions are always
-0777 (read, write, and execute for all user categories),
.\" Linux does not currently implement an lchmod(2).
-and can't be changed.
-(Note that there are some "magic" symbolic links in the
-.I /proc
-directory tree\(emfor example, the
-.IR /proc/[pid]/fd/*
-files\(emthat have different permissions.)
+On Linux, the permissions of an ordinary symbolic link are not used in any
+operations; the permissions are always 0777 (read, write, and execute for all
+user categories), and can't be changed.
+.PP
+However, magic-links do not follow this rule. They can have a non-0777 mode,
+which is used for permission checks when the final
+component of an
+.BR open (2)'s
+path is a magic-link (see
+.BR path_resolution (7).)
+
.\"
.\" The
.\" 4.4BSD
--
2.23.0
On Thu, Oct 3, 2019 at 4:56 PM Aleksa Sarai <[email protected]> wrote:
> Traditionally, magic-links have not been a well-understood topic in
> Linux. Given the new changes in their semantics (related to the link
> mode of trailing magic-links), it seems like a good opportunity to shine
> more light on magic-links and their semantics.
[...]
> +++ b/man7/symlink.7
> @@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
> are outlined here.
> It is important that site-local applications also conform to these rules,
> so that the user interface can be as consistent as possible.
> +.SS Magic-links
> +There is a special class of symlink-like objects known as "magic-links" which
I think names like that normally aren't hypenated in english, and
instead of "magic-links", it'd be "magic links"? Just like how you
wouldn't write "symbolic-link", but "symbolic link". But this is
bikeshedding, and if you disagree, feel free to ignore this comment.
> +can be found in certain pseudo-filesystems such as
> +.BR proc (5)
> +(examples include
> +.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
> +Unlike normal symlinks, magic-links are not resolved through
nit: AFAICS symlinks are always referred to as "symbolic links"
throughout the manpages.
> +pathname-expansion, but instead act as direct references to the kernel's own
> +representation of a file handle. As such, these magic-links allow users to
> +access files which cannot be referenced with normal paths (such as unlinked
> +files still referenced by a running program.)
Could maybe add "and files in different mount namespaces" as another
example here; at least for me, that's the main usecases for
/proc/*/root.
[...]
> +However, magic-links do not follow this rule. They can have a non-0777 mode,
> +which is used for permission checks when the final
> +component of an
> +.BR open (2)'s
Maybe leave out the "open" part, since the same restriction has to
also apply to other syscalls operating on files, like truncate() and
so on?
> +path is a magic-link (see
> +.BR path_resolution (7).)
On 2019-10-07, Jann Horn <[email protected]> wrote:
> On Thu, Oct 3, 2019 at 4:56 PM Aleksa Sarai <[email protected]> wrote:
> > Traditionally, magic-links have not been a well-understood topic in
> > Linux. Given the new changes in their semantics (related to the link
> > mode of trailing magic-links), it seems like a good opportunity to shine
> > more light on magic-links and their semantics.
> [...]
> > +++ b/man7/symlink.7
> > @@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
> > are outlined here.
> > It is important that site-local applications also conform to these rules,
> > so that the user interface can be as consistent as possible.
> > +.SS Magic-links
> > +There is a special class of symlink-like objects known as "magic-links" which
>
> I think names like that normally aren't hypenated in english, and
> instead of "magic-links", it'd be "magic links"? Just like how you
> wouldn't write "symbolic-link", but "symbolic link". But this is
> bikeshedding, and if you disagree, feel free to ignore this comment.
Looking at it now, I think you're right -- I hyphenated it here because
that's how I wrote it when documenting the feature in comments. But I
think that's because "symlink" and "magic-link" (the "abbreviated"
versions) seem to match better than "symlink" and "magic link".
I'll use "magic link" in documentation, but "magic-link" for all cases
where I would normally write "symlink".
> > +can be found in certain pseudo-filesystems such as
> > +.BR proc (5)
> > +(examples include
> > +.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
> > +Unlike normal symlinks, magic-links are not resolved through
>
> nit: AFAICS symlinks are always referred to as "symbolic links"
> throughout the manpages.
:+1:
> > +pathname-expansion, but instead act as direct references to the kernel's own
> > +representation of a file handle. As such, these magic-links allow users to
> > +access files which cannot be referenced with normal paths (such as unlinked
> > +files still referenced by a running program.)
>
> Could maybe add "and files in different mount namespaces" as another
> example here; at least for me, that's the main usecases for
> /proc/*/root.
Will do.
> [...]
> > +However, magic-links do not follow this rule. They can have a non-0777 mode,
> > +which is used for permission checks when the final
> > +component of an
> > +.BR open (2)'s
>
> Maybe leave out the "open" part, since the same restriction has to
> also apply to other syscalls operating on files, like truncate() and
> so on?
Yes (though I've just realised I hadn't implemented that -- oops.) Given
how expansive this patchset will get -- I might end up splitting it into
the magic-link stuff (and O_EMPTYPATH) and a separate series for
openat2(2) and the path resolution restrictions.
--
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
<https://www.cyphar.com/>
Hello Aleksa,
On 10/3/19 4:55 PM, Aleksa Sarai wrote:
> Traditionally, magic-links have not been a well-understood topic in
> Linux. Given the new changes in their semantics (related to the link
> mode of trailing magic-links), it seems like a good opportunity to shine
> more light on magic-links and their semantics.
>
> Signed-off-by: Aleksa Sarai <[email protected]>
Thanks for doing this. Some comments below.
> ---
> man7/path_resolution.7 | 15 +++++++++++++++
> man7/symlink.7 | 39 ++++++++++++++++++++++++++++++---------
> 2 files changed, 45 insertions(+), 9 deletions(-)
>
> diff --git a/man7/path_resolution.7 b/man7/path_resolution.7
> index 07664ed8faec..46f25ec4cdfa 100644
> --- a/man7/path_resolution.7
> +++ b/man7/path_resolution.7
> @@ -136,6 +136,21 @@ we are just creating it.
> The details on the treatment
> of the final entry are described in the manual pages of the specific
> system calls.
> +.PP
> +Since Linux 5.FOO, if the final entry is a "magic-link" (see
"magic link". As Jann points out, this is more normal English usage.
> +.BR symlink (7)),
> +and the user is attempting to
> +.BR open (2)
> +it, then there is an additional permission-related restriction applied to the
> +operation: the requested access mode must not exceed the "link mode" of the
> +magic-link (unlike ordinary symlinks, magic-links have their own file mode.)
Remove the hyphens (magic link). And also, as someone else pointed out,
manual pages fairly consistently uses the term "symbolic link"
(written in full).
You use the term "file mode" here. Do you mean the file permissions bits?
If yes, it is a bit misleading to suggest that symbolic links don't
have these mode bits. They do, but--as noted in the existing symlink(7)
manual page text--these bits are ignored. I suggest just removing the
parenthesized text.
> +For example, if
> +.I /proc/[pid]/fd/[num]
> +has a link mode of
> +.BR 0500 ,
> +unprivileged users are not permitted to
> +.BR open ()
> +the magic-link for writing.
> .SS . and ..
> By convention, every directory has the entries "." and "..",
> which refer to the directory itself and to its parent directory,
> diff --git a/man7/symlink.7 b/man7/symlink.7
> index 9f5bddd5dc21..33f0ec703acd 100644
> --- a/man7/symlink.7
> +++ b/man7/symlink.7
> @@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
> are outlined here.
> It is important that site-local applications also conform to these rules,
> so that the user interface can be as consistent as possible.
> +.SS Magic-links
> +There is a special class of symlink-like objects known as "magic-links" which
"magic links" (and through the rest of the page).
> +can be found in certain pseudo-filesystems such as
pseudofilesystems
> +.BR proc (5)
> +(examples include
> +.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
> +Unlike normal symlinks, magic-links are not resolved through
symbolic links
> +pathname-expansion, but instead act as direct references to the kernel's own
pathname expansion
> +representation of a file handle. As such, these magic-links allow users to
> +access files which cannot be referenced with normal paths (such as unlinked
> +files still referenced by a running program.)
> +.PP
> +Because they can bypass ordinary
> +.BR mount_namespaces (7)-based
> +restrictions, magic-links have been used as attack vectors in various exploits.
> +As such (since Linux 5.FOO), there are additional restrictions placed on the
> +re-opening of magic-links (see
> +.BR path_resolution (7)
> +for more details.)
> .SS Symbolic link ownership, permissions, and timestamps
> The owner and group of an existing symbolic link can be changed
> using
> @@ -99,16 +118,18 @@ of a symbolic link can be changed using
> or
> .BR lutimes (3).
> .PP
> -On Linux, the permissions of a symbolic link are not used
> -in any operations; the permissions are always
> -0777 (read, write, and execute for all user categories),
> .\" Linux does not currently implement an lchmod(2).
> -and can't be changed.
> -(Note that there are some "magic" symbolic links in the
> -.I /proc
> -directory tree\(emfor example, the
> -.IR /proc/[pid]/fd/*
> -files\(emthat have different permissions.)
> +On Linux, the permissions of an ordinary symbolic link are not used in any
> +operations; the permissions are always 0777 (read, write, and execute for all
> +user categories), and can't be changed.
> +.PP
> +However, magic-links do not follow this rule. They can have a non-0777 mode,
> +which is used for permission checks when the final
> +component of an
> +.BR open (2)'s
> +path is a magic-link (see
> +.BR path_resolution (7).)
> +
> .\"
> .\" The
> .\" 4.4BSD
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
On 2019-10-09, Michael Kerrisk (man-pages) <[email protected]> wrote:
> On 10/3/19 4:55 PM, Aleksa Sarai wrote:
> > Traditionally, magic-links have not been a well-understood topic in
> > Linux. Given the new changes in their semantics (related to the link
> > mode of trailing magic-links), it seems like a good opportunity to shine
> > more light on magic-links and their semantics.
> >
> > Signed-off-by: Aleksa Sarai <[email protected]>
>
> Thanks for doing this. Some comments below.
No problem -- just a heads-up that I'm going to split off the magic-link
changes from the openat2(2) series (there are quite a few things that
need to be done). So I will drop this man page for now.
> > ---
> > man7/path_resolution.7 | 15 +++++++++++++++
> > man7/symlink.7 | 39 ++++++++++++++++++++++++++++++---------
> > 2 files changed, 45 insertions(+), 9 deletions(-)
> >
> > diff --git a/man7/path_resolution.7 b/man7/path_resolution.7
> > index 07664ed8faec..46f25ec4cdfa 100644
> > --- a/man7/path_resolution.7
> > +++ b/man7/path_resolution.7
> > @@ -136,6 +136,21 @@ we are just creating it.
> > The details on the treatment
> > of the final entry are described in the manual pages of the specific
> > system calls.
> > +.PP
> > +Since Linux 5.FOO, if the final entry is a "magic-link" (see
>
> "magic link". As Jann points out, this is more normal English usage.
>
> > +.BR symlink (7)),
> > +and the user is attempting to
> > +.BR open (2)
> > +it, then there is an additional permission-related restriction applied to the
> > +operation: the requested access mode must not exceed the "link mode" of the
> > +magic-link (unlike ordinary symlinks, magic-links have their own file mode.)
>
> Remove the hyphens (magic link). And also, as someone else pointed out,
> manual pages fairly consistently uses the term "symbolic link"
> (written in full).
Will do.
> You use the term "file mode" here. Do you mean the file permissions bits?
Yes.
> If yes, it is a bit misleading to suggest that symbolic links don't
> have these mode bits. They do, but--as noted in the existing symlink(7)
> manual page text--these bits are ignored. I suggest just removing the
> parenthesized text.
I was trying to say that their file mode can be non-0777 -- but I can
just drop the entire thing.
> > +For example, if
> > +.I /proc/[pid]/fd/[num]
> > +has a link mode of
> > +.BR 0500 ,
> > +unprivileged users are not permitted to
> > +.BR open ()
> > +the magic-link for writing.
> > .SS . and ..
> > By convention, every directory has the entries "." and "..",
> > which refer to the directory itself and to its parent directory,
> > diff --git a/man7/symlink.7 b/man7/symlink.7
> > index 9f5bddd5dc21..33f0ec703acd 100644
> > --- a/man7/symlink.7
> > +++ b/man7/symlink.7
> > @@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
> > are outlined here.
> > It is important that site-local applications also conform to these rules,
> > so that the user interface can be as consistent as possible.
> > +.SS Magic-links
> > +There is a special class of symlink-like objects known as "magic-links" which
>
> "magic links" (and through the rest of the page).
>
> > +can be found in certain pseudo-filesystems such as
>
> pseudofilesystems
>
> > +.BR proc (5)
> > +(examples include
> > +.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
> > +Unlike normal symlinks, magic-links are not resolved through
>
> symbolic links
>
> > +pathname-expansion, but instead act as direct references to the kernel's own
>
> pathname expansion
Will do all of the above.
> > +representation of a file handle. As such, these magic-links allow users to
> > +access files which cannot be referenced with normal paths (such as unlinked
> > +files still referenced by a running program.)
> > +.PP
> > +Because they can bypass ordinary
> > +.BR mount_namespaces (7)-based
> > +restrictions, magic-links have been used as attack vectors in various exploits.
> > +As such (since Linux 5.FOO), there are additional restrictions placed on the
> > +re-opening of magic-links (see
> > +.BR path_resolution (7)
> > +for more details.)
> > .SS Symbolic link ownership, permissions, and timestamps
> > The owner and group of an existing symbolic link can be changed
> > using
> > @@ -99,16 +118,18 @@ of a symbolic link can be changed using
> > or
> > .BR lutimes (3).
> > .PP
> > -On Linux, the permissions of a symbolic link are not used
> > -in any operations; the permissions are always
> > -0777 (read, write, and execute for all user categories),
> > .\" Linux does not currently implement an lchmod(2).
> > -and can't be changed.
> > -(Note that there are some "magic" symbolic links in the
> > -.I /proc
> > -directory tree\(emfor example, the
> > -.IR /proc/[pid]/fd/*
> > -files\(emthat have different permissions.)
> > +On Linux, the permissions of an ordinary symbolic link are not used in any
> > +operations; the permissions are always 0777 (read, write, and execute for all
> > +user categories), and can't be changed.
> > +.PP
> > +However, magic-links do not follow this rule. They can have a non-0777 mode,
> > +which is used for permission checks when the final
> > +component of an
> > +.BR open (2)'s
> > +path is a magic-link (see
> > +.BR path_resolution (7).)
> > +
> > .\"
> > .\" The
> > .\" 4.4BSD
--
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
<https://www.cyphar.com/>
Hi Aleksa,
Re our discussion of documentation to be added for magic symlinks,
there was the patch below, which got paused. I guess this just needs a
light refresh?
Thanks,
Michael
On Thu, 3 Oct 2019 at 16:56, Aleksa Sarai <[email protected]> wrote:
>
> Traditionally, magic-links have not been a well-understood topic in
> Linux. Given the new changes in their semantics (related to the link
> mode of trailing magic-links), it seems like a good opportunity to shine
> more light on magic-links and their semantics.
>
> Signed-off-by: Aleksa Sarai <[email protected]>
> ---
> man7/path_resolution.7 | 15 +++++++++++++++
> man7/symlink.7 | 39 ++++++++++++++++++++++++++++++---------
> 2 files changed, 45 insertions(+), 9 deletions(-)
>
> diff --git a/man7/path_resolution.7 b/man7/path_resolution.7
> index 07664ed8faec..46f25ec4cdfa 100644
> --- a/man7/path_resolution.7
> +++ b/man7/path_resolution.7
> @@ -136,6 +136,21 @@ we are just creating it.
> The details on the treatment
> of the final entry are described in the manual pages of the specific
> system calls.
> +.PP
> +Since Linux 5.FOO, if the final entry is a "magic-link" (see
> +.BR symlink (7)),
> +and the user is attempting to
> +.BR open (2)
> +it, then there is an additional permission-related restriction applied to the
> +operation: the requested access mode must not exceed the "link mode" of the
> +magic-link (unlike ordinary symlinks, magic-links have their own file mode.)
> +For example, if
> +.I /proc/[pid]/fd/[num]
> +has a link mode of
> +.BR 0500 ,
> +unprivileged users are not permitted to
> +.BR open ()
> +the magic-link for writing.
> .SS . and ..
> By convention, every directory has the entries "." and "..",
> which refer to the directory itself and to its parent directory,
> diff --git a/man7/symlink.7 b/man7/symlink.7
> index 9f5bddd5dc21..33f0ec703acd 100644
> --- a/man7/symlink.7
> +++ b/man7/symlink.7
> @@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
> are outlined here.
> It is important that site-local applications also conform to these rules,
> so that the user interface can be as consistent as possible.
> +.SS Magic-links
> +There is a special class of symlink-like objects known as "magic-links" which
> +can be found in certain pseudo-filesystems such as
> +.BR proc (5)
> +(examples include
> +.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
> +Unlike normal symlinks, magic-links are not resolved through
> +pathname-expansion, but instead act as direct references to the kernel's own
> +representation of a file handle. As such, these magic-links allow users to
> +access files which cannot be referenced with normal paths (such as unlinked
> +files still referenced by a running program.)
> +.PP
> +Because they can bypass ordinary
> +.BR mount_namespaces (7)-based
> +restrictions, magic-links have been used as attack vectors in various exploits.
> +As such (since Linux 5.FOO), there are additional restrictions placed on the
> +re-opening of magic-links (see
> +.BR path_resolution (7)
> +for more details.)
> .SS Symbolic link ownership, permissions, and timestamps
> The owner and group of an existing symbolic link can be changed
> using
> @@ -99,16 +118,18 @@ of a symbolic link can be changed using
> or
> .BR lutimes (3).
> .PP
> -On Linux, the permissions of a symbolic link are not used
> -in any operations; the permissions are always
> -0777 (read, write, and execute for all user categories),
> .\" Linux does not currently implement an lchmod(2).
> -and can't be changed.
> -(Note that there are some "magic" symbolic links in the
> -.I /proc
> -directory tree\(emfor example, the
> -.IR /proc/[pid]/fd/*
> -files\(emthat have different permissions.)
> +On Linux, the permissions of an ordinary symbolic link are not used in any
> +operations; the permissions are always 0777 (read, write, and execute for all
> +user categories), and can't be changed.
> +.PP
> +However, magic-links do not follow this rule. They can have a non-0777 mode,
> +which is used for permission checks when the final
> +component of an
> +.BR open (2)'s
> +path is a magic-link (see
> +.BR path_resolution (7).)
> +
> .\"
> .\" The
> .\" 4.4BSD
> --
> 2.23.0
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
On 2020-04-17, Michael Kerrisk (man-pages) <[email protected]> wrote:
> Hi Aleksa,
>
> Re our discussion of documentation to be added for magic symlinks,
> there was the patch below, which got paused. I guess this just needs a
> light refresh?
Yes, this is the patch I was thinking of -- but since the whole "magic
link mode" semantics weren't in the openat2() series that was merged,
this would need a refresh. Also I feel that magic-links probably deserve
a slightly longer explanation than I gave here.
> Thanks,
>
> Michael
>
> On Thu, 3 Oct 2019 at 16:56, Aleksa Sarai <[email protected]> wrote:
> >
> > Traditionally, magic-links have not been a well-understood topic in
> > Linux. Given the new changes in their semantics (related to the link
> > mode of trailing magic-links), it seems like a good opportunity to shine
> > more light on magic-links and their semantics.
> >
> > Signed-off-by: Aleksa Sarai <[email protected]>
> > ---
> > man7/path_resolution.7 | 15 +++++++++++++++
> > man7/symlink.7 | 39 ++++++++++++++++++++++++++++++---------
> > 2 files changed, 45 insertions(+), 9 deletions(-)
> >
> > diff --git a/man7/path_resolution.7 b/man7/path_resolution.7
> > index 07664ed8faec..46f25ec4cdfa 100644
> > --- a/man7/path_resolution.7
> > +++ b/man7/path_resolution.7
> > @@ -136,6 +136,21 @@ we are just creating it.
> > The details on the treatment
> > of the final entry are described in the manual pages of the specific
> > system calls.
> > +.PP
> > +Since Linux 5.FOO, if the final entry is a "magic-link" (see
> > +.BR symlink (7)),
> > +and the user is attempting to
> > +.BR open (2)
> > +it, then there is an additional permission-related restriction applied to the
> > +operation: the requested access mode must not exceed the "link mode" of the
> > +magic-link (unlike ordinary symlinks, magic-links have their own file mode.)
> > +For example, if
> > +.I /proc/[pid]/fd/[num]
> > +has a link mode of
> > +.BR 0500 ,
> > +unprivileged users are not permitted to
> > +.BR open ()
> > +the magic-link for writing.
> > .SS . and ..
> > By convention, every directory has the entries "." and "..",
> > which refer to the directory itself and to its parent directory,
> > diff --git a/man7/symlink.7 b/man7/symlink.7
> > index 9f5bddd5dc21..33f0ec703acd 100644
> > --- a/man7/symlink.7
> > +++ b/man7/symlink.7
> > @@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
> > are outlined here.
> > It is important that site-local applications also conform to these rules,
> > so that the user interface can be as consistent as possible.
> > +.SS Magic-links
> > +There is a special class of symlink-like objects known as "magic-links" which
> > +can be found in certain pseudo-filesystems such as
> > +.BR proc (5)
> > +(examples include
> > +.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
> > +Unlike normal symlinks, magic-links are not resolved through
> > +pathname-expansion, but instead act as direct references to the kernel's own
> > +representation of a file handle. As such, these magic-links allow users to
> > +access files which cannot be referenced with normal paths (such as unlinked
> > +files still referenced by a running program.)
> > +.PP
> > +Because they can bypass ordinary
> > +.BR mount_namespaces (7)-based
> > +restrictions, magic-links have been used as attack vectors in various exploits.
> > +As such (since Linux 5.FOO), there are additional restrictions placed on the
> > +re-opening of magic-links (see
> > +.BR path_resolution (7)
> > +for more details.)
> > .SS Symbolic link ownership, permissions, and timestamps
> > The owner and group of an existing symbolic link can be changed
> > using
> > @@ -99,16 +118,18 @@ of a symbolic link can be changed using
> > or
> > .BR lutimes (3).
> > .PP
> > -On Linux, the permissions of a symbolic link are not used
> > -in any operations; the permissions are always
> > -0777 (read, write, and execute for all user categories),
> > .\" Linux does not currently implement an lchmod(2).
> > -and can't be changed.
> > -(Note that there are some "magic" symbolic links in the
> > -.I /proc
> > -directory tree\(emfor example, the
> > -.IR /proc/[pid]/fd/*
> > -files\(emthat have different permissions.)
> > +On Linux, the permissions of an ordinary symbolic link are not used in any
> > +operations; the permissions are always 0777 (read, write, and execute for all
> > +user categories), and can't be changed.
> > +.PP
> > +However, magic-links do not follow this rule. They can have a non-0777 mode,
> > +which is used for permission checks when the final
> > +component of an
> > +.BR open (2)'s
> > +path is a magic-link (see
> > +.BR path_resolution (7).)
> > +
> > .\"
> > .\" The
> > .\" 4.4BSD
> > --
> > 2.23.0
> >
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/
--
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
<https://www.cyphar.com/>
Hi Aleksa,
Did you have a chance to look into writing this patch?
Thanks,
Michael
On Fri, 17 Apr 2020 at 17:37, Aleksa Sarai <[email protected]> wrote:
>
> On 2020-04-17, Michael Kerrisk (man-pages) <[email protected]> wrote:
> > Hi Aleksa,
> >
> > Re our discussion of documentation to be added for magic symlinks,
> > there was the patch below, which got paused. I guess this just needs a
> > light refresh?
>
> Yes, this is the patch I was thinking of -- but since the whole "magic
> link mode" semantics weren't in the openat2() series that was merged,
> this would need a refresh. Also I feel that magic-links probably deserve
> a slightly longer explanation than I gave here.
>
> > Thanks,
> >
> > Michael
> >
> > On Thu, 3 Oct 2019 at 16:56, Aleksa Sarai <[email protected]> wrote:
> > >
> > > Traditionally, magic-links have not been a well-understood topic in
> > > Linux. Given the new changes in their semantics (related to the link
> > > mode of trailing magic-links), it seems like a good opportunity to shine
> > > more light on magic-links and their semantics.
> > >
> > > Signed-off-by: Aleksa Sarai <[email protected]>
> > > ---
> > > man7/path_resolution.7 | 15 +++++++++++++++
> > > man7/symlink.7 | 39 ++++++++++++++++++++++++++++++---------
> > > 2 files changed, 45 insertions(+), 9 deletions(-)
> > >
> > > diff --git a/man7/path_resolution.7 b/man7/path_resolution.7
> > > index 07664ed8faec..46f25ec4cdfa 100644
> > > --- a/man7/path_resolution.7
> > > +++ b/man7/path_resolution.7
> > > @@ -136,6 +136,21 @@ we are just creating it.
> > > The details on the treatment
> > > of the final entry are described in the manual pages of the specific
> > > system calls.
> > > +.PP
> > > +Since Linux 5.FOO, if the final entry is a "magic-link" (see
> > > +.BR symlink (7)),
> > > +and the user is attempting to
> > > +.BR open (2)
> > > +it, then there is an additional permission-related restriction applied to the
> > > +operation: the requested access mode must not exceed the "link mode" of the
> > > +magic-link (unlike ordinary symlinks, magic-links have their own file mode.)
> > > +For example, if
> > > +.I /proc/[pid]/fd/[num]
> > > +has a link mode of
> > > +.BR 0500 ,
> > > +unprivileged users are not permitted to
> > > +.BR open ()
> > > +the magic-link for writing.
> > > .SS . and ..
> > > By convention, every directory has the entries "." and "..",
> > > which refer to the directory itself and to its parent directory,
> > > diff --git a/man7/symlink.7 b/man7/symlink.7
> > > index 9f5bddd5dc21..33f0ec703acd 100644
> > > --- a/man7/symlink.7
> > > +++ b/man7/symlink.7
> > > @@ -84,6 +84,25 @@ as they are implemented on Linux and other systems,
> > > are outlined here.
> > > It is important that site-local applications also conform to these rules,
> > > so that the user interface can be as consistent as possible.
> > > +.SS Magic-links
> > > +There is a special class of symlink-like objects known as "magic-links" which
> > > +can be found in certain pseudo-filesystems such as
> > > +.BR proc (5)
> > > +(examples include
> > > +.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* .)
> > > +Unlike normal symlinks, magic-links are not resolved through
> > > +pathname-expansion, but instead act as direct references to the kernel's own
> > > +representation of a file handle. As such, these magic-links allow users to
> > > +access files which cannot be referenced with normal paths (such as unlinked
> > > +files still referenced by a running program.)
> > > +.PP
> > > +Because they can bypass ordinary
> > > +.BR mount_namespaces (7)-based
> > > +restrictions, magic-links have been used as attack vectors in various exploits.
> > > +As such (since Linux 5.FOO), there are additional restrictions placed on the
> > > +re-opening of magic-links (see
> > > +.BR path_resolution (7)
> > > +for more details.)
> > > .SS Symbolic link ownership, permissions, and timestamps
> > > The owner and group of an existing symbolic link can be changed
> > > using
> > > @@ -99,16 +118,18 @@ of a symbolic link can be changed using
> > > or
> > > .BR lutimes (3).
> > > .PP
> > > -On Linux, the permissions of a symbolic link are not used
> > > -in any operations; the permissions are always
> > > -0777 (read, write, and execute for all user categories),
> > > .\" Linux does not currently implement an lchmod(2).
> > > -and can't be changed.
> > > -(Note that there are some "magic" symbolic links in the
> > > -.I /proc
> > > -directory tree\(emfor example, the
> > > -.IR /proc/[pid]/fd/*
> > > -files\(emthat have different permissions.)
> > > +On Linux, the permissions of an ordinary symbolic link are not used in any
> > > +operations; the permissions are always 0777 (read, write, and execute for all
> > > +user categories), and can't be changed.
> > > +.PP
> > > +However, magic-links do not follow this rule. They can have a non-0777 mode,
> > > +which is used for permission checks when the final
> > > +component of an
> > > +.BR open (2)'s
> > > +path is a magic-link (see
> > > +.BR path_resolution (7).)
> > > +
> > > .\"
> > > .\" The
> > > .\" 4.4BSD
> > > --
> > > 2.23.0
> > >
> >
> >
> > --
> > Michael Kerrisk
> > Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> > Linux/UNIX System Programming Training: http://man7.org/training/
>
>
> --
> Aleksa Sarai
> Senior Software Engineer (Containers)
> SUSE Linux GmbH
> <https://www.cyphar.com/>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/