[PATCH] Document how capability bits work

[PATCH] Document how capability bits work

[Andy Lutomirski]

Signed-off-by: Andy Lutomirski <luto@amacapital.net>
---
 Documentation/security/capabilities.txt | 161 ++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 Documentation/security/capabilities.txt

diff --git a/Documentation/security/capabilities.txt b/Documentation/security/capabilities.txt
new file mode 100644
index 0000000..dc7bc34
--- /dev/null
+++ b/Documentation/security/capabilities.txt
@@ -0,0 +1,161 @@
+			  Linux capabilities
+
+
+==== What are capabilities ====
+
+Various system calls check for appropriate privileges.  For example, a program
+may bypass normal file permission checking if it has the CAP_DAC_OVERRIDE
+capability.  There are a lot of capabilities; the complete list is in
+include/uapi/linux/capability.h.
+
+When reading this description, do not assume anything about the word
+"inheritable".  It probably does not do what you expect.
+
+Every task has the following pieces of capability-related state.
+
+ * Four capability bit masks:
+   * The effective set (pE).  Privileged operations check this set.
+   * The permitted set (pP).  Tasks may set these bits in pE.
+   * The inheritable set (pI).  This set is complicated.
+   * The bounding set (pB).  This partially limits new permitted capabilities.
+
+ * Secure bits.  Each bit has a corresponding "lock" bit.
+   * SECURE_NONROOT: Makes uid==0 and euid==0 less special at exec time.
+   * SECURE_KEEP_CAPS: Prevents setresuid() from removing permitted caps.
+   * SECURE_NO_SETUID_FIXUP: Makes setresuid() entirely nonmagical.
+
+ * no_new_privs: See Documentation/prctl/no_new_privs.txt
+
+There is one invariant: pE ⊆ pP.
+
+In addition, files can have capabilities.  If a file has capabilities, it
+specifies two masks and one bit:
+ * fP: The permitted or forced set.
+ * fI: The inheritable set.
+ * fE (a single bit): Supposedly true for "legacy" programs.
+
+libcap's setcap tool pretends that fE is a bitmask.  It's not.
+
+At the most basic level, only pE matters.  All of the complexity is in how
+pE and the other masks can change.  (This is a slight lie -- user namespaces
+change this.)
+
+==== System calls ====
+
+Capabilities and related state are affected by these syscalls:
+ * capset: Change capabilities directly.
+ * set[res]uid: Sometimes changes capabilities for legacy compatibility.
+ * prctl(PR_SET_KEEPCAPS): Used to twiddle SECURE_KEEP_CAPS.
+ * prctl(PR_SET_SECUREBITS): Used to twiddle securebits in general.
+ * prctl(PR_SET_NO_NEW_PRIVS): Used to set no_new_privs.
+ * prctl(PR_CAPBSET_DROP): Used to remove bits from pB.
+ * execve: Does all kinds of magic.
+
+==== capset ====
+
+capset changes pI, pP, and pE as requested, subject to:
+
+ - (CAP_SETPCAP ∈ pE or euid is namespace owner) or pI' ⊆ pI | pP
+ - pI' ⊆ pI | pB
+ - pP' ⊆ pP
+ - pE' ⊆ pE
+
+In the event that pI ⊆ pB, the first two conditions simplify to pI' ⊆ pI | pP.
+
+==== set*uid ====
+
+After set[res]uid, if !SECURE_NO_SETUID_FIXUP, a fixup happens.  This fixup
+does two things:
+
+ - If !SECURE_KEEP_CAPS and some old uid was 0 and no new uid is 0, then
+   pP and pE are cleared.
+ - If euid becomes zero, the pE = pP.  Conversely, if euid becomes nonzero,
+   then pE' = 0.  (Note that this is independent of SECURE_KEEP_CAPS.)
+
+setfsuid has similar logic to tweak the fs-related pE bits.
+
+====  prctl ====
+
+---- PR_SET_KEEPCAPS ----
+
+This changes SECURE_KEEP_CAPS as long as !SECURE_KEEP_CAPS_LOCKED.
+CAP_SETPCAP is not required.
+
+---- PR_SET_SECUREBITS ----
+
+This changes securebits, subject to:
+ - The caller must have CAP_SETPCAP.
+ - The *_LOCKED bits can be set but not cleared.
+ - A locked bit cannot be changed.
+
+Note that an unprivileged process can change SECURE_KEEP_CAPS via
+PR_SET_KEEPCAPS but not via PR_SET_SECUREBITS.
+
+---- PR_SET_NO_NEW_PRIVS ----
+
+Sets the no_new_privs bit.  No privilege is required.  It is impossible
+to clear the no_new_privs bit.
+
+---- PR_CAPBSET_DROP ----
+
+Clears a single bit of pB.  Doing this requires CAP_SETPCAP.  There is no
+way to set a cleared bit of pB.
+
+==== execve ====
+
+execve's behavior is rather complicated.  It does this:
+
+Step 1: Load fI, fP, and fE.  If the file has no capabilities (the xattr
+is malformed or absent), then set fI = 0, fP = 0, and fE = false.  (In theory,
+fE is set on "legacy" binaries that don't know how to check their own
+capability sets.)
+
+Step 2: Apply the basic pP update rule:
+
+   pP' = (pB & fP) | (pI & fI)
+
+Step 3: If fE and pP ⊈ fP, then abort.  (This prevents legacy binaries from
+malfunctioning dangerously if pB is missing important bits.)
+
+Step 4: Apply a fixup for root if !SECURE_NOROOT.  The fixup is:
+
+ - If vfs caps were present, uid != 0, and euid == 0, then warn once per boot.
+ - Otherwise:
+   - If euid == 0 or uid == 0, then pP' = pB | pI.
+   - If euid == 0, then set fE = true.  (This does not affect the check
+      in step 2.)
+
+Step 5: Apply no_new_privs
+
+If no_new_privs is set (or if new euid != old uid or new egit != old gid and
+an unprivileged ptracer is attached), then set euid = uid, egid = gid,
+and set pP' = pP' & pP.  (Note: If CAP_SETUID is effective (in the old context)
+and no_new_privs is not set, then the euid and egid changes are skipped.)
+
+Step 6: Compute pE
+
+If fE, then pE' = pP'.  Else pE' = 0.
+
+Step 7: Clear SECURE_KEEP_CAPS.
+
+This happens regardless of the setting of SECURE_KEEP_CAPS_LOCKED.  Setting
+SECURE_KEEP_CAPS_LOCKED is therefore probably a mistake unless
+SECURE_NO_SETUID_FIXUP is set.
+
+
+In the absence of something like no_new_privs, then either
+
+pP' = (pB & fP) | (pI & fI)  (the normal case)
+
+or
+
+pP' = pB | pI (if euid or uid == 0)
+
+The latter condition means that, if euid or uid is zero, then execve acts
+(in part) as though fP = fI = <all bits set>.
+
+
+The upshot: pI bits can result in actual (pP or pE) privilege if you exec a
+program that has that fI bit set *or* you have !issecure(SECURE_NOROOT) and
+(euid == 0 || uid == 0).  (That latter case is possibly better understood
+as promoting pB bits to pP.)
-- 
1.7.11.7

