Re: RFC: capabilities(7): notes for kernel developers

[Rafael J. Wysocki]

On Friday, December 16, 2016 01:16:15 PM John Stultz wrote:
> On Fri, Dec 16, 2016 at 1:05 PM, Serge E. Hallyn  wrote:
> > Quoting John Stultz (john.stu...@linaro.org):
> >> On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
> >> > Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
> >> >> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> >> >> > On 12/15/2016 4:31 PM, John Stultz wrote:
> >> >> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
> >> >> >>  wrote:
> >> >> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
> >> >>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> >> >> > CAP_WAKE_ALARM could readily be CAP_TIME.
> >> >>  Actually, I don't quite understand what you mean with that 
> >> >>  sentence.
> >> >>  Could you elaborate?
> >> >> >>> Should have said CAP_SYS_TIME
> >> >> >>>
> >> >> >>> Setting an alarm could be considered a time management function,
> >> >> >>> depending on what it actually does.
> >> >> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> >> >> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
> >> >> >> the time. One wouldn't necessarily want to give applications which
> >> >> >> could wake a system up the capability to also set the time.
> >> >> >
> >> >> > Doesn't really matter, except that an ignorant developer
> >> >> > might make the mistake I did and assume that WAKE_ALARM
> >> >> > was somehow related to time management. If you want to use
> >> >> > it as an example don't let my dunderheadedness get in your
> >> >> > way.
> >> >>
> >> >> Actually, I decided it wasn't such a good example anyway.
> >> >> That capability could potentially be generic. (But it probably
> >> >> should better have been named something like 'CAP_WAKE_SYSTEM'.)
> >> >
> >> > How about:
> >> >
> >> > Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to 
> >> > CAP_WAKE_ALARM
> >> >
> >> > As suggested by Michael Kerrisk his is a less confusing name, and
> >> > this won't break any old userspace.
> >> >
> >> > Signed-off-by: Serge Hallyn 
> >> > Cc: Michael Kerrisk 
> >> > ---
> >> >  include/uapi/linux/capability.h | 2 ++
> >> >  1 file changed, 2 insertions(+)
> >> >
> >> > diff --git a/include/uapi/linux/capability.h 
> >> > b/include/uapi/linux/capability.h
> >> > index fd4f87d..ba972ff 100644
> >> > --- a/include/uapi/linux/capability.h
> >> > +++ b/include/uapi/linux/capability.h
> >> > @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
> >> >
> >> >  #define CAP_WAKE_ALARM35
> >> >
> >> > +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> >> > +
> >>
> >> I was thinking of the same thing. Although I might rename the
> >> numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
> >> with a comment as to WAKE_ALARM being deprecated), so its more clear
> >> which is the one that ought to be used by new code.
> >>
> >> However, in the spirit of this thread, we might even consider
> >> broadening the cap silo a bit further, to something like
> >> CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
> >> actions?
> >
> > Or just CAP_UNSUSPEND?
> 
> I guess I was trying to capture it could be use for actions like both
> waking and suspending the system.

Well, CAP_SYS_PM comes to mind then.

Thanks,
Rafael

Re: RFC: capabilities(7): notes for kernel developers

[Rafael J. Wysocki]

On Friday, December 16, 2016 01:16:15 PM John Stultz wrote:
> On Fri, Dec 16, 2016 at 1:05 PM, Serge E. Hallyn  wrote:
> > Quoting John Stultz (john.stu...@linaro.org):
> >> On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
> >> > Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
> >> >> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> >> >> > On 12/15/2016 4:31 PM, John Stultz wrote:
> >> >> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
> >> >> >>  wrote:
> >> >> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
> >> >>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> >> >> > CAP_WAKE_ALARM could readily be CAP_TIME.
> >> >>  Actually, I don't quite understand what you mean with that 
> >> >>  sentence.
> >> >>  Could you elaborate?
> >> >> >>> Should have said CAP_SYS_TIME
> >> >> >>>
> >> >> >>> Setting an alarm could be considered a time management function,
> >> >> >>> depending on what it actually does.
> >> >> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> >> >> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
> >> >> >> the time. One wouldn't necessarily want to give applications which
> >> >> >> could wake a system up the capability to also set the time.
> >> >> >
> >> >> > Doesn't really matter, except that an ignorant developer
> >> >> > might make the mistake I did and assume that WAKE_ALARM
> >> >> > was somehow related to time management. If you want to use
> >> >> > it as an example don't let my dunderheadedness get in your
> >> >> > way.
> >> >>
> >> >> Actually, I decided it wasn't such a good example anyway.
> >> >> That capability could potentially be generic. (But it probably
> >> >> should better have been named something like 'CAP_WAKE_SYSTEM'.)
> >> >
> >> > How about:
> >> >
> >> > Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to 
> >> > CAP_WAKE_ALARM
> >> >
> >> > As suggested by Michael Kerrisk his is a less confusing name, and
> >> > this won't break any old userspace.
> >> >
> >> > Signed-off-by: Serge Hallyn 
> >> > Cc: Michael Kerrisk 
> >> > ---
> >> >  include/uapi/linux/capability.h | 2 ++
> >> >  1 file changed, 2 insertions(+)
> >> >
> >> > diff --git a/include/uapi/linux/capability.h 
> >> > b/include/uapi/linux/capability.h
> >> > index fd4f87d..ba972ff 100644
> >> > --- a/include/uapi/linux/capability.h
> >> > +++ b/include/uapi/linux/capability.h
> >> > @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
> >> >
> >> >  #define CAP_WAKE_ALARM35
> >> >
> >> > +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> >> > +
> >>
> >> I was thinking of the same thing. Although I might rename the
> >> numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
> >> with a comment as to WAKE_ALARM being deprecated), so its more clear
> >> which is the one that ought to be used by new code.
> >>
> >> However, in the spirit of this thread, we might even consider
> >> broadening the cap silo a bit further, to something like
> >> CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
> >> actions?
> >
> > Or just CAP_UNSUSPEND?
> 
> I guess I was trying to capture it could be use for actions like both
> waking and suspending the system.

Well, CAP_SYS_PM comes to mind then.

Thanks,
Rafael

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

On 12/16/2016 09:10 PM, Serge E. Hallyn wrote:
> Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
>> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
>>> On 12/15/2016 4:31 PM, John Stultz wrote:
 On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
  wrote:
> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>>> CAP_WAKE_ALARM could readily be CAP_TIME.
>> Actually, I don't quite understand what you mean with that sentence.
>> Could you elaborate?
> Should have said CAP_SYS_TIME
>
> Setting an alarm could be considered a time management function,
> depending on what it actually does.
 Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
 a system from suspend, while CAP_SYS_TIME covers the ability to set
 the time. One wouldn't necessarily want to give applications which
 could wake a system up the capability to also set the time.
>>>
>>> Doesn't really matter, except that an ignorant developer
>>> might make the mistake I did and assume that WAKE_ALARM
>>> was somehow related to time management. If you want to use
>>> it as an example don't let my dunderheadedness get in your
>>> way.
>>
>> Actually, I decided it wasn't such a good example anyway.
>> That capability could potentially be generic. (But it probably
>> should better have been named something like 'CAP_WAKE_SYSTEM'.)
> 
> How about:
> 
> Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
> 
> As suggested by Michael Kerrisk his is a less confusing name, and
> this won't break any old userspace.

Yes, but. The names are used in user-space: should cap_to_text() or
cap_from_text() be reworked to understand these new names? For the former,
it seems like a bad idea, and for the latter it's dubious I would say.
So, I'm concerned that renaming/adding a synonym at the API level 
creates some inconsistency with user-space. Maybe I worry too much?

What certainly would be good is to more clearly document the (broader)
purpose of the (misnamed) capability in capabilities(7). Something along
the lines of John's suggestion.

