[12/15] Manual pages: cap_get_file.3: NOTES: note the effect of the Ambient set
diff mbox series

Message ID 20200720091328.290336-13-mtk.manpages@gmail.com
State New
Headers show
Series
  • Manual pages: various fixes
Related show

Commit Message

Michael Kerrisk (man-pages) July 20, 2020, 9:13 a.m. UTC
The addition of Ambient capabilities in Linux 4.3 rendered the text on
the effect of the Effective bit during execve(2) out-of-date. Fix that.
Also add a couple of paragraph breaks to improve readability.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 doc/cap_get_file.3 | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

Comments

Andrew G. Morgan July 20, 2020, 3:36 p.m. UTC | #1
I've applied all but this one. This one seems to imply that if the
effective bit is lowered, but the permitted bits are raised, the
ambient will have some sort of effect. This isn't how it works. Any
file caps (even an empty set) suppresses any effect of the ambient
vector.

Cheers

Andrew

On Mon, Jul 20, 2020 at 2:14 AM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> The addition of Ambient capabilities in Linux 4.3 rendered the text on
> the effect of the Effective bit during execve(2) out-of-date. Fix that.
> Also add a couple of paragraph breaks to improve readability.
>
> Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
> ---
>  doc/cap_get_file.3 | 11 ++++++++---
>  1 file changed, 8 insertions(+), 3 deletions(-)
>
> diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
> index ceacbaf..dc7b571 100644
> --- a/doc/cap_get_file.3
> +++ b/doc/cap_get_file.3
> @@ -103,13 +103,18 @@ or
>  These functions are specified by withdrawn POSIX.1e draft specification.
>  .SH NOTES
>  Support for file capabilities is provided on Linux since version 2.6.24.
> -
> +.PP
>  On Linux, the file Effective set is a single bit.
>  If it is enabled, then all Permitted capabilities are enabled
>  in the Effective set of the calling process when the file is executed;
> -otherwise, no capabilities are enabled in the process's Effective set
> +otherwise, the process's Ambient capabilities
> +(or, before the Linux 4.3 addition of Ambient capabilities, no capabilities)
> +are enabled in the process's Effective set
>  following an
> -.BR execve (2).
> +.BR execve (2)
> +(see
> +.BR capabilities (7)).
> +.PP
>  Because the file Effective set is a single bit,
>  if any capability is enabled in the Effective set of the
>  .I cap_t
> --
> 2.26.2
>
Michael Kerrisk (man-pages) July 20, 2020, 8:21 p.m. UTC | #2
Hi Andrew,

On Mon, 20 Jul 2020 at 17:36, Andrew G. Morgan <morgan@kernel.org> wrote:
>
> I've applied all but this one. This one seems to imply that if the
> effective bit is lowered, but the permitted bits are raised, the
> ambient will have some sort of effect. This isn't how it works. Any
> file caps (even an empty set) suppresses any effect of the ambient
> vector.

Thanks for catching that. I was trying to capture this piece of the
execve() transformation rules:

P'(effective)   = F(effective) ? P'(permitted) : P'(ambient)

But of course, I failed to capture the detail that it is the process's
*new* ambient set (which, as you note, is cleared if the file has any
attached capabilities) that is assigned to the effective set. Perhaps
the text is best left as is. If I have some better idea, I'll come
back to you.

Thanks,

Michael

> On Mon, Jul 20, 2020 at 2:14 AM Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
> >
> > The addition of Ambient capabilities in Linux 4.3 rendered the text on
> > the effect of the Effective bit during execve(2) out-of-date. Fix that.
> > Also add a couple of paragraph breaks to improve readability.
> >
> > Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
> > ---
> >  doc/cap_get_file.3 | 11 ++++++++---
> >  1 file changed, 8 insertions(+), 3 deletions(-)
> >
> > diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
> > index ceacbaf..dc7b571 100644
> > --- a/doc/cap_get_file.3
> > +++ b/doc/cap_get_file.3
> > @@ -103,13 +103,18 @@ or
> >  These functions are specified by withdrawn POSIX.1e draft specification.
> >  .SH NOTES
> >  Support for file capabilities is provided on Linux since version 2.6.24.
> > -
> > +.PP
> >  On Linux, the file Effective set is a single bit.
> >  If it is enabled, then all Permitted capabilities are enabled
> >  in the Effective set of the calling process when the file is executed;
> > -otherwise, no capabilities are enabled in the process's Effective set
> > +otherwise, the process's Ambient capabilities
> > +(or, before the Linux 4.3 addition of Ambient capabilities, no capabilities)
> > +are enabled in the process's Effective set
> >  following an
> > -.BR execve (2).
> > +.BR execve (2)
> > +(see
> > +.BR capabilities (7)).
> > +.PP
> >  Because the file Effective set is a single bit,
> >  if any capability is enabled in the Effective set of the
> >  .I cap_t
> > --
> > 2.26.2
> >

Patch
diff mbox series

diff --git a/doc/cap_get_file.3 b/doc/cap_get_file.3
index ceacbaf..dc7b571 100644
--- a/doc/cap_get_file.3
+++ b/doc/cap_get_file.3
@@ -103,13 +103,18 @@  or
 These functions are specified by withdrawn POSIX.1e draft specification.
 .SH NOTES
 Support for file capabilities is provided on Linux since version 2.6.24.
-
+.PP
 On Linux, the file Effective set is a single bit.
 If it is enabled, then all Permitted capabilities are enabled
 in the Effective set of the calling process when the file is executed;
-otherwise, no capabilities are enabled in the process's Effective set
+otherwise, the process's Ambient capabilities
+(or, before the Linux 4.3 addition of Ambient capabilities, no capabilities)
+are enabled in the process's Effective set
 following an
-.BR execve (2).
+.BR execve (2)
+(see
+.BR capabilities (7)).
+.PP
 Because the file Effective set is a single bit,
 if any capability is enabled in the Effective set of the
 .I cap_t