Re: [PATCH] Document how capability bits work

[Serge Hallyn]

Quoting Andy Lutomirski (luto@amacapital.net):
> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
> ---
>  Documentation/security/capabilities.txt | 161 ++++++++++++++++++++++++++++++++
>  1 file changed, 161 insertions(+)
>  create mode 100644 Documentation/security/capabilities.txt

TBH, I think a pointer to the capabilities.7 man page would be better.
(plus, if you feel they are needed, updates to the man page)

(I'll refrain from detailed review of the contents until this is
discussed.)

-serge

Re: [PATCH] Document how capability bits work

[Andy Lutomirski]

On Fri, Dec 7, 2012 at 11:21 AM, Serge Hallyn
<serge.hallyn@canonical.com> wrote:
> Quoting Andy Lutomirski (luto@amacapital.net):
>> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
>> ---
>>  Documentation/security/capabilities.txt | 161 ++++++++++++++++++++++++++++++++
>>  1 file changed, 161 insertions(+)
>>  create mode 100644 Documentation/security/capabilities.txt
>
> TBH, I think a pointer to the capabilities.7 man page would be better.
> (plus, if you feel they are needed, updates to the man page)

Updating capabilities.7 wouldn't be a bad idea, but IMO it certainly
needs work.  For example, it says:

       Inheritable:
              This is a set of capabilities preserved across an execve(2).  It
              provides a mechanism for a process to assign capabilities to the
              permitted set of the new program during an execve(2).

This is, at best, misleading.

Permitted says:

              If  a  thread  drops a capability from its permitted set, it can
              never reacquire that capability (unless it execve(2)s  either  a
              set-user-ID-root  program,  or  a  program whose associated file
              capabilities grant that capability).