Cheers,

Michael

> Signed-off-by: Serge Hallyn 
> Cc: Michael Kerrisk 
> ---
>  include/uapi/linux/capability.h | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/include/uapi/linux/capability.h b/include/uapi/linux/capability.h
> index fd4f87d..ba972ff 100644
> --- a/include/uapi/linux/capability.h
> +++ b/include/uapi/linux/capability.h
> @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
>  
>  #define CAP_WAKE_ALARM35
>  
> +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> +
>  /* Allow preventing system suspends */
>  
>  #define CAP_BLOCK_SUSPEND36
> 


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

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

On 12/16/2016 09:10 PM, Serge E. Hallyn wrote:
> Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
>> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
>>> On 12/15/2016 4:31 PM, John Stultz wrote:
 On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
  wrote:
> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>>> CAP_WAKE_ALARM could readily be CAP_TIME.
>> Actually, I don't quite understand what you mean with that sentence.
>> Could you elaborate?
> Should have said CAP_SYS_TIME
>
> Setting an alarm could be considered a time management function,
> depending on what it actually does.
 Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
 a system from suspend, while CAP_SYS_TIME covers the ability to set
 the time. One wouldn't necessarily want to give applications which
 could wake a system up the capability to also set the time.
>>>
>>> Doesn't really matter, except that an ignorant developer
>>> might make the mistake I did and assume that WAKE_ALARM
>>> was somehow related to time management. If you want to use
>>> it as an example don't let my dunderheadedness get in your
>>> way.
>>
>> Actually, I decided it wasn't such a good example anyway.
>> That capability could potentially be generic. (But it probably
>> should better have been named something like 'CAP_WAKE_SYSTEM'.)
> 
> How about:
> 
> Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
> 
> As suggested by Michael Kerrisk his is a less confusing name, and
> this won't break any old userspace.

Yes, but. The names are used in user-space: should cap_to_text() or
cap_from_text() be reworked to understand these new names? For the former,
it seems like a bad idea, and for the latter it's dubious I would say.
So, I'm concerned that renaming/adding a synonym at the API level 
creates some inconsistency with user-space. Maybe I worry too much?

What certainly would be good is to more clearly document the (broader)
purpose of the (misnamed) capability in capabilities(7). Something along
the lines of John's suggestion.

Cheers,

Michael

> Signed-off-by: Serge Hallyn 
> Cc: Michael Kerrisk 
> ---
>  include/uapi/linux/capability.h | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/include/uapi/linux/capability.h b/include/uapi/linux/capability.h
> index fd4f87d..ba972ff 100644
> --- a/include/uapi/linux/capability.h
> +++ b/include/uapi/linux/capability.h
> @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
>  
>  #define CAP_WAKE_ALARM35
>  
> +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> +
>  /* Allow preventing system suspends */
>  
>  #define CAP_BLOCK_SUSPEND36
> 


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

Re: RFC: capabilities(7): notes for kernel developers

[John Stultz]

On Fri, Dec 16, 2016 at 1:05 PM, Serge E. Hallyn  wrote:
> Quoting John Stultz (john.stu...@linaro.org):
>> On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
>> > Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
>> >> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
>> >> > On 12/15/2016 4:31 PM, John Stultz wrote:
>> >> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>> >> >>  wrote:
>> >> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> >>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>> >> > CAP_WAKE_ALARM could readily be CAP_TIME.
>> >>  Actually, I don't quite understand what you mean with that sentence.
>> >>  Could you elaborate?
>> >> >>> Should have said CAP_SYS_TIME
>> >> >>>
>> >> >>> Setting an alarm could be considered a time management function,
>> >> >>> depending on what it actually does.
>> >> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
>> >> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
>> >> >> the time. One wouldn't necessarily want to give applications which
>> >> >> could wake a system up the capability to also set the time.
>> >> >
>> >> > Doesn't really matter, except that an ignorant developer
>> >> > might make the mistake I did and assume that WAKE_ALARM
>> >> > was somehow related to time management. If you want to use
>> >> > it as an example don't let my dunderheadedness get in your
>> >> > way.
>> >>
>> >> Actually, I decided it wasn't such a good example anyway.
>> >> That capability could potentially be generic. (But it probably
>> >> should better have been named something like 'CAP_WAKE_SYSTEM'.)
>> >
>> > How about:
>> >
>> > Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
>> >
>> > As suggested by Michael Kerrisk his is a less confusing name, and
>> > this won't break any old userspace.
>> >
>> > Signed-off-by: Serge Hallyn 
>> > Cc: Michael Kerrisk 
>> > ---
>> >  include/uapi/linux/capability.h | 2 ++
>> >  1 file changed, 2 insertions(+)
>> >
>> > diff --git a/include/uapi/linux/capability.h 
>> > b/include/uapi/linux/capability.h
>> > index fd4f87d..ba972ff 100644
>> > --- a/include/uapi/linux/capability.h
>> > +++ b/include/uapi/linux/capability.h
>> > @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
>> >
>> >  #define CAP_WAKE_ALARM35
>> >
>> > +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
>> > +
>>
>> I was thinking of the same thing. Although I might rename the
>> numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
>> with a comment as to WAKE_ALARM being deprecated), so its more clear
>> which is the one that ought to be used by new code.
>>
>> However, in the spirit of this thread, we might even consider
>> broadening the cap silo a bit further, to something like
>> CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
>> actions?
>
> Or just CAP_UNSUSPEND?

I guess I was trying to capture it could be use for actions like both
waking and suspending the system.

thanks
-john

Re: RFC: capabilities(7): notes for kernel developers

[John Stultz]

On Fri, Dec 16, 2016 at 1:05 PM, Serge E. Hallyn  wrote:
> Quoting John Stultz (john.stu...@linaro.org):
>> On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
>> > Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
>> >> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
>> >> > On 12/15/2016 4:31 PM, John Stultz wrote:
>> >> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>> >> >>  wrote:
>> >> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> >>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>> >> > CAP_WAKE_ALARM could readily be CAP_TIME.
>> >>  Actually, I don't quite understand what you mean with that sentence.
>> >>  Could you elaborate?
>> >> >>> Should have said CAP_SYS_TIME
>> >> >>>
>> >> >>> Setting an alarm could be considered a time management function,
>> >> >>> depending on what it actually does.
>> >> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
>> >> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
>> >> >> the time. One wouldn't necessarily want to give applications which
>> >> >> could wake a system up the capability to also set the time.
>> >> >
>> >> > Doesn't really matter, except that an ignorant developer
>> >> > might make the mistake I did and assume that WAKE_ALARM
>> >> > was somehow related to time management. If you want to use
>> >> > it as an example don't let my dunderheadedness get in your
>> >> > way.
>> >>
>> >> Actually, I decided it wasn't such a good example anyway.
>> >> That capability could potentially be generic. (But it probably
>> >> should better have been named something like 'CAP_WAKE_SYSTEM'.)
>> >
>> > How about:
>> >
>> > Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
>> >
>> > As suggested by Michael Kerrisk his is a less confusing name, and
>> > this won't break any old userspace.
>> >
>> > Signed-off-by: Serge Hallyn 
>> > Cc: Michael Kerrisk 
>> > ---
>> >  include/uapi/linux/capability.h | 2 ++
>> >  1 file changed, 2 insertions(+)
>> >
>> > diff --git a/include/uapi/linux/capability.h 
>> > b/include/uapi/linux/capability.h
>> > index fd4f87d..ba972ff 100644
>> > --- a/include/uapi/linux/capability.h
>> > +++ b/include/uapi/linux/capability.h
>> > @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
>> >
>> >  #define CAP_WAKE_ALARM35
>> >
>> > +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
>> > +
>>
>> I was thinking of the same thing. Although I might rename the
>> numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
>> with a comment as to WAKE_ALARM being deprecated), so its more clear
>> which is the one that ought to be used by new code.
>>
>> However, in the spirit of this thread, we might even consider
>> broadening the cap silo a bit further, to something like
>> CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
>> actions?
>
> Or just CAP_UNSUSPEND?

