Re: [PATCH man-pages v2 2/2] openat2.2: document new openat2(2) syscall

Hello Aleksa,

On 4/12/20 6:49 PM, Aleksa Sarai wrote:

Sorry, I could've sworn I responded when you posted this -- comments
below. And sorry for not getting back to you before the 5.06 release.

No worries and ahanks for your feedback below.

[...]

quoted

quoted

quoted

.\" FIXME I find the "previously-functional systems" in the previous
.\" sentence a little odd (since openat2() ia new sysycall), so I would
.\" like to clarify a little...
.\" Are you referring to the scenario where someone might take an
.\" existing application that uses openat() and replaces the uses
.\" of openat() with openat2()? In which case, is it correct to
.\" understand that you mean that one should not just indiscriminately
.\" add the RESOLVE_NO_XDEV flag to all of the openat2() calls?
.\" If I'm not on the right track, could you point me in the right
.\" direction please.

This is mostly meant as a warning to hopefully avoid applications
because the developer didn't realise that system paths may contain
symlinks or bind-mounts. For an application which has switched to
openat2() and then uses RESOLVE_NO_SYMLINKS for a non-security reason,
it's possible that on some distributions (or future versions of a
distribution) that their application will stop working because a system
path suddenly contains a symlink or is a bind-mount.

This was a concern which was brought up on LWN some time ago. If you can
think of a phrasing that makes this more clear, I'd appreciate it.

Thanks. I've made the text:

                     Applications  that  employ  the RESOLVE_NO_XDEV flag
                     are encouraged to make its use configurable  (unless
                     it is used for a specific security purpose), as bind
                     mounts are widely used by end-users.   Setting  this
                     flag indiscriminately—i.e., for purposes not specif‐
                     ically related to security—for all uses of openat2()
                     may  result  in  spurious errors on previously-func‐
                     tional systems.  This may occur if, for  example,  a
                     system  pathname  that  is used by an application is
                     modified (e.g., in a new  distribution  release)  so
                     that  a  pathname  component  (now)  contains a bind
                     mount.

Okay?

Yup,

Thanks.

and the same text should be used for the same warning I gave for
RESOLVE_NO_SYMLINKS (for the same reason, because system paths may
switch to symlinks -- the prime example being what Arch Linux did
several years ago).

Okay -- I added similar text to RESOLVE_NO_SYMLINKS.

quoted

quoted

quoted

.\" FIXME: what specific details in symlink(7) are being referred
.\" by the following sentence? It's not clear.

The section on magic-links, but you're right that the sentence ordering
is a bit odd. It should probably go after the first sentence.

I must admit that I'm still confused. There's only the briefest of 
mentions of magic links in symlink(7). Perhaps that needs to be fixed?

It wouldn't hurt to add a longer description of magic-links in
symlink(7). I'll send you a small patch to beef up the description (I
had planned to include a longer rewrite with the O_EMPTYPATH patches but
those require quite a bit more work to land).

That would be great. Thank you!

quoted

And, while I think of it, the text just preceding that FIXME says:

    Due to the potential danger of unknowingly opening 
    these magic links, it may be preferable for users to 
    disable their resolution entirely.

This sentence reads a little strangely. Could you please give me some
concrete examples, and I will try rewording that sentence a bit.

The primary example is that certain files (such as tty devices) are
best not opened by an unsuspecting program (if you do not have a
controlling TTY, and you open such a file that console becomes your
controlling TTY unless you use O_NOCTTY).

But more generally, magic-links allow programs to be "beamed" all over
the system (bypassing ordinary mount namespace restrictions). Since they
are fairly rarely used intentionally by most programs, this is more of a
tip to programmers that maybe they should play it safe and disallow
magic-links unless they are expecting to have to use them.

I've reworked the text on RESOLVE_NO_MAGICLINKS substantially:

       RESOLVE_NO_MAGICLINKS
              Disallow all magic-link resolution during path reso‐
              lution.

              Magic links are symbolic link-like objects that  are
              most  notably  found  in  proc(5);  examples include
              /proc/[pid]/exe  and  /proc/[pid]/fd/*.   (See  sym‐
              link(7) for more details.)

              Unknowingly  opening  magic  links  can be risky for
              some applications.  Examples of such  risks  include
              the following:

              · If the process opening a pathname is a controlling
                process that currently has no controlling terminal
                (see  credentials(7)),  then  opening a magic link
                inside /proc/[pid]/fd that happens to refer  to  a
                terminal would cause the process to acquire a con‐
                trolling terminal.

              · In  a  containerized  environment,  a  magic  link
                inside  /proc  may  refer to an object outside the
                container, and thus may provide a means to  escape
                from the container.

[The above example derives from https://lwn.net/Articles/796868/]

              Because  of such risks, an application may prefer to
              disable   magic   link    resolution    using    the
              RESOLVE_NO_MAGICLINKS flag.

              If  the trailing component (i.e., basename) of path‐
              name is a magic link, and  how.flags  contains  both
              O_PATH  and O_NOFOLLOW, then an O_PATH file descrip‐
              tor referencing the magic link will be returned.

How does the above look?

Also, regarding the last paragraph, I  have a question.  The
text doesn't seem quite to relate to the rest of the discussion.
Should it be saying something like:

If the trailing component (i.e., basename) of pathname is a magic link,
**how.resolve contains RESOLVE_NO_MAGICLINKS,**
and how.flags contains both O_PATH and O_NOFOLLOW, then an O_PATH
file descriptor referencing the magic link will be returned.

?

[...]

quoted

quoted

quoted

.\" FIXME The next piece is unclear (to me). What kind of ".." escape
.\" attempts does chroot() not detect that RESOLVE_IN_ROOT does?

If the root is moved, you can escape from a chroot(2). But this sentence
might not really belong in a man-page since it's describing (important)
aspects of the implementation and not the semantics.

So, should I just remove the sentence?

Yup, sounds reasonable.

Done.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/