That's just not true (e.g. if uid == 0).

The text later on is better, but I think it would be helpful to have a
detailed and succinct description of what's going on.

I would be happy to revise this patch to reference capabilities.7.

--Andy

Re: [PATCH] Document how capability bits work

[Rob Landley]

On 12/07/2012 01:32:18 PM, Andy Lutomirski wrote:
> On Fri, Dec 7, 2012 at 11:21 AM, Serge Hallyn
> <serge.hallyn@canonical.com> wrote:
> > Quoting Andy Lutomirski (luto@amacapital.net):
> >> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
> >> ---
> >>  Documentation/security/capabilities.txt | 161  
> ++++++++++++++++++++++++++++++++
> >>  1 file changed, 161 insertions(+)
> >>  create mode 100644 Documentation/security/capabilities.txt
> >
> > TBH, I think a pointer to the capabilities.7 man page would be  
> better.
> > (plus, if you feel they are needed, updates to the man page)
> 
> Updating capabilities.7 wouldn't be a bad idea, but IMO it certainly
> needs work.  For example, it says:
...
> I would be happy to revise this patch to reference capabilities.7.

The capabilities.7 man page is existing maintained documentation on how  
to use this from userspace, which seems to be the point of your  
document. Having include/linux/uapi/capability.h mention its existence  
might be good. Feeding fixes to the documentation we've already got  
would be good.

I read your document having largely ignored capabilities for years, and  
don't feel I have a better understanding of them after reading it. (I'm  
aware they exist, I'm aware they're used as a justification for  
extended attributes, I'm aware people think breaking a fireplace into a  
bunch of candleflames increases fire safety. I'm aware of  
http://forums.grsecurity.net/viewtopic.php?f=7&t=2522 and I _used_ to  
be aware of  
http://userweb.kernel.org/~morgan/sendmail-capabilities-war-story.html  
but kernel.org never bothered putting most of itself back together  
after the breakin last year and archive.org doesn't have a copy. I'm  
aware that a decade ago at Atlanta Linux Showcase in california Ted Tso  
was sad nobody was using them yet. But I haven't hugely been tracking  
changes over the last 5 years in how they work. It looks like figuring  
out who has what involves working through exercises in set theory that  
cannot be explained using a 127 bit ascii set. Personally, I prefer  
"more dangerous" security setups that don't require I pull out scratch  
paper to reason about the state of the system, so perhaps I'm biased  
here.)

Rob

Re: [PATCH] Document how capability bits work

[Andy Lutomirski]

On Fri, Dec 7, 2012 at 5:10 PM, Rob Landley <rob@landley.net> wrote:
> On 12/07/2012 01:32:18 PM, Andy Lutomirski wrote:
>>
>> On Fri, Dec 7, 2012 at 11:21 AM, Serge Hallyn
>> <serge.hallyn@canonical.com> wrote:
>> > Quoting Andy Lutomirski (luto@amacapital.net):
>> >> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
>> >> ---
>> >>  Documentation/security/capabilities.txt | 161
>> >> ++++++++++++++++++++++++++++++++
>> >>  1 file changed, 161 insertions(+)
>> >>  create mode 100644 Documentation/security/capabilities.txt
>> >
>> > TBH, I think a pointer to the capabilities.7 man page would be better.
>> > (plus, if you feel they are needed, updates to the man page)
>>
>> Updating capabilities.7 wouldn't be a bad idea, but IMO it certainly
>> needs work.  For example, it says:
>
> ...
>
>> I would be happy to revise this patch to reference capabilities.7.
>
>
> The capabilities.7 man page is existing maintained documentation on how to
> use this from userspace, which seems to be the point of your document.
> Having include/linux/uapi/capability.h mention its existence might be good.
> Feeding fixes to the documentation we've already got would be good.
>
> I read your document having largely ignored capabilities for years, and
> don't feel I have a better understanding of them after reading it. (I'm
> aware they exist, I'm aware they're used as a justification for extended
> attributes, I'm aware people think breaking a fireplace into a bunch of
> candleflames increases fire safety. I'm aware of
> http://forums.grsecurity.net/viewtopic.php?f=7&t=2522 and I _used_ to be
> aware of
> http://userweb.kernel.org/~morgan/sendmail-capabilities-war-story.html but
> kernel.org never bothered putting most of itself back together after the
> breakin last year and archive.org doesn't have a copy. I'm aware that a
> decade ago at Atlanta Linux Showcase in california Ted Tso was sad nobody
> was using them yet. But I haven't hugely been tracking changes over the last
> 5 years in how they work. It looks like figuring out who has what involves
> working through exercises in set theory that cannot be explained using a 127
> bit ascii set. Personally, I prefer "more dangerous" security setups that
> don't require I pull out scratch paper to reason about the state of the
> system, so perhaps I'm biased here.)