I guess I was trying to capture it could be use for actions like both
waking and suspending the system.

thanks
-john

Re: RFC: capabilities(7): notes for kernel developers

[Serge E. Hallyn]

Quoting John Stultz (john.stu...@linaro.org):
> On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
> > Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
> >> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> >> > On 12/15/2016 4:31 PM, John Stultz wrote:
> >> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
> >> >>  wrote:
> >> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
> >>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> >> > CAP_WAKE_ALARM could readily be CAP_TIME.
> >>  Actually, I don't quite understand what you mean with that sentence.
> >>  Could you elaborate?
> >> >>> Should have said CAP_SYS_TIME
> >> >>>
> >> >>> Setting an alarm could be considered a time management function,
> >> >>> depending on what it actually does.
> >> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> >> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
> >> >> the time. One wouldn't necessarily want to give applications which
> >> >> could wake a system up the capability to also set the time.
> >> >
> >> > Doesn't really matter, except that an ignorant developer
> >> > might make the mistake I did and assume that WAKE_ALARM
> >> > was somehow related to time management. If you want to use
> >> > it as an example don't let my dunderheadedness get in your
> >> > way.
> >>
> >> Actually, I decided it wasn't such a good example anyway.
> >> That capability could potentially be generic. (But it probably
> >> should better have been named something like 'CAP_WAKE_SYSTEM'.)
> >
> > How about:
> >
> > Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
> >
> > As suggested by Michael Kerrisk his is a less confusing name, and
> > this won't break any old userspace.
> >
> > Signed-off-by: Serge Hallyn 
> > Cc: Michael Kerrisk 
> > ---
> >  include/uapi/linux/capability.h | 2 ++
> >  1 file changed, 2 insertions(+)
> >
> > diff --git a/include/uapi/linux/capability.h 
> > b/include/uapi/linux/capability.h
> > index fd4f87d..ba972ff 100644
> > --- a/include/uapi/linux/capability.h
> > +++ b/include/uapi/linux/capability.h
> > @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
> >
> >  #define CAP_WAKE_ALARM35
> >
> > +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> > +
> 
> I was thinking of the same thing. Although I might rename the
> numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
> with a comment as to WAKE_ALARM being deprecated), so its more clear
> which is the one that ought to be used by new code.
> 
> However, in the spirit of this thread, we might even consider
> broadening the cap silo a bit further, to something like
> CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
> actions?

Or just CAP_UNSUSPEND?

Re: RFC: capabilities(7): notes for kernel developers

[Serge E. Hallyn]

Quoting John Stultz (john.stu...@linaro.org):
> On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
> > Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
> >> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> >> > On 12/15/2016 4:31 PM, John Stultz wrote:
> >> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
> >> >>  wrote:
> >> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
> >>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> >> > CAP_WAKE_ALARM could readily be CAP_TIME.
> >>  Actually, I don't quite understand what you mean with that sentence.
> >>  Could you elaborate?
> >> >>> Should have said CAP_SYS_TIME
> >> >>>
> >> >>> Setting an alarm could be considered a time management function,
> >> >>> depending on what it actually does.
> >> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> >> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
> >> >> the time. One wouldn't necessarily want to give applications which
> >> >> could wake a system up the capability to also set the time.
> >> >
> >> > Doesn't really matter, except that an ignorant developer
> >> > might make the mistake I did and assume that WAKE_ALARM
> >> > was somehow related to time management. If you want to use
> >> > it as an example don't let my dunderheadedness get in your
> >> > way.
> >>
> >> Actually, I decided it wasn't such a good example anyway.
> >> That capability could potentially be generic. (But it probably
> >> should better have been named something like 'CAP_WAKE_SYSTEM'.)
> >
> > How about:
> >
> > Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
> >
> > As suggested by Michael Kerrisk his is a less confusing name, and
> > this won't break any old userspace.
> >
> > Signed-off-by: Serge Hallyn 
> > Cc: Michael Kerrisk 
> > ---
> >  include/uapi/linux/capability.h | 2 ++
> >  1 file changed, 2 insertions(+)
> >
> > diff --git a/include/uapi/linux/capability.h 
> > b/include/uapi/linux/capability.h
> > index fd4f87d..ba972ff 100644
> > --- a/include/uapi/linux/capability.h
> > +++ b/include/uapi/linux/capability.h
> > @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
> >
> >  #define CAP_WAKE_ALARM35
> >
> > +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> > +
> 
> I was thinking of the same thing. Although I might rename the
> numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
> with a comment as to WAKE_ALARM being deprecated), so its more clear
> which is the one that ought to be used by new code.
> 
> However, in the spirit of this thread, we might even consider
> broadening the cap silo a bit further, to something like
> CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
> actions?

Or just CAP_UNSUSPEND?

Re: RFC: capabilities(7): notes for kernel developers

[John Stultz]

On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
> Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
>> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
>> > On 12/15/2016 4:31 PM, John Stultz wrote:
>> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>> >>  wrote:
>> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>> > CAP_WAKE_ALARM could readily be CAP_TIME.
>>  Actually, I don't quite understand what you mean with that sentence.
>>  Could you elaborate?
>> >>> Should have said CAP_SYS_TIME
>> >>>
>> >>> Setting an alarm could be considered a time management function,
>> >>> depending on what it actually does.
>> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
>> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
>> >> the time. One wouldn't necessarily want to give applications which
>> >> could wake a system up the capability to also set the time.
>> >
>> > Doesn't really matter, except that an ignorant developer
>> > might make the mistake I did and assume that WAKE_ALARM
>> > was somehow related to time management. If you want to use
>> > it as an example don't let my dunderheadedness get in your
>> > way.
>>
>> Actually, I decided it wasn't such a good example anyway.
>> That capability could potentially be generic. (But it probably
>> should better have been named something like 'CAP_WAKE_SYSTEM'.)
>
> How about:
>
> Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
>
> As suggested by Michael Kerrisk his is a less confusing name, and
> this won't break any old userspace.
>
> Signed-off-by: Serge Hallyn 
> Cc: Michael Kerrisk 
> ---
>  include/uapi/linux/capability.h | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/include/uapi/linux/capability.h b/include/uapi/linux/capability.h
> index fd4f87d..ba972ff 100644
> --- a/include/uapi/linux/capability.h
> +++ b/include/uapi/linux/capability.h
> @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
>
>  #define CAP_WAKE_ALARM35
>
> +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> +

I was thinking of the same thing. Although I might rename the
numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
with a comment as to WAKE_ALARM being deprecated), so its more clear
which is the one that ought to be used by new code.

However, in the spirit of this thread, we might even consider
broadening the cap silo a bit further, to something like
CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
actions?

thanks
-john

Re: RFC: capabilities(7): notes for kernel developers

[John Stultz]

On Fri, Dec 16, 2016 at 12:10 PM, Serge E. Hallyn  wrote:
> Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
>> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
>> > On 12/15/2016 4:31 PM, John Stultz wrote:
>> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>> >>  wrote:
>> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>> > CAP_WAKE_ALARM could readily be CAP_TIME.
>>  Actually, I don't quite understand what you mean with that sentence.
>>  Could you elaborate?
>> >>> Should have said CAP_SYS_TIME
>> >>>
>> >>> Setting an alarm could be considered a time management function,
>> >>> depending on what it actually does.
>> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
>> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
>> >> the time. One wouldn't necessarily want to give applications which
>> >> could wake a system up the capability to also set the time.
>> >
>> > Doesn't really matter, except that an ignorant developer
>> > might make the mistake I did and assume that WAKE_ALARM
>> > was somehow related to time management. If you want to use
>> > it as an example don't let my dunderheadedness get in your
>> > way.
>>
>> Actually, I decided it wasn't such a good example anyway.
>> That capability could potentially be generic. (But it probably
>> should better have been named something like 'CAP_WAKE_SYSTEM'.)
>
> How about:
>
> Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM
>
> As suggested by Michael Kerrisk his is a less confusing name, and
> this won't break any old userspace.
>
> Signed-off-by: Serge Hallyn 
> Cc: Michael Kerrisk 
> ---
>  include/uapi/linux/capability.h | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/include/uapi/linux/capability.h b/include/uapi/linux/capability.h
> index fd4f87d..ba972ff 100644
> --- a/include/uapi/linux/capability.h
> +++ b/include/uapi/linux/capability.h
> @@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
>
>  #define CAP_WAKE_ALARM35
>
> +#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
> +

I was thinking of the same thing. Although I might rename the
numerical define to WAKE_SYSTEM and put WAKE_ALARM as the alias (along
with a comment as to WAKE_ALARM being deprecated), so its more clear
which is the one that ought to be used by new code.

However, in the spirit of this thread, we might even consider
broadening the cap silo a bit further, to something like
CAP_WAKE_SUSPEND, such that it might also be able to cover broader PM
actions?

thanks
-john

Re: RFC: capabilities(7): notes for kernel developers

[Serge E. Hallyn]

Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> > On 12/15/2016 4:31 PM, John Stultz wrote:
> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
> >>  wrote:
> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> > CAP_WAKE_ALARM could readily be CAP_TIME.
>  Actually, I don't quite understand what you mean with that sentence.
>  Could you elaborate?
> >>> Should have said CAP_SYS_TIME
> >>>
> >>> Setting an alarm could be considered a time management function,
> >>> depending on what it actually does.
> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
> >> the time. One wouldn't necessarily want to give applications which
> >> could wake a system up the capability to also set the time.
> > 
> > Doesn't really matter, except that an ignorant developer
> > might make the mistake I did and assume that WAKE_ALARM
> > was somehow related to time management. If you want to use
> > it as an example don't let my dunderheadedness get in your
> > way.
> 
> Actually, I decided it wasn't such a good example anyway.
> That capability could potentially be generic. (But it probably
> should better have been named something like 'CAP_WAKE_SYSTEM'.)

How about:

Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM

As suggested by Michael Kerrisk his is a less confusing name, and
this won't break any old userspace.

Signed-off-by: Serge Hallyn 
Cc: Michael Kerrisk 
---
 include/uapi/linux/capability.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/uapi/linux/capability.h b/include/uapi/linux/capability.h
index fd4f87d..ba972ff 100644
--- a/include/uapi/linux/capability.h
+++ b/include/uapi/linux/capability.h
@@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
 
 #define CAP_WAKE_ALARM35
 
+#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
+
 /* Allow preventing system suspends */
 
 #define CAP_BLOCK_SUSPEND36
-- 
2.7.4

Re: RFC: capabilities(7): notes for kernel developers

[Serge E. Hallyn]

Quoting Michael Kerrisk (man-pages) (mtk.manpa...@gmail.com):
> On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> > On 12/15/2016 4:31 PM, John Stultz wrote:
> >> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
> >>  wrote:
> >>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>  On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> > CAP_WAKE_ALARM could readily be CAP_TIME.
>  Actually, I don't quite understand what you mean with that sentence.
>  Could you elaborate?
> >>> Should have said CAP_SYS_TIME
> >>>
> >>> Setting an alarm could be considered a time management function,
> >>> depending on what it actually does.
> >> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> >> a system from suspend, while CAP_SYS_TIME covers the ability to set
> >> the time. One wouldn't necessarily want to give applications which
> >> could wake a system up the capability to also set the time.
> > 
> > Doesn't really matter, except that an ignorant developer
> > might make the mistake I did and assume that WAKE_ALARM
> > was somehow related to time management. If you want to use
> > it as an example don't let my dunderheadedness get in your
> > way.
> 
> Actually, I decided it wasn't such a good example anyway.
> That capability could potentially be generic. (But it probably
> should better have been named something like 'CAP_WAKE_SYSTEM'.)

How about:

Subject: [PATCH 1/1] capabilities: alias CAP_WAKE_SYSTEM to CAP_WAKE_ALARM

As suggested by Michael Kerrisk his is a less confusing name, and
this won't break any old userspace.

Signed-off-by: Serge Hallyn 
Cc: Michael Kerrisk 
---
 include/uapi/linux/capability.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/uapi/linux/capability.h b/include/uapi/linux/capability.h