Heh.  I agree this stuff is shockingly complicated.  (And this
document isn't wriiten in ASCII...)

I actually wrote this file because I was reading the code and trying
to figure out wtf was going on.  This is the result :)  I'll see if I
can improve capabilities.7.

Any pointers to things you wanted to understand?

--Andy

Re: [PATCH] Document how capability bits work

[Rob Landley]

On 12/07/2012 07:27:25 PM, Andy Lutomirski wrote:
> On Fri, Dec 7, 2012 at 5:10 PM, Rob Landley <rob@landley.net> wrote:
> > On 12/07/2012 01:32:18 PM, Andy Lutomirski wrote:
> >>
> >> On Fri, Dec 7, 2012 at 11:21 AM, Serge Hallyn
> >> <serge.hallyn@canonical.com> wrote:
> >> > Quoting Andy Lutomirski (luto@amacapital.net):
> >> >> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
> >> >> ---
> >> >>  Documentation/security/capabilities.txt | 161
> >> >> ++++++++++++++++++++++++++++++++
> >> >>  1 file changed, 161 insertions(+)
> >> >>  create mode 100644 Documentation/security/capabilities.txt
> >> >
> >> > TBH, I think a pointer to the capabilities.7 man page would be  
> better.
> >> > (plus, if you feel they are needed, updates to the man page)
> >>
> >> Updating capabilities.7 wouldn't be a bad idea, but IMO it  
> certainly
> >> needs work.  For example, it says:
> >
> > ...
> >
> >> I would be happy to revise this patch to reference capabilities.7.
> >
> >
> > The capabilities.7 man page is existing maintained documentation on  
> how to
> > use this from userspace, which seems to be the point of your  
> document.
> > Having include/linux/uapi/capability.h mention its existence might  
> be good.
> > Feeding fixes to the documentation we've already got would be good.
> >
> > I read your document having largely ignored capabilities for years,  
> and
> > don't feel I have a better understanding of them after reading it.  
> (I'm
> > aware they exist, I'm aware they're used as a justification for  
> extended
> > attributes, I'm aware people think breaking a fireplace into a  
> bunch of
> > candleflames increases fire safety. I'm aware of
> > http://forums.grsecurity.net/viewtopic.php?f=7&t=2522 and I _used_  
> to be
> > aware of
> >  
> http://userweb.kernel.org/~morgan/sendmail-capabilities-war-story.html  
> but
> > kernel.org never bothered putting most of itself back together  
> after the
> > breakin last year and archive.org doesn't have a copy. I'm aware  
> that a
> > decade ago at Atlanta Linux Showcase in california Ted Tso was sad  
> nobody
> > was using them yet. But I haven't hugely been tracking changes over  
> the last
> > 5 years in how they work. It looks like figuring out who has what  
> involves
> > working through exercises in set theory that cannot be explained  
> using a 127
> > bit ascii set. Personally, I prefer "more dangerous" security  
> setups that
> > don't require I pull out scratch paper to reason about the state of  
> the
> > system, so perhaps I'm biased here.)
> 
> Heh.  I agree this stuff is shockingly complicated.  (And this
> document isn't wriiten in ASCII...)

The fact that you need multiple sets of capabilities per process  
(permitted, inheritable, effective), plus MORE sets (plural) of  
capabilities attached to executable files, plus the "capability  
bounding set" which is presumably so selinux can mess with it, plus a  
reset to all ones when you run an suid root program... And this is on  
_top_ of the existing uid/gid ownership stuff attached to every process  
and filesystem. And it's orthogonal to the namespace and cgroups stuff  
added to implement containers. AND the people who use capabilities  
still want to spray down the system with SELinux rulesets (or apparmor)  
on top of that...

The complexity of this mechanism does not fill me with confidence in  
its robustness, nor increase my desire to make extensive use of it. But  
then I don't normally do enterprise system administration, so I'm not  
the target audience.

> I actually wrote this file because I was reading the code and trying
> to figure out wtf was going on.  This is the result :)  I'll see if I
> can improve capabilities.7.
> 
> Any pointers to things you wanted to understand?

The only thing I really _want_ to understand about capabilities is why  
the lxc guys seem to think they need them to implement containers. (I  
think I have it written down somewhere, but don't remember off the top  
of my head.)

As to "how capatilities get set", the "transformation of capabilities  
during execve" bit of the man page seemed to cover it. (I got to the  
point where it said the capability bounding set is now a per-thread  
attribute, could NOT wrap my head around why anybody would even try to  
"secure" threads of the same process from each other, and wandered off.)