index fd4f87d..ba972ff 100644
--- a/include/uapi/linux/capability.h
+++ b/include/uapi/linux/capability.h
@@ -357,6 +357,8 @@ struct vfs_ns_cap_data {
 
 #define CAP_WAKE_ALARM35
 
+#define CAP_WAKE_SYSTEM  CAP_WAKE_ALARM
+
 /* Allow preventing system suspends */
 
 #define CAP_BLOCK_SUSPEND36
-- 
2.7.4

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

On 12/15/2016 09:40 PM, Casey Schaufler wrote:
> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> Hello Casey,
>>
>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>>> On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:

[...]

*  To determine which existing capability might best be associated
   with your new feature, review the list of capabilities above in
   order to find a "silo" into which your new feature best fits.
>>> One approach to take is to determine if there are other features
>>> requiring capabilities that will always be use along with the
>>> new feature. If the new feature is useless without these other
>>> features, you should use the same capability as the other features.
>> Thanks, I've lifted those words exactly as you gave them into the man page.
>>
*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
   vast  proportion  of  existing capability checks are associated
   with this capability, to the point where it  can  plausibly  be
   called "the new root".  Don't make the problem worse.  The only
   new features that should be associated with  CAP_SYS_ADMIN  are
   ones that closely match existing uses in that silo.
>>> I don't agree with this advice. Use CAP_SYS_ADMIN if you are
>>> preforming system administration functions. Odds are very good
>>> that if a program is using one system administration feature
>>> it will be using others. 
>> Really? To me, the CAP_SYS_ADMIN situation is a terrible mess.  Around a
>> third of all of the capability checks in the kernel are for that
>> capability. Or, to put it another way, it is so broad, that if a process
>> has to have that capability, it may as well be root.  And because it is
>> so broad, the number of binaries that might need that file capability is
>> large. (See also https://lwn.net/Articles/486306/)
> 
> Back in the days of the POSIX P1003.1e/2c working group
> we struggled with what to do about the things that required
> privilege but that were not related to the enforcement of
> security policy. Everyone involved was looking to use
> capabilities to meet B2* least privilege requirements in
> NSA security evaluations. Because those evaluations where
> of security policy, by far the easiest thing to do was to
> create a single capability for all the things that didn't
> show up in the security policy and declare that the people
> doing the evaluation didn't have to look over there. Since
> then, people have taken a more practical view that includes
> security relevance in addition to security policy.

Ahhh -- thanks for a bit of the history! Helps me to
understand a bit more why things are as they are...

> In retrospect we should have grouped all of the attribute
> changes (chmod, chown, ...) into one capability and broken
> the non-policy actions into a set on 2 or three.
> 
> The way that we think of privilege has evolved. We're not
> focused on policy the way we used to be. We'll never get
> everyone to agree on what the *right* granularity and
> grouping is, either.

:-)

> -
> * The B2 least privilege requirements are amusing.
>   If you want more information, look up "TCSEC orange book".

Maybe one day...

[...]

Cheers,

Mcihael


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

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

On 12/15/2016 09:40 PM, Casey Schaufler wrote:
> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> Hello Casey,
>>
>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>>> On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:

[...]

*  To determine which existing capability might best be associated
   with your new feature, review the list of capabilities above in
   order to find a "silo" into which your new feature best fits.
>>> One approach to take is to determine if there are other features
>>> requiring capabilities that will always be use along with the
>>> new feature. If the new feature is useless without these other
>>> features, you should use the same capability as the other features.
>> Thanks, I've lifted those words exactly as you gave them into the man page.
>>
*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
   vast  proportion  of  existing capability checks are associated
   with this capability, to the point where it  can  plausibly  be
   called "the new root".  Don't make the problem worse.  The only
   new features that should be associated with  CAP_SYS_ADMIN  are
   ones that closely match existing uses in that silo.
>>> I don't agree with this advice. Use CAP_SYS_ADMIN if you are
>>> preforming system administration functions. Odds are very good
>>> that if a program is using one system administration feature
>>> it will be using others. 
>> Really? To me, the CAP_SYS_ADMIN situation is a terrible mess.  Around a
>> third of all of the capability checks in the kernel are for that
>> capability. Or, to put it another way, it is so broad, that if a process
>> has to have that capability, it may as well be root.  And because it is
>> so broad, the number of binaries that might need that file capability is
>> large. (See also https://lwn.net/Articles/486306/)
> 
> Back in the days of the POSIX P1003.1e/2c working group
> we struggled with what to do about the things that required
> privilege but that were not related to the enforcement of
> security policy. Everyone involved was looking to use
> capabilities to meet B2* least privilege requirements in
> NSA security evaluations. Because those evaluations where
> of security policy, by far the easiest thing to do was to
> create a single capability for all the things that didn't
> show up in the security policy and declare that the people
> doing the evaluation didn't have to look over there. Since
> then, people have taken a more practical view that includes
> security relevance in addition to security policy.

Ahhh -- thanks for a bit of the history! Helps me to
understand a bit more why things are as they are...

> In retrospect we should have grouped all of the attribute
> changes (chmod, chown, ...) into one capability and broken
> the non-policy actions into a set on 2 or three.
> 
> The way that we think of privilege has evolved. We're not
> focused on policy the way we used to be. We'll never get
> everyone to agree on what the *right* granularity and
> grouping is, either.

:-)

> -
> * The B2 least privilege requirements are amusing.
>   If you want more information, look up "TCSEC orange book".

Maybe one day...

[...]

Cheers,

Mcihael


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

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> On 12/15/2016 4:31 PM, John Stultz wrote:
>> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>>  wrote:
>>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
 On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> CAP_WAKE_ALARM could readily be CAP_TIME.
 Actually, I don't quite understand what you mean with that sentence.
 Could you elaborate?
>>> Should have said CAP_SYS_TIME
>>>
>>> Setting an alarm could be considered a time management function,
>>> depending on what it actually does.
>> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
>> a system from suspend, while CAP_SYS_TIME covers the ability to set
>> the time. One wouldn't necessarily want to give applications which
>> could wake a system up the capability to also set the time.
> 
> Doesn't really matter, except that an ignorant developer
> might make the mistake I did and assume that WAKE_ALARM
> was somehow related to time management. If you want to use
> it as an example don't let my dunderheadedness get in your
> way.

Actually, I decided it wasn't such a good example anyway.
That capability could potentially be generic. (But it probably
should better have been named something like 'CAP_WAKE_SYSTEM'.)

>> thanks
>> -john
> 
> Again, thank you for taking this on. It should be a
> big help.

You're welcome. And thanks for your help, Casey.

Cheers,

Michael


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

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

On 12/16/2016 01:44 AM, Casey Schaufler wrote:
> On 12/15/2016 4:31 PM, John Stultz wrote:
>> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>>  wrote:
>>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
 On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> CAP_WAKE_ALARM could readily be CAP_TIME.
 Actually, I don't quite understand what you mean with that sentence.
 Could you elaborate?
>>> Should have said CAP_SYS_TIME
>>>
>>> Setting an alarm could be considered a time management function,
>>> depending on what it actually does.
>> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
>> a system from suspend, while CAP_SYS_TIME covers the ability to set
>> the time. One wouldn't necessarily want to give applications which
>> could wake a system up the capability to also set the time.
> 
> Doesn't really matter, except that an ignorant developer
> might make the mistake I did and assume that WAKE_ALARM
> was somehow related to time management. If you want to use
> it as an example don't let my dunderheadedness get in your
> way.

Actually, I decided it wasn't such a good example anyway.
That capability could potentially be generic. (But it probably
should better have been named something like 'CAP_WAKE_SYSTEM'.)

>> thanks
>> -john
> 
> Again, thank you for taking this on. It should be a
> big help.

You're welcome. And thanks for your help, Casey.

Cheers,

Michael


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

Re: RFC: capabilities(7): notes for kernel developers

[Casey Schaufler]

On 12/15/2016 4:31 PM, John Stultz wrote:
> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>  wrote:
>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
 CAP_WAKE_ALARM could readily be CAP_TIME.
>>> Actually, I don't quite understand what you mean with that sentence.
>>> Could you elaborate?
>> Should have said CAP_SYS_TIME
>>
>> Setting an alarm could be considered a time management function,
>> depending on what it actually does.
> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> a system from suspend, while CAP_SYS_TIME covers the ability to set
> the time. One wouldn't necessarily want to give applications which
> could wake a system up the capability to also set the time.

Doesn't really matter, except that an ignorant developer
might make the mistake I did and assume that WAKE_ALARM
was somehow related to time management. If you want to use
it as an example don't let my dunderheadedness get in your
way.

> thanks
> -john

Again, thank you for taking this on. It should be a
big help.

Re: RFC: capabilities(7): notes for kernel developers

[Casey Schaufler]

On 12/15/2016 4:31 PM, John Stultz wrote:
> On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
>  wrote:
>> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
 CAP_WAKE_ALARM could readily be CAP_TIME.
>>> Actually, I don't quite understand what you mean with that sentence.
>>> Could you elaborate?
>> Should have said CAP_SYS_TIME
>>
>> Setting an alarm could be considered a time management function,
>> depending on what it actually does.
> Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
> a system from suspend, while CAP_SYS_TIME covers the ability to set
> the time. One wouldn't necessarily want to give applications which
> could wake a system up the capability to also set the time.

Doesn't really matter, except that an ignorant developer
might make the mistake I did and assume that WAKE_ALARM
was somehow related to time management. If you want to use
it as an example don't let my dunderheadedness get in your
way.

> thanks
> -john

Again, thank you for taking this on. It should be a
big help.

Re: RFC: capabilities(7): notes for kernel developers

[John Stultz]

On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
 wrote:
> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>>> CAP_WAKE_ALARM could readily be CAP_TIME.
>> Actually, I don't quite understand what you mean with that sentence.
>> Could you elaborate?
>
> Should have said CAP_SYS_TIME
>
> Setting an alarm could be considered a time management function,
> depending on what it actually does.

Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
a system from suspend, while CAP_SYS_TIME covers the ability to set
the time. One wouldn't necessarily want to give applications which
could wake a system up the capability to also set the time.

thanks
-john

Re: RFC: capabilities(7): notes for kernel developers

[John Stultz]

On Thu, Dec 15, 2016 at 12:40 PM, Casey Schaufler
 wrote:
> On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
>> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>>> CAP_WAKE_ALARM could readily be CAP_TIME.
>> Actually, I don't quite understand what you mean with that sentence.
>> Could you elaborate?
>
> Should have said CAP_SYS_TIME
>
> Setting an alarm could be considered a time management function,
> depending on what it actually does.

Just a nit here. CAP_WAKE_ALARM is more about the privilege of waking
a system from suspend, while CAP_SYS_TIME covers the ability to set
the time. One wouldn't necessarily want to give applications which
could wake a system up the capability to also set the time.

thanks
-john

Re: RFC: capabilities(7): notes for kernel developers

[Casey Schaufler]

On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
> Hello Casey,
>
> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>> On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:
>>> Hello all,
>>>
>>> Because the topic every now then comes up "which capability 
>>> should I associate with the new feature that I'm adding to 
>>> the kernel?", I propose to add the text below to the 
>>> capabilities(7) man page [1] with some recommendations
>>> on how to go about choosing. I would be happy
>>> to get feedback, suggestions for improvement and
>>> so on.
>> Thank you. This is long overdue.
>>
>>> Cheers,
>>>
>>> Michael
>>>
>>> [1] http://man7.org/linux/man-pages/man7/capabilities.7.html
>>>
>>>
>>>Notes to kernel developers
>>>When adding a new kernel feature that  should  be  governed  by  a
>>>capability, consider the following points.
>>>
>>>*  The  goal of capabilities is divide the power of superuser into
>>>   small pieces, such that if a program that has  capabilities  is
>> I wouldn't say "small". Small implies many, and we want to
>> keep the number of capabilities manageable.
> Fixed.
>
>>>   compromised, its power to do damage to the system would be much
>>>   less than a similar set-user-ID-root program.
>> Not "much less", just less.
> Fixed.
>
>> Change "similar set-user-ID-root program" to "the same program
>> running with root privilege".
> Fixed.
>
>>>*  You have the choice of either creating  a  new  capability  for
>>>   your  new  feature,  or associating the feature with one of the
>>>   existing capabilities.  Because the size of capability sets  is
>>>   currently  limited to 64 bits, the latter option is preferable,
>> The reason is not the size of the set being limited, it is
>> that a large set of capabilities would be unmanageable. The
>> fact that someone is reading this is sufficient evidence of
>> that.
> Yep. Reworked to cover this point.
>
>>>   unless there are compelling reasons to take the former option.
>>>
>>>*  To determine which existing capability might best be associated
>>>   with your new feature, review the list of capabilities above in
>>>   order to find a "silo" into which your new feature best fits.
>> One approach to take is to determine if there are other features
>> requiring capabilities that will always be use along with the
>> new feature. If the new feature is useless without these other
>> features, you should use the same capability as the other features.
> Thanks, I've lifted those words exactly as you gave them into the man page.
>
>>>*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
>>>   vast  proportion  of  existing capability checks are associated
>>>   with this capability, to the point where it  can  plausibly  be
>>>   called "the new root".  Don't make the problem worse.  The only
>>>   new features that should be associated with  CAP_SYS_ADMIN  are
>>>   ones that closely match existing uses in that silo.
>> I don't agree with this advice. Use CAP_SYS_ADMIN if you are
>> preforming system administration functions. Odds are very good
>> that if a program is using one system administration feature
>> it will be using others. 
> Really? To me, the CAP_SYS_ADMIN situation is a terrible mess.  Around a
> third of all of the capability checks in the kernel are for that
> capability. Or, to put it another way, it is so broad, that if a process
> has to have that capability, it may as well be root.  And because it is
> so broad, the number of binaries that might need that file capability is
> large. (See also https://lwn.net/Articles/486306/)

Back in the days of the POSIX P1003.1e/2c working group
we struggled with what to do about the things that required
privilege but that were not related to the enforcement of
security policy. Everyone involved was looking to use
capabilities to meet B2* least privilege requirements in
NSA security evaluations. Because those evaluations where
of security policy, by far the easiest thing to do was to
create a single capability for all the things that didn't
show up in the security policy and declare that the people
doing the evaluation didn't have to look over there. Since
then, people have taken a more practical view that includes
security relevance in addition to security policy.

In retrospect we should have grouped all of the attribute
changes (chmod, chown, ...) into one capability and broken
the non-policy actions into a set on 2 or three.

The way that we think of privilege has evolved. We're not
focused on policy the way we used to be. We'll never get
everyone to agree on what the *right* granularity and
grouping is, either.

-
* The B2 least privilege requirements are amusing.
  If you want more information, look up "TCSEC orange book".

> Here's an *incomplete* list of (from capabilities(7)) of what
> 

Re: RFC: capabilities(7): notes for kernel developers

[Casey Schaufler]

On 12/15/2016 11:41 AM, Michael Kerrisk (man-pages) wrote:
> Hello Casey,
>
> On 12/15/2016 05:29 PM, Casey Schaufler wrote:
>> On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:
>>> Hello all,
>>>
>>> Because the topic every now then comes up "which capability 
>>> should I associate with the new feature that I'm adding to 
>>> the kernel?", I propose to add the text below to the 
>>> capabilities(7) man page [1] with some recommendations
>>> on how to go about choosing. I would be happy
>>> to get feedback, suggestions for improvement and
>>> so on.
>> Thank you. This is long overdue.
>>
>>> Cheers,
>>>
>>> Michael
>>>
>>> [1] http://man7.org/linux/man-pages/man7/capabilities.7.html
>>>
>>>
>>>Notes to kernel developers
>>>When adding a new kernel feature that  should  be  governed  by  a
>>>capability, consider the following points.
>>>
>>>*  The  goal of capabilities is divide the power of superuser into
>>>   small pieces, such that if a program that has  capabilities  is
>> I wouldn't say "small". Small implies many, and we want to
>> keep the number of capabilities manageable.
> Fixed.
>
>>>   compromised, its power to do damage to the system would be much
>>>   less than a similar set-user-ID-root program.
>> Not "much less", just less.
> Fixed.
>
>> Change "similar set-user-ID-root program" to "the same program
>> running with root privilege".
> Fixed.
>
>>>*  You have the choice of either creating  a  new  capability  for
>>>   your  new  feature,  or associating the feature with one of the
>>>   existing capabilities.  Because the size of capability sets  is
>>>   currently  limited to 64 bits, the latter option is preferable,
>> The reason is not the size of the set being limited, it is
>> that a large set of capabilities would be unmanageable. The
>> fact that someone is reading this is sufficient evidence of
>> that.
> Yep. Reworked to cover this point.
>
>>>   unless there are compelling reasons to take the former option.
>>>
>>>*  To determine which existing capability might best be associated
>>>   with your new feature, review the list of capabilities above in
>>>   order to find a "silo" into which your new feature best fits.
>> One approach to take is to determine if there are other features
>> requiring capabilities that will always be use along with the
>> new feature. If the new feature is useless without these other
>> features, you should use the same capability as the other features.
> Thanks, I've lifted those words exactly as you gave them into the man page.
>
>>>*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
>>>   vast  proportion  of  existing capability checks are associated
>>>   with this capability, to the point where it  can  plausibly  be
>>>   called "the new root".  Don't make the problem worse.  The only
>>>   new features that should be associated with  CAP_SYS_ADMIN  are
>>>   ones that closely match existing uses in that silo.
>> I don't agree with this advice. Use CAP_SYS_ADMIN if you are
>> preforming system administration functions. Odds are very good
>> that if a program is using one system administration feature
>> it will be using others. 
> Really? To me, the CAP_SYS_ADMIN situation is a terrible mess.  Around a
> third of all of the capability checks in the kernel are for that
> capability. Or, to put it another way, it is so broad, that if a process
> has to have that capability, it may as well be root.  And because it is
> so broad, the number of binaries that might need that file capability is
> large. (See also https://lwn.net/Articles/486306/)

Back in the days of the POSIX P1003.1e/2c working group
we struggled with what to do about the things that required
privilege but that were not related to the enforcement of
security policy. Everyone involved was looking to use
capabilities to meet B2* least privilege requirements in
NSA security evaluations. Because those evaluations where
of security policy, by far the easiest thing to do was to
create a single capability for all the things that didn't
show up in the security policy and declare that the people
doing the evaluation didn't have to look over there. Since
then, people have taken a more practical view that includes
security relevance in addition to security policy.

In retrospect we should have grouped all of the attribute
changes (chmod, chown, ...) into one capability and broken
the non-policy actions into a set on 2 or three.

The way that we think of privilege has evolved. We're not
focused on policy the way we used to be. We'll never get
everyone to agree on what the *right* granularity and
grouping is, either.

-
* The B2 least privilege requirements are amusing.
  If you want more information, look up "TCSEC orange book".

> Here's an *incomplete* list of (from capabilities(7)) of what
> 

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

Hello Casey,

On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:
>> Hello all,
>>
>> Because the topic every now then comes up "which capability 
>> should I associate with the new feature that I'm adding to 
>> the kernel?", I propose to add the text below to the 
>> capabilities(7) man page [1] with some recommendations
>> on how to go about choosing. I would be happy
>> to get feedback, suggestions for improvement and
>> so on.
> 
> Thank you. This is long overdue.
> 
>> Cheers,
>>
>> Michael
>>
>> [1] http://man7.org/linux/man-pages/man7/capabilities.7.html
>>
>>
>>Notes to kernel developers
>>When adding a new kernel feature that  should  be  governed  by  a
>>capability, consider the following points.
>>
>>*  The  goal of capabilities is divide the power of superuser into
>>   small pieces, such that if a program that has  capabilities  is
> 
> I wouldn't say "small". Small implies many, and we want to
> keep the number of capabilities manageable.

Fixed.

>>   compromised, its power to do damage to the system would be much
>>   less than a similar set-user-ID-root program.
> 
> Not "much less", just less.

Fixed.

> Change "similar set-user-ID-root program" to "the same program
> running with root privilege".

Fixed.

>>*  You have the choice of either creating  a  new  capability  for
>>   your  new  feature,  or associating the feature with one of the
>>   existing capabilities.  Because the size of capability sets  is
>>   currently  limited to 64 bits, the latter option is preferable,
> 
> The reason is not the size of the set being limited, it is
> that a large set of capabilities would be unmanageable. The
> fact that someone is reading this is sufficient evidence of
> that.

Yep. Reworked to cover this point.

>>   unless there are compelling reasons to take the former option.
>>
>>*  To determine which existing capability might best be associated
>>   with your new feature, review the list of capabilities above in
>>   order to find a "silo" into which your new feature best fits.
> 
> One approach to take is to determine if there are other features
> requiring capabilities that will always be use along with the
> new feature. If the new feature is useless without these other
> features, you should use the same capability as the other features.

Thanks, I've lifted those words exactly as you gave them into the man page.

>>*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
>>   vast  proportion  of  existing capability checks are associated
>>   with this capability, to the point where it  can  plausibly  be
>>   called "the new root".  Don't make the problem worse.  The only
>>   new features that should be associated with  CAP_SYS_ADMIN  are
>>   ones that closely match existing uses in that silo.
> 
> I don't agree with this advice. Use CAP_SYS_ADMIN if you are
> preforming system administration functions. Odds are very good
> that if a program is using one system administration feature
> it will be using others. 

Really? To me, the CAP_SYS_ADMIN situation is a terrible mess.  Around a
third of all of the capability checks in the kernel are for that
capability. Or, to put it another way, it is so broad, that if a process
has to have that capability, it may as well be root.  And because it is
so broad, the number of binaries that might need that file capability is
large. (See also https://lwn.net/Articles/486306/)

Here's an *incomplete* list of (from capabilities(7)) of what
CAP_SYS_ADMIN allows:

  * Perform a range of system administration operations including:
quotactl(2),   mount(2),   umount(2),  swapon(2),  swapoff(2),
sethostname(2), and setdomainname(2);
  * perform privileged syslog(2) operations (since  Linux  2.6.37,
CAP_SYSLOG should be used to permit such operations);
  * perform VM86_REQUEST_IRQ vm86(2) command;
  * perform  IPC_SET and IPC_RMID operations on arbitrary System V
IPC objects;
  * override RLIMIT_NPROC resource limit;
  * perform operations on trusted and security Extended Attributes
(see xattr(7));
  * use lookup_dcookie(2);
  * use  ioprio_set(2) to assign IOPRIO_CLASS_RT and (before Linux
2.6.25) IOPRIO_CLASS_IDLE I/O scheduling classes;
  * forge PID when passing  socket  credentials  via  UNIX  domain
sockets;
  * exceed  /proc/sys/fs/file-max,  the  system-wide  limit on the
number of open files, in system calls that open  files  (e.g.,
accept(2), execve(2), open(2), pipe(2));
  * employ  CLONE_* flags that create new namespaces with clone(2)
and unshare(2) (but, since Linux 3.8, creating user namespaces
does not require any capability);
  * call perf_event_open(2);
  * access privileged perf event information;
  * call  setns(2)  (requires  CAP_SYS_ADMIN  in the target names‐
   

Re: RFC: capabilities(7): notes for kernel developers

[Michael Kerrisk (man-pages)]

Hello Casey,

On 12/15/2016 05:29 PM, Casey Schaufler wrote:
> On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:
>> Hello all,
>>
>> Because the topic every now then comes up "which capability 
>> should I associate with the new feature that I'm adding to 
>> the kernel?", I propose to add the text below to the 
>> capabilities(7) man page [1] with some recommendations
>> on how to go about choosing. I would be happy
>> to get feedback, suggestions for improvement and
>> so on.
> 
> Thank you. This is long overdue.
> 
>> Cheers,
>>
>> Michael
>>
>> [1] http://man7.org/linux/man-pages/man7/capabilities.7.html
>>
>>
>>Notes to kernel developers
>>When adding a new kernel feature that  should  be  governed  by  a
>>capability, consider the following points.
>>
>>*  The  goal of capabilities is divide the power of superuser into
>>   small pieces, such that if a program that has  capabilities  is
> 
> I wouldn't say "small". Small implies many, and we want to
> keep the number of capabilities manageable.

Fixed.

>>   compromised, its power to do damage to the system would be much
>>   less than a similar set-user-ID-root program.
> 
> Not "much less", just less.

Fixed.

> Change "similar set-user-ID-root program" to "the same program
> running with root privilege".

Fixed.

>>*  You have the choice of either creating  a  new  capability  for
>>   your  new  feature,  or associating the feature with one of the
>>   existing capabilities.  Because the size of capability sets  is
>>   currently  limited to 64 bits, the latter option is preferable,
> 
> The reason is not the size of the set being limited, it is
> that a large set of capabilities would be unmanageable. The
> fact that someone is reading this is sufficient evidence of
> that.

Yep. Reworked to cover this point.

>>   unless there are compelling reasons to take the former option.
>>
>>*  To determine which existing capability might best be associated
>>   with your new feature, review the list of capabilities above in
>>   order to find a "silo" into which your new feature best fits.
> 
> One approach to take is to determine if there are other features
> requiring capabilities that will always be use along with the
> new feature. If the new feature is useless without these other
> features, you should use the same capability as the other features.

Thanks, I've lifted those words exactly as you gave them into the man page.

>>*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
>>   vast  proportion  of  existing capability checks are associated
>>   with this capability, to the point where it  can  plausibly  be
>>   called "the new root".  Don't make the problem worse.  The only
>>   new features that should be associated with  CAP_SYS_ADMIN  are
>>   ones that closely match existing uses in that silo.
> 
> I don't agree with this advice. Use CAP_SYS_ADMIN if you are
> preforming system administration functions. Odds are very good
> that if a program is using one system administration feature
> it will be using others. 

Really? To me, the CAP_SYS_ADMIN situation is a terrible mess.  Around a
third of all of the capability checks in the kernel are for that
capability. Or, to put it another way, it is so broad, that if a process
has to have that capability, it may as well be root.  And because it is
so broad, the number of binaries that might need that file capability is
large. (See also https://lwn.net/Articles/486306/)

Here's an *incomplete* list of (from capabilities(7)) of what
CAP_SYS_ADMIN allows:

  * Perform a range of system administration operations including:
quotactl(2),   mount(2),   umount(2),  swapon(2),  swapoff(2),
sethostname(2), and setdomainname(2);
  * perform privileged syslog(2) operations (since  Linux  2.6.37,
CAP_SYSLOG should be used to permit such operations);
  * perform VM86_REQUEST_IRQ vm86(2) command;
  * perform  IPC_SET and IPC_RMID operations on arbitrary System V
IPC objects;
  * override RLIMIT_NPROC resource limit;
  * perform operations on trusted and security Extended Attributes
(see xattr(7));
  * use lookup_dcookie(2);
  * use  ioprio_set(2) to assign IOPRIO_CLASS_RT and (before Linux
2.6.25) IOPRIO_CLASS_IDLE I/O scheduling classes;
  * forge PID when passing  socket  credentials  via  UNIX  domain
sockets;
  * exceed  /proc/sys/fs/file-max,  the  system-wide  limit on the
number of open files, in system calls that open  files  (e.g.,
accept(2), execve(2), open(2), pipe(2));
  * employ  CLONE_* flags that create new namespaces with clone(2)
and unshare(2) (but, since Linux 3.8, creating user namespaces
does not require any capability);
  * call perf_event_open(2);
  * access privileged perf event information;
  * call  setns(2)  (requires  CAP_SYS_ADMIN  in the target names‐
   

Re: RFC: capabilities(7): notes for kernel developers

[Casey Schaufler]

On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:
> Hello all,
>
> Because the topic every now then comes up "which capability 
> should I associate with the new feature that I'm adding to 
> the kernel?", I propose to add the text below to the 
> capabilities(7) man page [1] with some recommendations
> on how to go about choosing. I would be happy
> to get feedback, suggestions for improvement and
> so on.

Thank you. This is long overdue.

> Cheers,
>
> Michael
>
> [1] http://man7.org/linux/man-pages/man7/capabilities.7.html
>
>
>Notes to kernel developers
>When adding a new kernel feature that  should  be  governed  by  a
>capability, consider the following points.
>
>*  The  goal of capabilities is divide the power of superuser into
>   small pieces, such that if a program that has  capabilities  is

I wouldn't say "small". Small implies many, and we want to
keep the number of capabilities manageable.

>   compromised, its power to do damage to the system would be much
>   less than a similar set-user-ID-root program.

Not "much less", just less.
Change "similar set-user-ID-root program" to "the same program
running with root privilege".
 

>*  You have the choice of either creating  a  new  capability  for
>   your  new  feature,  or associating the feature with one of the
>   existing capabilities.  Because the size of capability sets  is
>   currently  limited to 64 bits, the latter option is preferable,

The reason is not the size of the set being limited, it is
that a large set of capabilities would be unmanageable. The
fact that someone is reading this is sufficient evidence of
that.

>   unless there are compelling reasons to take the former option.
>
>*  To determine which existing capability might best be associated
>   with your new feature, review the list of capabilities above in
>   order to find a "silo" into which your new feature best fits.

One approach to take is to determine if there are other features
requiring capabilities that will always be use along with the
new feature. If the new feature is useless without these other
features, you should use the same capability as the other features.

>*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
>   vast  proportion  of  existing capability checks are associated
>   with this capability, to the point where it  can  plausibly  be
>   called "the new root".  Don't make the problem worse.  The only
>   new features that should be associated with  CAP_SYS_ADMIN  are
>   ones that closely match existing uses in that silo.

I don't agree with this advice. Use CAP_SYS_ADMIN if you are
preforming system administration functions. Odds are very good
that if a program is using one system administration feature
it will be using others. 

>*  If  you have determined that it really is necessary to create a
>   new capability for your feature, avoid making (and  naming)  it
>   as  a "single-use" capability.

Be strong. Don't say "avoid making (and naming)", say "don't make or name".
We can't allow single use capabilities. If we did that we'd have thousands
of capabilities. It's hard enough to get developers to use a coarse set of
capabilities.

>   Thus, for example, the addition
>   of the highly specific CAP_WAKE_ALARM was probably  a  mistake.
>   Instead,  try  to  identify  and  name your new capability as a
>   broader silo into which other related future  use  cases  might
>   fit.

Need a better example. CAP_WAKE_ALARM could readily be CAP_TIME.

Re: RFC: capabilities(7): notes for kernel developers

[Casey Schaufler]

On 12/15/2016 3:40 AM, Michael Kerrisk (man-pages) wrote:
> Hello all,
>
> Because the topic every now then comes up "which capability 
> should I associate with the new feature that I'm adding to 
> the kernel?", I propose to add the text below to the 
> capabilities(7) man page [1] with some recommendations
> on how to go about choosing. I would be happy
> to get feedback, suggestions for improvement and
> so on.

Thank you. This is long overdue.

> Cheers,
>
> Michael
>
> [1] http://man7.org/linux/man-pages/man7/capabilities.7.html
>
>
>Notes to kernel developers
>When adding a new kernel feature that  should  be  governed  by  a
>capability, consider the following points.
>
>*  The  goal of capabilities is divide the power of superuser into
>   small pieces, such that if a program that has  capabilities  is

I wouldn't say "small". Small implies many, and we want to
keep the number of capabilities manageable.

>   compromised, its power to do damage to the system would be much
>   less than a similar set-user-ID-root program.

Not "much less", just less.
Change "similar set-user-ID-root program" to "the same program
running with root privilege".
 

>*  You have the choice of either creating  a  new  capability  for
>   your  new  feature,  or associating the feature with one of the
>   existing capabilities.  Because the size of capability sets  is
>   currently  limited to 64 bits, the latter option is preferable,

The reason is not the size of the set being limited, it is
that a large set of capabilities would be unmanageable. The
fact that someone is reading this is sufficient evidence of
that.

>   unless there are compelling reasons to take the former option.
>
>*  To determine which existing capability might best be associated
>   with your new feature, review the list of capabilities above in
>   order to find a "silo" into which your new feature best fits.

One approach to take is to determine if there are other features
requiring capabilities that will always be use along with the
new feature. If the new feature is useless without these other
features, you should use the same capability as the other features.

>*  Don't choose CAP_SYS_ADMIN if you can  possibly  avoid  it!   A
>   vast  proportion  of  existing capability checks are associated
>   with this capability, to the point where it  can  plausibly  be
>   called "the new root".  Don't make the problem worse.  The only
>   new features that should be associated with  CAP_SYS_ADMIN  are
>   ones that closely match existing uses in that silo.

I don't agree with this advice. Use CAP_SYS_ADMIN if you are
preforming system administration functions. Odds are very good
that if a program is using one system administration feature
it will be using others. 

>*  If  you have determined that it really is necessary to create a
>   new capability for your feature, avoid making (and  naming)  it
>   as  a "single-use" capability.

Be strong. Don't say "avoid making (and naming)", say "don't make or name".
We can't allow single use capabilities. If we did that we'd have thousands
of capabilities. It's hard enough to get developers to use a coarse set of
capabilities.

>   Thus, for example, the addition
>   of the highly specific CAP_WAKE_ALARM was probably  a  mistake.
>   Instead,  try  to  identify  and  name your new capability as a
>   broader silo into which other related future  use  cases  might
>   fit.

Need a better example. CAP_WAKE_ALARM could readily be CAP_TIME.