But the point is the current man page does a good job of documenting  
this stuff, which is a separate issue from whether or not I think the  
mechanism is a good idea. You seem to be suggesting that there are  
flaws in the man page, in which case I suggest fixing the man page.

Rob

Re: [PATCH] Document how capability bits work

[Michael Kerrisk (man-pages)]

Andy,

On Sat, Dec 8, 2012 at 2:27 AM, Andy Lutomirski <luto@amacapital.net> wrote:
> On Fri, Dec 7, 2012 at 5:10 PM, Rob Landley <rob@landley.net> wrote:
>> On 12/07/2012 01:32:18 PM, Andy Lutomirski wrote:
>>>
>>> On Fri, Dec 7, 2012 at 11:21 AM, Serge Hallyn
>>> <serge.hallyn@canonical.com> wrote:
>>> > Quoting Andy Lutomirski (luto@amacapital.net):
>>> >> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
>>> >> ---
>>> >>  Documentation/security/capabilities.txt | 161
>>> >> ++++++++++++++++++++++++++++++++
>>> >>  1 file changed, 161 insertions(+)
>>> >>  create mode 100644 Documentation/security/capabilities.txt
>>> >
>>> > TBH, I think a pointer to the capabilities.7 man page would be better.
>>> > (plus, if you feel they are needed, updates to the man page)
>>>
>>> Updating capabilities.7 wouldn't be a bad idea, but IMO it certainly
>>> needs work.  For example, it says:
>>
>> ...
>>
>>> I would be happy to revise this patch to reference capabilities.7.
>>
>>
>> The capabilities.7 man page is existing maintained documentation on how to
>> use this from userspace, which seems to be the point of your document.
>> Having include/linux/uapi/capability.h mention its existence might be good.
>> Feeding fixes to the documentation we've already got would be good.
>>
>> I read your document having largely ignored capabilities for years, and
>> don't feel I have a better understanding of them after reading it. (I'm
>> aware they exist, I'm aware they're used as a justification for extended
>> attributes, I'm aware people think breaking a fireplace into a bunch of
>> candleflames increases fire safety. I'm aware of
>> http://forums.grsecurity.net/viewtopic.php?f=7&t=2522 and I _used_ to be
>> aware of
>> http://userweb.kernel.org/~morgan/sendmail-capabilities-war-story.html but
>> kernel.org never bothered putting most of itself back together after the
>> breakin last year and archive.org doesn't have a copy. I'm aware that a
>> decade ago at Atlanta Linux Showcase in california Ted Tso was sad nobody
>> was using them yet. But I haven't hugely been tracking changes over the last
>> 5 years in how they work. It looks like figuring out who has what involves
>> working through exercises in set theory that cannot be explained using a 127
>> bit ascii set. Personally, I prefer "more dangerous" security setups that
>> don't require I pull out scratch paper to reason about the state of the
>> system, so perhaps I'm biased here.)
>
> Heh.  I agree this stuff is shockingly complicated.  (And this
> document isn't wriiten in ASCII...)
>
> I actually wrote this file because I was reading the code and trying
> to figure out wtf was going on.  This is the result :)  I'll see if I
> can improve capabilities.7.
>
> Any pointers to things you wanted to understand?

Indeed, it strikes me that a patch to capabilities.7 would be best.
This is all about user-visible stuff, and hiding things in a kernel
source file is not very user visible.

capabilities.7 is a big page. It would be best to break the patch into
logically distinct pieces, if that can be sensibly done.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: [PATCH] Document how capability bits work

[Serge Hallyn]

Quoting Rob Landley (rob@landley.net):
> The fact that you need multiple sets of capabilities per process
> (permitted, inheritable, effective), plus MORE sets (plural) of
> capabilities attached to executable files, plus the "capability
> bounding set" which is presumably so selinux can mess with it, plus

The bounding set was in large part a workaround for the absence of the
user namespace (and, at the time, the devices cgroup).

(Now libcap-ng uses it to try and make capabilities generally easier to
use.)

-serge