Documenting ptrace access mode checking

Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Hi Jann, Stephen, et al.

Jann, since you recently committed a patch in this area, and Stephen,
since you committed 006ebb40d3d much further back in time, I wonder if
you might help me by reviewing the text below that I propose to add to
the ptrace(2) man page, in order to document "ptrace access mode 
checking" that is performed in various parts of the kernel-user-space
interface. Of course, I welcome input from anyone else as well.

Here's the new ptrace(2) text. Any comments, technical or terminological
fixes, other improvements, etc. are welcome.

[[
   Ptrace access mode checking
       Various parts of the kernel-user-space API (not just  ptrace(2)
       operations), require so-called "ptrace access mode permissions"
       which are gated  by  Linux  Security  Modules  (LSMs)  such  as
       SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
       2.6.27, all such checks were of a  single  type.   Since  Linux
       2.6.27, two access mode levels are distinguished:

       PTRACE_MODE_READ
              For  "read" operations or other operations that are less
              dangerous, such as: get_robust_list(2); kcmp(2); reading
              /proc/[pid]/auxv,         /proc/[pid]/environ,        or
              /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
              file.

       PTRACE_MODE_ATTACH
              For  "write"  operations,  or  other operations that are
              more    dangerous,    such    as:    ptrace    attaching
              (PTRACE_ATTACH)    to   another   process   or   calling
              process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
              tively the default before Linux 2.6.27.)

       Since  Linux  4.5, the above access mode checks may be combined
       (ORed) with one of the following modifiers:

       PTRACE_MODE_FSCREDS
              Use the caller's filesystem UID  and  GID  (see  creden‐
              tials(7)) or effective capabilities for LSM checks.

       PTRACE_MODE_REALCREDS
              Use the caller's real UID and GID or permitted capabili‐
              ties for LSM checks.  This was effectively  the  default
              before Linux 4.5.

       Because  combining  one of the credential modifiers with one of
       the aforementioned access modes is  typical,  some  macros  are
       defined in the kernel sources for the combinations:

       PTRACE_MODE_READ_FSCREDS
              Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.

       PTRACE_MODE_READ_REALCREDS
              Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.

       PTRACE_MODE_ATTACH_FSCREDS
              Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.

       PTRACE_MODE_ATTACH_REALCREDS
              Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.

       One further modifier can be ORed with the access mode:

       PTRACE_MODE_NOAUDIT (since Linux 3.3)
              Don't audit this access mode check.

[I'd quite welcome some text to explain "auditing" here.]

       The  algorithm  employed for ptrace access mode checking deter‐
       mines whether the calling process is  allowed  to  perform  the
       corresponding action on the target process, as follows:

       1.  If the calling thread and the target thread are in the same
           thread group, access is always allowed.

       2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
           the  check in the next step, employ the caller's filesystem
           user ID and group ID (see credentials(7));  otherwise  (the
           access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
           caller's real user ID and group ID.

       3.  Deny access if neither of the following is true:

           · The real, effective, and saved-set user IDs of the target
             match  the caller's user ID, and the real, effective, and
             saved-set group IDs of  the  target  match  the  caller's
             group ID.

           · The caller has the CAP_SYS_PTRACE capability.

       4.  Deny  access if the target process "dumpable" attribute has
           a value other than 1 (SUID_DUMP_USER; see the discussion of
           PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
           the CAP_SYS_PTRACE capability in the user namespace of  the
           target process.

       5.  The  kernel LSM security_ptrace_access_check() interface is
           invoked to see if ptrace access is permitted.  The  results
           depend on the LSM.  The implementation of this interface in
           the default LSM performs the following steps:

           a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
              use the caller's effective capability set in the follow‐
              ing  check;  otherwise  (the   access   mode   specifies
              PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
              capability set.

           b) Deny access if neither of the following is true:

              · The caller's capabilities are a proper superset of the
                target process's permitted capabilities.

              · The  caller  has  the CAP_SYS_PTRACE capability in the
                target process's user namespace.

              Note that the default LSM does not  distinguish  between
              PTRACE_MODE_READ and PTRACE_MODE_ATTACH.

       6.  If  access  has  not  been  denied  by any of the preceding
           steps, then access is allowed.
]]

There are accompanying changes to various pages that refer to 
the new text in ptrace(2), so that, for example, kcmp(2) adds:

       Permission  to  employ kcmp() is governed by ptrace access mode
       PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
       see ptrace(2).

and proc.5 has additions such as:

       /proc/[pid]/auxv (since 2.6.0-test7)
              ...
              Permission to access this file is governed by  a  ptrace
              access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
              ptrace(2).

       /proc/[pid]/cwd
              ...
              Permission to dereference  or  read  (readlink(2))  this
              symbolic  link  is  governed  by  a  ptrace  access mode
              PTRACE_MODE_READ_FSCREDS check; see ptrace(2).

Thanks,

Michael

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

Re: Documenting ptrace access mode checking

[Eric W. Biederman]

Adding Oleg just because he seems to do most of the ptrace related
maintenance these days.

"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:

> Hi Jann, Stephen, et al.
>
> Jann, since you recently committed a patch in this area, and Stephen,
> since you committed 006ebb40d3d much further back in time, I wonder if
> you might help me by reviewing the text below that I propose to add to
> the ptrace(2) man page, in order to document "ptrace access mode 
> checking" that is performed in various parts of the kernel-user-space
> interface. Of course, I welcome input from anyone else as well.
>
> Here's the new ptrace(2) text. Any comments, technical or terminological
> fixes, other improvements, etc. are welcome.
>
> [[
>    Ptrace access mode checking
>        Various parts of the kernel-user-space API (not just  ptrace(2)
>        operations), require so-called "ptrace access mode permissions"
>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>        2.6.27, all such checks were of a  single  type.   Since  Linux
>        2.6.27, two access mode levels are distinguished:
>
>        PTRACE_MODE_READ
>               For  "read" operations or other operations that are less
>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>               file.
>
>        PTRACE_MODE_ATTACH
>               For  "write"  operations,  or  other operations that are
>               more    dangerous,    such    as:    ptrace    attaching
>               (PTRACE_ATTACH)    to   another   process   or   calling
>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>               tively the default before Linux 2.6.27.)
>
>        Since  Linux  4.5, the above access mode checks may be combined
>        (ORed) with one of the following modifiers:
>
>        PTRACE_MODE_FSCREDS
>               Use the caller's filesystem UID  and  GID  (see  creden‐
>               tials(7)) or effective capabilities for LSM checks.
>
>        PTRACE_MODE_REALCREDS
>               Use the caller's real UID and GID or permitted capabili‐
>               ties for LSM checks.  This was effectively  the  default
>               before Linux 4.5.
>
>        Because  combining  one of the credential modifiers with one of
>        the aforementioned access modes is  typical,  some  macros  are
>        defined in the kernel sources for the combinations:
>
>        PTRACE_MODE_READ_FSCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
>
>        PTRACE_MODE_READ_REALCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
>
>        PTRACE_MODE_ATTACH_FSCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
>
>        PTRACE_MODE_ATTACH_REALCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
>
>        One further modifier can be ORed with the access mode:
>
>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>               Don't audit this access mode check.
>
> [I'd quite welcome some text to explain "auditing" here.]

         AKA don't let the audit subsystem know.  Which tends to
         generate audit records capable is called.
>
>        The  algorithm  employed for ptrace access mode checking deter‐
>        mines whether the calling process is  allowed  to  perform  the
>        corresponding action on the target process, as follows:
>
>        1.  If the calling thread and the target thread are in the same
>            thread group, access is always allowed.

This test only exsits because the LSMs historically and I suspect
continue to be broken and deny a process the ability to ptrace itself.
>
>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>            the  check in the next step, employ the caller's filesystem
>            user ID and group ID (see credentials(7));  otherwise  (the
>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>            caller's real user ID and group ID.
>
>        3.  Deny access if neither of the following is true:
>
>            · The real, effective, and saved-set user IDs of the target
>              match  the caller's user ID, and the real, effective, and
>              saved-set group IDs of  the  target  match  the  caller's
>              group ID.
>
>            · The caller has the CAP_SYS_PTRACE capability.
>
>        4.  Deny  access if the target process "dumpable" attribute has
>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>            the CAP_SYS_PTRACE capability in the user namespace of  the
>            target process.
>
>        5.  The  kernel LSM security_ptrace_access_check() interface is
>            invoked to see if ptrace access is permitted.  The  results
>            depend on the LSM.  The implementation of this interface in
>            the default LSM performs the following steps:
>
>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>               use the caller's effective capability set in the follow‐
>               ing  check;  otherwise  (the   access   mode   specifies
>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>               capability set.
>
>            b) Deny access if neither of the following is true:
>
>               · The caller's capabilities are a proper superset of the
>                 target process's permitted capabilities.
>
>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>                 target process's user namespace.
>
>               Note that the default LSM does not  distinguish  between
>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
>
>        6.  If  access  has  not  been  denied  by any of the preceding
>            steps, then access is allowed.
> ]]
>
> There are accompanying changes to various pages that refer to 
> the new text in ptrace(2), so that, for example, kcmp(2) adds:
>
>        Permission  to  employ kcmp() is governed by ptrace access mode
>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>        see ptrace(2).
>
> and proc.5 has additions such as:
>
>        /proc/[pid]/auxv (since 2.6.0-test7)
>               ...
>               Permission to access this file is governed by  a  ptrace
>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>               ptrace(2).
>
>        /proc/[pid]/cwd
>               ...
>               Permission to dereference  or  read  (readlink(2))  this
>               symbolic  link  is  governed  by  a  ptrace  access mode
>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).

Hmm.

When I gave this level of detail about the user namespace permission
checks you gave me some flack, because it was not particularly
comprehensible to the end users.  I think you deserve the same feedback.

How do we say this in a way that does not describes a useful way to
think about it.  I read this and I know a lot of what is going on and my
mind goes numb.

How about something like this:

   If the callers uid and gid are the same as a processes uids and gids
   and the processes is configured to allow core dumps (aka it was never
   setuid or setgid) then the caller is allowed to ptrace a process.
   
   Otherwise the caller must have CAP_SYS_PTRACE.
   
   Linux security modules impose additional restrictions.
   
   For consistency access to various process attributes are guarded with
   the same security checks as the ptrace system call itself.  As they are
   all methods to get information about a process.

We certainly need something that gives a high level view so people
reading the man page can know what to expect.   If you get down into the
weeds we run the danger of people beginning to think they can depend
upon bugs in the implementation.

Eric

Re: Documenting ptrace access mode checking

[Kees Cook]

On Tue, Jun 21, 2016 at 12:55 PM, Eric W. Biederman
<ebiederm@xmission.com> wrote:
>
> Adding Oleg just because he seems to do most of the ptrace related
> maintenance these days.
>
> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>
>> Hi Jann, Stephen, et al.
>>
>> Jann, since you recently committed a patch in this area, and Stephen,
>> since you committed 006ebb40d3d much further back in time, I wonder if
>> you might help me by reviewing the text below that I propose to add to
>> the ptrace(2) man page, in order to document "ptrace access mode
>> checking" that is performed in various parts of the kernel-user-space
>> interface. Of course, I welcome input from anyone else as well.

Your text matches my understand of this code. :)

>> Here's the new ptrace(2) text. Any comments, technical or terminological
>> fixes, other improvements, etc. are welcome.
>>
>> [[
>>    Ptrace access mode checking
>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>        operations), require so-called "ptrace access mode permissions"
>>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>>        2.6.27, all such checks were of a  single  type.   Since  Linux
>>        2.6.27, two access mode levels are distinguished:
>>
>>        PTRACE_MODE_READ
>>               For  "read" operations or other operations that are less
>>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>>               file.
>>
>>        PTRACE_MODE_ATTACH
>>               For  "write"  operations,  or  other operations that are
>>               more    dangerous,    such    as:    ptrace    attaching
>>               (PTRACE_ATTACH)    to   another   process   or   calling
>>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>>               tively the default before Linux 2.6.27.)
>>
>>        Since  Linux  4.5, the above access mode checks may be combined
>>        (ORed) with one of the following modifiers:
>>
>>        PTRACE_MODE_FSCREDS
>>               Use the caller's filesystem UID  and  GID  (see  creden‐
>>               tials(7)) or effective capabilities for LSM checks.
>>
>>        PTRACE_MODE_REALCREDS
>>               Use the caller's real UID and GID or permitted capabili‐
>>               ties for LSM checks.  This was effectively  the  default
>>               before Linux 4.5.
>>
>>        Because  combining  one of the credential modifiers with one of
>>        the aforementioned access modes is  typical,  some  macros  are
>>        defined in the kernel sources for the combinations:
>>
>>        PTRACE_MODE_READ_FSCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_READ_REALCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
>>
>>        PTRACE_MODE_ATTACH_FSCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_ATTACH_REALCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
>>
>>        One further modifier can be ORed with the access mode:
>>
>>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>>               Don't audit this access mode check.
>>
>> [I'd quite welcome some text to explain "auditing" here.]
>
>          AKA don't let the audit subsystem know.  Which tends to
>          generate audit records capable is called.
>>
>>        The  algorithm  employed for ptrace access mode checking deter‐
>>        mines whether the calling process is  allowed  to  perform  the
>>        corresponding action on the target process, as follows:
>>
>>        1.  If the calling thread and the target thread are in the same
>>            thread group, access is always allowed.
>
> This test only exsits because the LSMs historically and I suspect
> continue to be broken and deny a process the ability to ptrace itself.

Well, it's not that the LSMs are broken, it's that self-inspection is
a short-circuited "allow". The LSMs aren't involved.

>>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>>            the  check in the next step, employ the caller's filesystem
>>            user ID and group ID (see credentials(7));  otherwise  (the
>>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>>            caller's real user ID and group ID.
>>
>>        3.  Deny access if neither of the following is true:
>>
>>            · The real, effective, and saved-set user IDs of the target
>>              match  the caller's user ID, and the real, effective, and
>>              saved-set group IDs of  the  target  match  the  caller's
>>              group ID.
>>
>>            · The caller has the CAP_SYS_PTRACE capability.
>>
>>        4.  Deny  access if the target process "dumpable" attribute has
>>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>>            the CAP_SYS_PTRACE capability in the user namespace of  the
>>            target process.
>>
>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>            invoked to see if ptrace access is permitted.  The  results
>>            depend on the LSM.  The implementation of this interface in
>>            the default LSM performs the following steps:
>>
>>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>>               use the caller's effective capability set in the follow‐
>>               ing  check;  otherwise  (the   access   mode   specifies
>>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>>               capability set.
>>
>>            b) Deny access if neither of the following is true:
>>
>>               · The caller's capabilities are a proper superset of the
>>                 target process's permitted capabilities.
>>
>>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>>                 target process's user namespace.
>>
>>               Note that the default LSM does not  distinguish  between
>>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
>>
>>        6.  If  access  has  not  been  denied  by any of the preceding
>>            steps, then access is allowed.
>> ]]
>>
>> There are accompanying changes to various pages that refer to
>> the new text in ptrace(2), so that, for example, kcmp(2) adds:
>>
>>        Permission  to  employ kcmp() is governed by ptrace access mode
>>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>>        see ptrace(2).
>>
>> and proc.5 has additions such as:
>>
>>        /proc/[pid]/auxv (since 2.6.0-test7)
>>               ...
>>               Permission to access this file is governed by  a  ptrace
>>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>>               ptrace(2).
>>
>>        /proc/[pid]/cwd
>>               ...
>>               Permission to dereference  or  read  (readlink(2))  this
>>               symbolic  link  is  governed  by  a  ptrace  access mode
>>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).
>
> Hmm.
>
> When I gave this level of detail about the user namespace permission
> checks you gave me some flack, because it was not particularly
> comprehensible to the end users.  I think you deserve the same feedback.
>
> How do we say this in a way that does not describes a useful way to
> think about it.  I read this and I know a lot of what is going on and my
> mind goes numb.

If the goal is to document the kernel behavior, then the details
around the various MODE flags makes sense. If this is just about
userspace-visible behavior, I would agree: the MODE flag details may
be overkill (since they are not exposed to userspace).

-Kees

-- 
Kees Cook
Chrome OS & Brillo Security

Re: Documenting ptrace access mode checking

[Eric W. Biederman]

Kees Cook <keescook@chromium.org> writes:

> On Tue, Jun 21, 2016 at 12:55 PM, Eric W. Biederman
> <ebiederm@xmission.com> wrote:
>
>> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>>
>>>        The  algorithm  employed for ptrace access mode checking deter‐
>>>        mines whether the calling process is  allowed  to  perform  the
>>>        corresponding action on the target process, as follows:
>>>
>>>        1.  If the calling thread and the target thread are in the same
>>>            thread group, access is always allowed.
>>
>> This test only exsits because the LSMs historically and I suspect
>> continue to be broken and deny a process the ability to ptrace itself.
>
> Well, it's not that the LSMs are broken, it's that self-inspection is
> a short-circuited "allow". The LSMs aren't involved.

Long ago and far away.  I modified /proc/self/something to use the same
permissions as ptrace.  This broken everyone's selinux setups.  So the
short circuit was added.

Or in short the LSMs aren't involved because they got it wrong.

If the selinux breakage was not in the selinux rules that are loaded from
userspace but in the kernel module that short circuit check would have
been confined to selinux.

I have had an occasional thought and the occassional discussion about
removing that check and just fixing the LSMs but at this point I don't
think anyone cares enough to make that change.

Eric

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Hi Kees,

On 06/21/2016 10:29 PM, Kees Cook wrote:
> On Tue, Jun 21, 2016 at 12:55 PM, Eric W. Biederman
> <ebiederm@xmission.com> wrote:
>>
>> Adding Oleg just because he seems to do most of the ptrace related
>> maintenance these days.
>>
>> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>>
>>> Hi Jann, Stephen, et al.
>>>
>>> Jann, since you recently committed a patch in this area, and Stephen,
>>> since you committed 006ebb40d3d much further back in time, I wonder if
>>> you might help me by reviewing the text below that I propose to add to
>>> the ptrace(2) man page, in order to document "ptrace access mode
>>> checking" that is performed in various parts of the kernel-user-space
>>> interface. Of course, I welcome input from anyone else as well.
>
> Your text matches my understand of this code. :)

Thanks for reviewing the text!

>>> Here's the new ptrace(2) text. Any comments, technical or terminological
>>> fixes, other improvements, etc. are welcome.
>>>
>>> [[
>>>    Ptrace access mode checking
>>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>>        operations), require so-called "ptrace access mode permissions"
>>>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>>>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>>>        2.6.27, all such checks were of a  single  type.   Since  Linux
>>>        2.6.27, two access mode levels are distinguished:
>>>
>>>        PTRACE_MODE_READ
>>>               For  "read" operations or other operations that are less
>>>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>>>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>>>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>>>               file.
>>>
>>>        PTRACE_MODE_ATTACH
>>>               For  "write"  operations,  or  other operations that are
>>>               more    dangerous,    such    as:    ptrace    attaching
>>>               (PTRACE_ATTACH)    to   another   process   or   calling
>>>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>>>               tively the default before Linux 2.6.27.)
>>>
>>>        Since  Linux  4.5, the above access mode checks may be combined
>>>        (ORed) with one of the following modifiers:
>>>
>>>        PTRACE_MODE_FSCREDS
>>>               Use the caller's filesystem UID  and  GID  (see  creden‐
>>>               tials(7)) or effective capabilities for LSM checks.
>>>
>>>        PTRACE_MODE_REALCREDS
>>>               Use the caller's real UID and GID or permitted capabili‐
>>>               ties for LSM checks.  This was effectively  the  default
>>>               before Linux 4.5.
>>>
>>>        Because  combining  one of the credential modifiers with one of
>>>        the aforementioned access modes is  typical,  some  macros  are
>>>        defined in the kernel sources for the combinations:
>>>
>>>        PTRACE_MODE_READ_FSCREDS
>>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
>>>
>>>        PTRACE_MODE_READ_REALCREDS
>>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
>>>
>>>        PTRACE_MODE_ATTACH_FSCREDS
>>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
>>>
>>>        PTRACE_MODE_ATTACH_REALCREDS
>>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
>>>
>>>        One further modifier can be ORed with the access mode:
>>>
>>>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>>>               Don't audit this access mode check.
>>>
>>> [I'd quite welcome some text to explain "auditing" here.]
>>
>>          AKA don't let the audit subsystem know.  Which tends to
>>          generate audit records capable is called.
>>>
>>>        The  algorithm  employed for ptrace access mode checking deter‐
>>>        mines whether the calling process is  allowed  to  perform  the
>>>        corresponding action on the target process, as follows:
>>>
>>>        1.  If the calling thread and the target thread are in the same
>>>            thread group, access is always allowed.
>>
>> This test only exsits because the LSMs historically and I suspect
>> continue to be broken and deny a process the ability to ptrace itself.
>
> Well, it's not that the LSMs are broken, it's that self-inspection is
> a short-circuited "allow". The LSMs aren't involved.
>
>>>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>>>            the  check in the next step, employ the caller's filesystem
>>>            user ID and group ID (see credentials(7));  otherwise  (the
>>>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>>>            caller's real user ID and group ID.
>>>
>>>        3.  Deny access if neither of the following is true:
>>>
>>>            · The real, effective, and saved-set user IDs of the target
>>>              match  the caller's user ID, and the real, effective, and
>>>              saved-set group IDs of  the  target  match  the  caller's
>>>              group ID.
>>>
>>>            · The caller has the CAP_SYS_PTRACE capability.
>>>
>>>        4.  Deny  access if the target process "dumpable" attribute has
>>>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>>>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>>>            the CAP_SYS_PTRACE capability in the user namespace of  the
>>>            target process.
>>>
>>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>>            invoked to see if ptrace access is permitted.  The  results
>>>            depend on the LSM.  The implementation of this interface in
>>>            the default LSM performs the following steps:
>>>
>>>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>>>               use the caller's effective capability set in the follow‐
>>>               ing  check;  otherwise  (the   access   mode   specifies
>>>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>>>               capability set.
>>>
>>>            b) Deny access if neither of the following is true:
>>>
>>>               · The caller's capabilities are a proper superset of the
>>>                 target process's permitted capabilities.
>>>
>>>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>>>                 target process's user namespace.
>>>
>>>               Note that the default LSM does not  distinguish  between
>>>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
>>>
>>>        6.  If  access  has  not  been  denied  by any of the preceding
>>>            steps, then access is allowed.
>>> ]]
>>>
>>> There are accompanying changes to various pages that refer to
>>> the new text in ptrace(2), so that, for example, kcmp(2) adds:
>>>
>>>        Permission  to  employ kcmp() is governed by ptrace access mode
>>>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>>>        see ptrace(2).
>>>
>>> and proc.5 has additions such as:
>>>
>>>        /proc/[pid]/auxv (since 2.6.0-test7)
>>>               ...
>>>               Permission to access this file is governed by  a  ptrace
>>>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>>>               ptrace(2).
>>>
>>>        /proc/[pid]/cwd
>>>               ...
>>>               Permission to dereference  or  read  (readlink(2))  this
>>>               symbolic  link  is  governed  by  a  ptrace  access mode
>>>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).
>>
>> Hmm.
>>
>> When I gave this level of detail about the user namespace permission
>> checks you gave me some flack, because it was not particularly
>> comprehensible to the end users.  I think you deserve the same feedback.
>>
>> How do we say this in a way that does not describes a useful way to
>> think about it.  I read this and I know a lot of what is going on and my
>> mind goes numb.
>
> If the goal is to document the kernel behavior, then the details
> around the various MODE flags makes sense. If this is just about
> userspace-visible behavior, I would agree: the MODE flag details may
> be overkill (since they are not exposed to userspace).

The problem is that this is about user-space-visible behavior, but in
order to explain that behavior at what I believe is a sufficient level
of detail (e.g., to differentiate the various types of checks that
are performed for various system calls and pseudofile accesses),
one needs (1) to discuss the MODE flag details as implemented in
the kernel, and (2) to have a shorthand way to refer to the various
cases from other pages. It's not absolutely necessary to name the
flags for (1), but using the flag names is certainly a handy
shorthand for (2).

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: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Hi Eric,

On 06/21/2016 09:55 PM, Eric W. Biederman wrote:
>
> Adding Oleg just because he seems to do most of the ptrace related
> maintenance these days.
>
> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>
>> Hi Jann, Stephen, et al.
>>
>> Jann, since you recently committed a patch in this area, and Stephen,
>> since you committed 006ebb40d3d much further back in time, I wonder if
>> you might help me by reviewing the text below that I propose to add to
>> the ptrace(2) man page, in order to document "ptrace access mode
>> checking" that is performed in various parts of the kernel-user-space
>> interface. Of course, I welcome input from anyone else as well.
>>
>> Here's the new ptrace(2) text. Any comments, technical or terminological
>> fixes, other improvements, etc. are welcome.
>>
>> [[
>>    Ptrace access mode checking
>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>        operations), require so-called "ptrace access mode permissions"
>>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>>        2.6.27, all such checks were of a  single  type.   Since  Linux
>>        2.6.27, two access mode levels are distinguished:
>>
>>        PTRACE_MODE_READ
>>               For  "read" operations or other operations that are less
>>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>>               file.
>>
>>        PTRACE_MODE_ATTACH
>>               For  "write"  operations,  or  other operations that are
>>               more    dangerous,    such    as:    ptrace    attaching
>>               (PTRACE_ATTACH)    to   another   process   or   calling
>>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>>               tively the default before Linux 2.6.27.)
>>
>>        Since  Linux  4.5, the above access mode checks may be combined
>>        (ORed) with one of the following modifiers:
>>
>>        PTRACE_MODE_FSCREDS
>>               Use the caller's filesystem UID  and  GID  (see  creden‐
>>               tials(7)) or effective capabilities for LSM checks.
>>
>>        PTRACE_MODE_REALCREDS
>>               Use the caller's real UID and GID or permitted capabili‐
>>               ties for LSM checks.  This was effectively  the  default
>>               before Linux 4.5.
>>
>>        Because  combining  one of the credential modifiers with one of
>>        the aforementioned access modes is  typical,  some  macros  are
>>        defined in the kernel sources for the combinations:
>>
>>        PTRACE_MODE_READ_FSCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_READ_REALCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
>>
>>        PTRACE_MODE_ATTACH_FSCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_ATTACH_REALCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
>>
>>        One further modifier can be ORed with the access mode:
>>
>>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>>               Don't audit this access mode check.
>>
>> [I'd quite welcome some text to explain "auditing" here.]
>
>          AKA don't let the audit subsystem know.  Which tends to
>          generate audit records capable is called.
>>
>>        The  algorithm  employed for ptrace access mode checking deter‐
>>        mines whether the calling process is  allowed  to  perform  the
>>        corresponding action on the target process, as follows:
>>
>>        1.  If the calling thread and the target thread are in the same
>>            thread group, access is always allowed.
>
> This test only exsits because the LSMs historically and I suspect
> continue to be broken and deny a process the ability to ptrace itself.
>>
>>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>>            the  check in the next step, employ the caller's filesystem
>>            user ID and group ID (see credentials(7));  otherwise  (the
>>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>>            caller's real user ID and group ID.
>>
>>        3.  Deny access if neither of the following is true:
>>
>>            · The real, effective, and saved-set user IDs of the target
>>              match  the caller's user ID, and the real, effective, and
>>              saved-set group IDs of  the  target  match  the  caller's
>>              group ID.
>>
>>            · The caller has the CAP_SYS_PTRACE capability.
>>
>>        4.  Deny  access if the target process "dumpable" attribute has
>>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>>            the CAP_SYS_PTRACE capability in the user namespace of  the
>>            target process.
>>
>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>            invoked to see if ptrace access is permitted.  The  results
>>            depend on the LSM.  The implementation of this interface in
>>            the default LSM performs the following steps:
>>
>>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>>               use the caller's effective capability set in the follow‐
>>               ing  check;  otherwise  (the   access   mode   specifies
>>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>>               capability set.
>>
>>            b) Deny access if neither of the following is true:
>>
>>               · The caller's capabilities are a proper superset of the
>>                 target process's permitted capabilities.
>>
>>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>>                 target process's user namespace.
>>
>>               Note that the default LSM does not  distinguish  between
>>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
>>
>>        6.  If  access  has  not  been  denied  by any of the preceding
>>            steps, then access is allowed.
>> ]]
>>
>> There are accompanying changes to various pages that refer to
>> the new text in ptrace(2), so that, for example, kcmp(2) adds:
>>
>>        Permission  to  employ kcmp() is governed by ptrace access mode
>>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>>        see ptrace(2).
>>
>> and proc.5 has additions such as:
>>
>>        /proc/[pid]/auxv (since 2.6.0-test7)
>>               ...
>>               Permission to access this file is governed by  a  ptrace
>>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>>               ptrace(2).
>>
>>        /proc/[pid]/cwd
>>               ...
>>               Permission to dereference  or  read  (readlink(2))  this
>>               symbolic  link  is  governed  by  a  ptrace  access mode
>>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).
>
> Hmm.
>
> When I gave this level of detail about the user namespace permission
> checks you gave me some flack, because it was not particularly
> comprehensible to the end users.  I think you deserve the same feedback.
>
> How do we say this in a way that does not describes a useful way to
> think about it.  I read this and I know a lot of what is going on and my
> mind goes numb.
>
> How about something like this:
>
>    If the callers uid and gid are the same as a processes uids and gids
>    and the processes is configured to allow core dumps (aka it was never
>    setuid or setgid) then the caller is allowed to ptrace a process.
>
>    Otherwise the caller must have CAP_SYS_PTRACE.
>
>    Linux security modules impose additional restrictions.
>
>    For consistency access to various process attributes are guarded with
>    the same security checks as the ptrace system call itself.  As they are
>    all methods to get information about a process.
>
> We certainly need something that gives a high level view so people
> reading the man page can know what to expect.   If you get down into the
> weeds we run the danger of people beginning to think they can depend
> upon bugs in the implementation.

Thanks for the feedback, but I think more detail is required than you
suggest. (And I added all of that detail somewhat reluctantly.)
See my other replies for my rationale.

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: Documenting ptrace access mode checking

[Eric W. Biederman]

"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:

> Hi Eric,
>
> On 06/21/2016 09:55 PM, Eric W. Biederman wrote:
>> Hmm.
>>
>> When I gave this level of detail about the user namespace permission
>> checks you gave me some flack, because it was not particularly
>> comprehensible to the end users.  I think you deserve the same feedback.
>>
>> How do we say this in a way that does not describes a useful way to
>> think about it.  I read this and I know a lot of what is going on and my
>> mind goes numb.
>>
>> How about something like this:
>>
>>    If the callers uid and gid are the same as a processes uids and gids
>>    and the processes is configured to allow core dumps (aka it was never
>>    setuid or setgid) then the caller is allowed to ptrace a process.
>>
>>    Otherwise the caller must have CAP_SYS_PTRACE.
>>
>>    Linux security modules impose additional restrictions.
>>
>>    For consistency access to various process attributes are guarded with
>>    the same security checks as the ptrace system call itself.  As they are
>>    all methods to get information about a process.
>>
>> We certainly need something that gives a high level view so people
>> reading the man page can know what to expect.   If you get down into the
>> weeds we run the danger of people beginning to think they can depend
>> upon bugs in the implementation.
>
> Thanks for the feedback, but I think more detail is required than you
> suggest. (And I added all of that detail somewhat reluctantly.)
> See my other replies for my rationale.

What I saw badly missing from your description is not the level of
detail but bring things into a form that ordinary mortals can
understand.

For an explanation to be clear I think we very much need the high level
overview first.  Then we can expand that description with the very
detailed view.

I very much think we need to describe things in such a way that people
understand the principles behind the permission checks, and not just
have the documentation echo the code, so that people can know what weird
things LSMs like yama are likely to do, and how these checks are likely
to evolve in the future.

Because one thing is clear to me.  The evolution of these details is
clearly not done, and will continue to change in the future.

Eric

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Hi Eric,

On 06/23/2016 09:04 PM, Eric W. Biederman wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>
>> Hi Eric,
>>
>> On 06/21/2016 09:55 PM, Eric W. Biederman wrote:
>>> Hmm.
>>>
>>> When I gave this level of detail about the user namespace permission
>>> checks you gave me some flack, because it was not particularly
>>> comprehensible to the end users.  I think you deserve the same feedback.
>>>
>>> How do we say this in a way that does not describes a useful way to
>>> think about it.  I read this and I know a lot of what is going on and my
>>> mind goes numb.
>>>
>>> How about something like this:
>>>
>>>    If the callers uid and gid are the same as a processes uids and gids
>>>    and the processes is configured to allow core dumps (aka it was never
>>>    setuid or setgid) then the caller is allowed to ptrace a process.
>>>
>>>    Otherwise the caller must have CAP_SYS_PTRACE.
>>>
>>>    Linux security modules impose additional restrictions.
>>>
>>>    For consistency access to various process attributes are guarded with
>>>    the same security checks as the ptrace system call itself.  As they are
>>>    all methods to get information about a process.
>>>
>>> We certainly need something that gives a high level view so people
>>> reading the man page can know what to expect.   If you get down into the
>>> weeds we run the danger of people beginning to think they can depend
>>> upon bugs in the implementation.
>>
>> Thanks for the feedback, but I think more detail is required than you
>> suggest. (And I added all of that detail somewhat reluctantly.)
>> See my other replies for my rationale.
>
> What I saw badly missing from your description is not the level of
> detail but bring things into a form that ordinary mortals can
> understand.
>
> For an explanation to be clear I think we very much need the high level
> overview first.  Then we can expand that description with the very
> detailed view.
>
> I very much think we need to describe things in such a way that people
> understand the principles behind the permission checks, and not just
> have the documentation echo the code, so that people can know what weird
> things LSMs like yama are likely to do, and how these checks are likely
> to evolve in the future.

So, I completely agree with you, and I agree that this could be better.
At first, I understood your meaning to be that I should avoid all of the
detail, and just limit the man page to some very high level text as
you proposed. So, I think it's worth prefixing the details with some
attempt at a high-level picture. How about this as an introductory
paragraph:

        Various parts of the kernel-user-space API (not just  ptrace(2)
        operations),  require  so-called  "ptrace  access mode" checks,
        whose outcome determines whether an operation is permitted (or,
        in  a  few cases, causes a "read" operation to return sanitized
        data).  These checks are performed in cases where  one  process
        can  inspect sensitive information about, or in some cases mod‐
        ify the state of, another process.  The  checks  are  based  on
        factors  such  as  the  credentials and capabilities of the two
        processes, whether or not the "target" process is dumpable, and
        the  results  of checks performed by any enabled Linux Security
        Module (LSM)—for example, SELinux, Yama, or  Smack—and  by  the
        commoncap LSM (which is always invoked).

?

> Because one thing is clear to me.  The evolution of these details is
> clearly not done, and will continue to change in the future.

Maybe people will even write man page patches when that happens :-).

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: Documenting ptrace access mode checking

[Oleg Nesterov]

On 06/21, Eric W. Biederman wrote:
>
> Adding Oleg just because he seems to do most of the ptrace related
> maintenance these days.

so I have to admit that I never even tried to actually understand
ptrace_may_access ;)

> We certainly need something that gives a high level view so people
> reading the man page can know what to expect.   If you get down into the
> weeds we run the danger of people beginning to think they can depend
> upon bugs in the implementation.

Personally I agree. I think "man ptrace" shouldn't not tell too much
about kernel internals.

Perhaps Documentation/security/ makes more sense?

Oleg.

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Hi Oleg,

On 06/22/2016 11:51 PM, Oleg Nesterov wrote:
> On 06/21, Eric W. Biederman wrote:
>>
>> Adding Oleg just because he seems to do most of the ptrace related
>> maintenance these days.
>
> so I have to admit that I never even tried to actually understand
> ptrace_may_access ;)
>
>> We certainly need something that gives a high level view so people
>> reading the man page can know what to expect.   If you get down into the
>> weeds we run the danger of people beginning to think they can depend
>> upon bugs in the implementation.
>
> Personally I agree. I think "man ptrace" shouldn't not tell too much
> about kernel internals.

See my other replies on this topic. Somehow, we need a way of
describing the behavior that user-space sees. I think it's
inevitable that that means talking about what;s going on
"under the hood".

Regarding Eric's point that "we run the danger of people beginning
to think they can depend upon bugs in the implementation": when it
comes to breaking the ABI, the presence or absence of documentation
doesn't save us on that point (Linus has a few times made his position
wrt to documentation clear).

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: Documenting ptrace access mode checking

[Eric W. Biederman]

"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:

> Hi Oleg,
>
> On 06/22/2016 11:51 PM, Oleg Nesterov wrote:
>> On 06/21, Eric W. Biederman wrote:
>>>
>>> Adding Oleg just because he seems to do most of the ptrace related
>>> maintenance these days.
>>
>> so I have to admit that I never even tried to actually understand
>> ptrace_may_access ;)
>>
>>> We certainly need something that gives a high level view so people
>>> reading the man page can know what to expect.   If you get down into the
>>> weeds we run the danger of people beginning to think they can depend
>>> upon bugs in the implementation.
>>
>> Personally I agree. I think "man ptrace" shouldn't not tell too much
>> about kernel internals.
>
> See my other replies on this topic. Somehow, we need a way of
> describing the behavior that user-space sees. I think it's
> inevitable that that means talking about what;s going on
> "under the hood".
>
> Regarding Eric's point that "we run the danger of people beginning
> to think they can depend upon bugs in the implementation": when it
> comes to breaking the ABI, the presence or absence of documentation
> doesn't save us on that point (Linus has a few times made his position
> wrt to documentation clear).

Which are interesting in this respect as a bug in the implementation
that is a security issue can and will be changed, even if userspace
breaks.  Breaking userspace is not desirable but when there is no other
reasonable choice it will happen.

Eric

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

On 06/23/2016 08:56 PM, Eric W. Biederman wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
>
>> Hi Oleg,
>>
>> On 06/22/2016 11:51 PM, Oleg Nesterov wrote:
>>> On 06/21, Eric W. Biederman wrote:
>>>>
>>>> Adding Oleg just because he seems to do most of the ptrace related
>>>> maintenance these days.
>>>
>>> so I have to admit that I never even tried to actually understand
>>> ptrace_may_access ;)
>>>
>>>> We certainly need something that gives a high level view so people
>>>> reading the man page can know what to expect.   If you get down into the
>>>> weeds we run the danger of people beginning to think they can depend
>>>> upon bugs in the implementation.
>>>
>>> Personally I agree. I think "man ptrace" shouldn't not tell too much
>>> about kernel internals.
>>
>> See my other replies on this topic. Somehow, we need a way of
>> describing the behavior that user-space sees. I think it's
>> inevitable that that means talking about what;s going on
>> "under the hood".
>>
>> Regarding Eric's point that "we run the danger of people beginning
>> to think they can depend upon bugs in the implementation": when it
>> comes to breaking the ABI, the presence or absence of documentation
>> doesn't save us on that point (Linus has a few times made his position
>> wrt to documentation clear).
>
> Which are interesting in this respect as a bug in the implementation
> that is a security issue can and will be changed, even if userspace
> breaks.  Breaking userspace is not desirable but when there is no other
> reasonable choice it will happen.

Yes, good point.

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: Documenting ptrace access mode checking

[Jann Horn]

[-- Attachment #1: Type: text/plain, Size: 7926 bytes --]

On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Jann, Stephen, et al.
> 
> Jann, since you recently committed a patch in this area, and Stephen,
> since you committed 006ebb40d3d much further back in time, I wonder if
> you might help me by reviewing the text below that I propose to add to
> the ptrace(2) man page, in order to document "ptrace access mode 
> checking" that is performed in various parts of the kernel-user-space
> interface. Of course, I welcome input from anyone else as well.
> 
> Here's the new ptrace(2) text. Any comments, technical or terminological
> fixes, other improvements, etc. are welcome.

As others have said, I'm surprised about seeing documentation about
kernel-internal constants in manpages - but I think it might be a good
thing to have there, given that people who look at ptrace(2) are likely
to be interested in low-level details.


> [[
>    Ptrace access mode checking
>        Various parts of the kernel-user-space API (not just  ptrace(2)
>        operations), require so-called "ptrace access mode permissions"
>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>        2.6.27, all such checks were of a  single  type.   Since  Linux
>        2.6.27, two access mode levels are distinguished:
> 
>        PTRACE_MODE_READ
>               For  "read" operations or other operations that are less
>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>               file.
> 
>        PTRACE_MODE_ATTACH
>               For  "write"  operations,  or  other operations that are
>               more    dangerous,    such    as:    ptrace    attaching
>               (PTRACE_ATTACH)    to   another   process   or   calling
>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>               tively the default before Linux 2.6.27.)
> 
>        Since  Linux  4.5, the above access mode checks may be combined

s/may/must/; otherwise __ptrace_may_access() will yell about the kernel
code being broken and deny access.

>        (ORed) with one of the following modifiers:
> 
>        PTRACE_MODE_FSCREDS
>               Use the caller's filesystem UID  and  GID  (see  creden‐
>               tials(7)) or effective capabilities for LSM checks.
> 
>        PTRACE_MODE_REALCREDS
>               Use the caller's real UID and GID or permitted capabili‐
>               ties for LSM checks.  This was effectively  the  default
>               before Linux 4.5.
> 
>        Because  combining  one of the credential modifiers with one of
>        the aforementioned access modes is  typical,  some  macros  are
>        defined in the kernel sources for the combinations:
> 
>        PTRACE_MODE_READ_FSCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
> 
>        PTRACE_MODE_READ_REALCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
> 
>        PTRACE_MODE_ATTACH_FSCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
> 
>        PTRACE_MODE_ATTACH_REALCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
> 
>        One further modifier can be ORed with the access mode:
> 
>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>               Don't audit this access mode check.
> 
> [I'd quite welcome some text to explain "auditing" here.]
> 
>        The  algorithm  employed for ptrace access mode checking deter‐
>        mines whether the calling process is  allowed  to  perform  the
>        corresponding action on the target process, as follows:
> 
>        1.  If the calling thread and the target thread are in the same
>            thread group, access is always allowed.
> 
>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>            the  check in the next step, employ the caller's filesystem
>            user ID and group ID (see credentials(7));  otherwise  (the
>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>            caller's real user ID and group ID.

Might want to add a "for historical reasons" or so here.


>        3.  Deny access if neither of the following is true:
> 
>            · The real, effective, and saved-set user IDs of the target
>              match  the caller's user ID, and the real, effective, and
>              saved-set group IDs of  the  target  match  the  caller's
>              group ID.
> 
>            · The caller has the CAP_SYS_PTRACE capability.

Might want to also specify here (like below) that the caller needs to
have the capability relative to the user ns of the target.


>        4.  Deny  access if the target process "dumpable" attribute has
>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>            the CAP_SYS_PTRACE capability in the user namespace of  the
>            target process.
> 
>        5.  The  kernel LSM security_ptrace_access_check() interface is
>            invoked to see if ptrace access is permitted.  The  results
>            depend on the LSM.  The implementation of this interface in
>            the default LSM performs the following steps:

For people who are unaware of how the LSM API works, it might be good to
clarify that the commoncap LSM is *always* invoked; otherwise, it might
give the impression that using another LSM would replace it.
(Also, are there other documents that refer to it as "default LSM"? I
think that that term is slightly confusing.)


>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>               use the caller's effective capability set in the follow‐
>               ing  check;  otherwise  (the   access   mode   specifies
>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>               capability set.
> 
>            b) Deny access if neither of the following is true:
> 
>               · The caller's capabilities are a proper superset of the
>                 target process's permitted capabilities.

This also requires the caller and the target to be in the same user
namespace.


>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>                 target process's user namespace.
> 
>               Note that the default LSM does not  distinguish  between
>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
> 
>        6.  If  access  has  not  been  denied  by any of the preceding
>            steps, then access is allowed.
> ]]
> 
> There are accompanying changes to various pages that refer to 
> the new text in ptrace(2), so that, for example, kcmp(2) adds:
> 
>        Permission  to  employ kcmp() is governed by ptrace access mode
>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>        see ptrace(2).

(Actually, kcmp() just needs READ access - you described that accurately
earlier, but it's wrong here.)


> and proc.5 has additions such as:
> 
>        /proc/[pid]/auxv (since 2.6.0-test7)
>               ...
>               Permission to access this file is governed by  a  ptrace
>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>               ptrace(2).
> 
>        /proc/[pid]/cwd
>               ...
>               Permission to dereference  or  read  (readlink(2))  this
>               symbolic  link  is  governed  by  a  ptrace  access mode
>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).

That sounds great! :)

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Hi Jann,


On 06/21/2016 10:55 PM, Jann Horn wrote:
> On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages) wrote:
>> Hi Jann, Stephen, et al.
>>
>> Jann, since you recently committed a patch in this area, and Stephen,
>> since you committed 006ebb40d3d much further back in time, I wonder if
>> you might help me by reviewing the text below that I propose to add to
>> the ptrace(2) man page, in order to document "ptrace access mode
>> checking" that is performed in various parts of the kernel-user-space
>> interface. Of course, I welcome input from anyone else as well.
>>
>> Here's the new ptrace(2) text. Any comments, technical or terminological
>> fixes, other improvements, etc. are welcome.
>
> As others have said, I'm surprised about seeing documentation about
> kernel-internal constants in manpages - but I think it might be a good
> thing to have there, given that people who look at ptrace(2) are likely
> to be interested in low-level details.

I agree that it is a little surprising to add kernel-internal
constants in a man page. (There are precedents, but they are few.)
But see my reply to Kees. It's more than just explaining low level
details: there are various kinds of user-space behavior differences
(real vs filesystem credentials; permitted vs effective capabilities)
produced by the ptrace_may_access() checks, and those behaviors need
to be described and *somehow* labeled for cross-referencing from
other man pages.

>> [[
>>    Ptrace access mode checking
>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>        operations), require so-called "ptrace access mode permissions"
>>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>>        2.6.27, all such checks were of a  single  type.   Since  Linux
>>        2.6.27, two access mode levels are distinguished:
>>
>>        PTRACE_MODE_READ
>>               For  "read" operations or other operations that are less
>>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>>               file.
>>
>>        PTRACE_MODE_ATTACH
>>               For  "write"  operations,  or  other operations that are
>>               more    dangerous,    such    as:    ptrace    attaching
>>               (PTRACE_ATTACH)    to   another   process   or   calling
>>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>>               tively the default before Linux 2.6.27.)
>>
>>        Since  Linux  4.5, the above access mode checks may be combined
>
> s/may/must/; otherwise __ptrace_may_access() will yell about the kernel
> code being broken and deny access.

Good point. I changed "may" to "are". ("must" is not quite right to my
"user-space" ear; it might be misread as implying that the user-space
developer must do something.)

>>        (ORed) with one of the following modifiers:
>>
>>        PTRACE_MODE_FSCREDS
>>               Use the caller's filesystem UID  and  GID  (see  creden‐
>>               tials(7)) or effective capabilities for LSM checks.
>>
>>        PTRACE_MODE_REALCREDS
>>               Use the caller's real UID and GID or permitted capabili‐
>>               ties for LSM checks.  This was effectively  the  default
>>               before Linux 4.5.
>>
>>        Because  combining  one of the credential modifiers with one of
>>        the aforementioned access modes is  typical,  some  macros  are
>>        defined in the kernel sources for the combinations:
>>
>>        PTRACE_MODE_READ_FSCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_READ_REALCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
>>
>>        PTRACE_MODE_ATTACH_FSCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_ATTACH_REALCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
>>
>>        One further modifier can be ORed with the access mode:
>>
>>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>>               Don't audit this access mode check.
>>
>> [I'd quite welcome some text to explain "auditing" here.]
>>
>>        The  algorithm  employed for ptrace access mode checking deter‐
>>        mines whether the calling process is  allowed  to  perform  the
>>        corresponding action on the target process, as follows:
>>
>>        1.  If the calling thread and the target thread are in the same
>>            thread group, access is always allowed.
>>
>>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>>            the  check in the next step, employ the caller's filesystem
>>            user ID and group ID (see credentials(7));  otherwise  (the
>>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>>            caller's real user ID and group ID.
>
> Might want to add a "for historical reasons" or so here.

Can you be a little more precise about "here", and maybe tell me why
you think it helps?

>>        3.  Deny access if neither of the following is true:
>>
>>            · The real, effective, and saved-set user IDs of the target
>>              match  the caller's user ID, and the real, effective, and
>>              saved-set group IDs of  the  target  match  the  caller's
>>              group ID.
>>
>>            · The caller has the CAP_SYS_PTRACE capability.
>
> Might want to also specify here (like below) that the caller needs to
> have the capability relative to the user ns of the target.

Done.

>>        4.  Deny  access if the target process "dumpable" attribute has
>>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>>            the CAP_SYS_PTRACE capability in the user namespace of  the
>>            target process.
>>
>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>            invoked to see if ptrace access is permitted.  The  results
>>            depend on the LSM.  The implementation of this interface in
>>            the default LSM performs the following steps:
>
> For people who are unaware of how the LSM API works, it might be good to
> clarify that the commoncap LSM is *always* invoked; otherwise, it might
> give the impression that using another LSM would replace it.

As we can see, I am one of those who are unaware of how the LSM API
works :-/.

> (Also, are there other documents that refer to it as "default LSM"? I
> think that that term is slightly confusing.)

No, that's a terminological confusion of my own making. Fixed now.

I changed this text to:

        Various parts of the kernel-user-space API (not just  ptrace(2)
        operations), require so-called "ptrace access mode permissions"
        which are gated by any enabled Linux Security Module (LSMs)—for
        example,  SELinux,  Yama, or Smack—and by the the commoncap LSM
        (which is always invoked).  Prior to  Linux  2.6.27,  all  such
        checks  were  of a single type.  Since Linux 2.6.27, two access
        mode levels are distinguished:

BTW, can you point me at the piece(s) of kernel code that show that
"commoncap" is always invoked in addition to any other LSM that has
been installed?

>>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>>               use the caller's effective capability set in the follow‐
>>               ing  check;  otherwise  (the   access   mode   specifies
>>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>>               capability set.
>>
>>            b) Deny access if neither of the following is true:
>>
>>               · The caller's capabilities are a proper superset of the
>>                 target process's permitted capabilities.
>
> This also requires the caller and the target to be in the same user
> namespace.

Thanks! Fixed.

>>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>>                 target process's user namespace.
>>
>>               Note that the default LSM does not  distinguish  between
>>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
>>
>>        6.  If  access  has  not  been  denied  by any of the preceding
>>            steps, then access is allowed.
>> ]]
>>
>> There are accompanying changes to various pages that refer to
>> the new text in ptrace(2), so that, for example, kcmp(2) adds:
>>
>>        Permission  to  employ kcmp() is governed by ptrace access mode
>>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>>        see ptrace(2).
>
> (Actually, kcmp() just needs READ access - you described that accurately
> earlier, but it's wrong here.)

D'oh! Thanks!

>> and proc.5 has additions such as:
>>
>>        /proc/[pid]/auxv (since 2.6.0-test7)
>>               ...
>>               Permission to access this file is governed by  a  ptrace
>>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>>               ptrace(2).
>>
>>        /proc/[pid]/cwd
>>               ...
>>               Permission to dereference  or  read  (readlink(2))  this
>>               symbolic  link  is  governed  by  a  ptrace  access mode
>>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).
>
> That sounds great! :)

Thanks for the review!

Thanks,

Michael


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

Re: Documenting ptrace access mode checking

[Kees Cook]

On Wed, Jun 22, 2016 at 12:21 PM, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> On 06/21/2016 10:55 PM, Jann Horn wrote:
>> On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages)
>> wrote:
>>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>>            invoked to see if ptrace access is permitted.  The  results
>>>            depend on the LSM.  The implementation of this interface in
>>>            the default LSM performs the following steps:
>>
>>
>> For people who are unaware of how the LSM API works, it might be good to
>> clarify that the commoncap LSM is *always* invoked; otherwise, it might
>> give the impression that using another LSM would replace it.
>
>
> As we can see, I am one of those who are unaware of how the LSM API
> works :-/.
>
>> (Also, are there other documents that refer to it as "default LSM"? I
>> think that that term is slightly confusing.)
>
>
> No, that's a terminological confusion of my own making. Fixed now.
>
> I changed this text to:
>
>        Various parts of the kernel-user-space API (not just  ptrace(2)
>        operations), require so-called "ptrace access mode permissions"
>        which are gated by any enabled Linux Security Module (LSMs)—for
>        example,  SELinux,  Yama, or Smack—and by the the commoncap LSM
>        (which is always invoked).  Prior to  Linux  2.6.27,  all  such
>        checks  were  of a single type.  Since Linux 2.6.27, two access
>        mode levels are distinguished:
>
> BTW, can you point me at the piece(s) of kernel code that show that
> "commoncap" is always invoked in addition to any other LSM that has
> been installed?

It's not entirely obvious, but the bottom of security/commoncap.c shows:

#ifdef CONFIG_SECURITY

struct security_hook_list capability_hooks[] = {
        LSM_HOOK_INIT(capable, cap_capable),
...
};

void __init capability_add_hooks(void)
{
        security_add_hooks(capability_hooks, ARRAY_SIZE(capability_hooks));
}

#endif

And security/security.c shows the initialization order of the LSMs:

int __init security_init(void)
{
        pr_info("Security Framework initialized\n");

        /*
         * Load minor LSMs, with the capability module always first.
         */
        capability_add_hooks();
        yama_add_hooks();
        loadpin_add_hooks();

        /*
         * Load all the remaining security modules.
         */
        do_security_initcalls();

        return 0;
}


-Kees



-- 
Kees Cook
Chrome OS & Brillo Security

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

On 06/22/2016 11:11 PM, Kees Cook wrote:
> On Wed, Jun 22, 2016 at 12:21 PM, Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>> On 06/21/2016 10:55 PM, Jann Horn wrote:
>>> On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages)
>>> wrote:
>>>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>>>            invoked to see if ptrace access is permitted.  The  results
>>>>            depend on the LSM.  The implementation of this interface in
>>>>            the default LSM performs the following steps:
>>>
>>>
>>> For people who are unaware of how the LSM API works, it might be good to
>>> clarify that the commoncap LSM is *always* invoked; otherwise, it might
>>> give the impression that using another LSM would replace it.
>>
>>
>> As we can see, I am one of those who are unaware of how the LSM API
>> works :-/.
>>
>>> (Also, are there other documents that refer to it as "default LSM"? I
>>> think that that term is slightly confusing.)
>>
>>
>> No, that's a terminological confusion of my own making. Fixed now.
>>
>> I changed this text to:
>>
>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>        operations), require so-called "ptrace access mode permissions"
>>        which are gated by any enabled Linux Security Module (LSMs)—for
>>        example,  SELinux,  Yama, or Smack—and by the the commoncap LSM
>>        (which is always invoked).  Prior to  Linux  2.6.27,  all  such
>>        checks  were  of a single type.  Since Linux 2.6.27, two access
>>        mode levels are distinguished:
>>
>> BTW, can you point me at the piece(s) of kernel code that show that
>> "commoncap" is always invoked in addition to any other LSM that has
>> been installed?
>
> It's not entirely obvious, but the bottom of security/commoncap.c shows:

Thanks Kees!

Cheers,

Michael

>
> #ifdef CONFIG_SECURITY
>
> struct security_hook_list capability_hooks[] = {
>         LSM_HOOK_INIT(capable, cap_capable),
> ...
> };
>
> void __init capability_add_hooks(void)
> {
>         security_add_hooks(capability_hooks, ARRAY_SIZE(capability_hooks));
> }
>
> #endif
>
> And security/security.c shows the initialization order of the LSMs:
>
> int __init security_init(void)
> {
>         pr_info("Security Framework initialized\n");
>
>         /*
>          * Load minor LSMs, with the capability module always first.
>          */
>         capability_add_hooks();
>         yama_add_hooks();
>         loadpin_add_hooks();
>
>         /*
>          * Load all the remaining security modules.
>          */
>         do_security_initcalls();
>
>         return 0;
> }
>
>
> -Kees
>
>
>


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

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

On 06/22/2016 11:11 PM, Kees Cook wrote:
> On Wed, Jun 22, 2016 at 12:21 PM, Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>> On 06/21/2016 10:55 PM, Jann Horn wrote:
>>> On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages)
>>> wrote:
>>>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>>>            invoked to see if ptrace access is permitted.  The  results
>>>>            depend on the LSM.  The implementation of this interface in
>>>>            the default LSM performs the following steps:
>>>
>>>
>>> For people who are unaware of how the LSM API works, it might be good to
>>> clarify that the commoncap LSM is *always* invoked; otherwise, it might
>>> give the impression that using another LSM would replace it.
>>
>>
>> As we can see, I am one of those who are unaware of how the LSM API
>> works :-/.
>>
>>> (Also, are there other documents that refer to it as "default LSM"? I
>>> think that that term is slightly confusing.)
>>
>>
>> No, that's a terminological confusion of my own making. Fixed now.
>>
>> I changed this text to:
>>
>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>        operations), require so-called "ptrace access mode permissions"
>>        which are gated by any enabled Linux Security Module (LSMs)—for
>>        example,  SELinux,  Yama, or Smack—and by the the commoncap LSM
>>        (which is always invoked).  Prior to  Linux  2.6.27,  all  such
>>        checks  were  of a single type.  Since Linux 2.6.27, two access
>>        mode levels are distinguished:
>>
>> BTW, can you point me at the piece(s) of kernel code that show that
>> "commoncap" is always invoked in addition to any other LSM that has
>> been installed?
>
> It's not entirely obvious, but the bottom of security/commoncap.c shows:
>
> #ifdef CONFIG_SECURITY
>
> struct security_hook_list capability_hooks[] = {
>         LSM_HOOK_INIT(capable, cap_capable),
> ...
> };
>
> void __init capability_add_hooks(void)
> {
>         security_add_hooks(capability_hooks, ARRAY_SIZE(capability_hooks));
> }
>
> #endif
>
> And security/security.c shows the initialization order of the LSMs:
>
> int __init security_init(void)
> {
>         pr_info("Security Framework initialized\n");
>
>         /*
>          * Load minor LSMs, with the capability module always first.
>          */
>         capability_add_hooks();
>         yama_add_hooks();
>         loadpin_add_hooks();
>
>         /*
>          * Load all the remaining security modules.
>          */
>         do_security_initcalls();
>
>         return 0;
> }

So, I just want to check my understanding of a couple of points:

1. The commoncap LSM is invoked first, and if it denies access,
    then no further LSM is/needs to be called.

2. Is it the case that only one of the other LSMs (SELinux, Yama,
    AppArmor, etc.) is invoked, or can more than one be invoked.
    I thought only one is invoked, but perhaps I am out of date
    in my understanding.

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: Documenting ptrace access mode checking

[Casey Schaufler]

On 6/24/2016 1:40 AM, Michael Kerrisk (man-pages) wrote:
> On 06/22/2016 11:11 PM, Kees Cook wrote:
>> On Wed, Jun 22, 2016 at 12:21 PM, Michael Kerrisk (man-pages)
>> <mtk.manpages@gmail.com> wrote:
>>> On 06/21/2016 10:55 PM, Jann Horn wrote:
>>>> On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages)
>>>> wrote:
>>>>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>>>>            invoked to see if ptrace access is permitted.  The  results
>>>>>            depend on the LSM.  The implementation of this interface in
>>>>>            the default LSM performs the following steps:
>>>>
>>>>
>>>> For people who are unaware of how the LSM API works, it might be good to
>>>> clarify that the commoncap LSM is *always* invoked; otherwise, it might
>>>> give the impression that using another LSM would replace it.
>>>
>>>
>>> As we can see, I am one of those who are unaware of how the LSM API
>>> works :-/.
>>>
>>>> (Also, are there other documents that refer to it as "default LSM"? I
>>>> think that that term is slightly confusing.)
>>>
>>>
>>> No, that's a terminological confusion of my own making. Fixed now.
>>>
>>> I changed this text to:
>>>
>>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>>        operations), require so-called "ptrace access mode permissions"
>>>        which are gated by any enabled Linux Security Module (LSMs)—for
>>>        example,  SELinux,  Yama, or Smack—and by the the commoncap LSM
>>>        (which is always invoked).  Prior to  Linux  2.6.27,  all  such
>>>        checks  were  of a single type.  Since Linux 2.6.27, two access
>>>        mode levels are distinguished:
>>>
>>> BTW, can you point me at the piece(s) of kernel code that show that
>>> "commoncap" is always invoked in addition to any other LSM that has
>>> been installed?
>>
>> It's not entirely obvious, but the bottom of security/commoncap.c shows:
>>
>> #ifdef CONFIG_SECURITY
>>
>> struct security_hook_list capability_hooks[] = {
>>         LSM_HOOK_INIT(capable, cap_capable),
>> ...
>> };
>>
>> void __init capability_add_hooks(void)
>> {
>>         security_add_hooks(capability_hooks, ARRAY_SIZE(capability_hooks));
>> }
>>
>> #endif
>>
>> And security/security.c shows the initialization order of the LSMs:
>>
>> int __init security_init(void)
>> {
>>         pr_info("Security Framework initialized\n");
>>
>>         /*
>>          * Load minor LSMs, with the capability module always first.
>>          */
>>         capability_add_hooks();
>>         yama_add_hooks();
>>         loadpin_add_hooks();
>>
>>         /*
>>          * Load all the remaining security modules.
>>          */
>>         do_security_initcalls();
>>
>>         return 0;
>> }
>
> So, I just want to check my understanding of a couple of points:
>
> 1. The commoncap LSM is invoked first, and if it denies access,
>    then no further LSM is/needs to be called.

Yes. The LSM infrastructure is "bail on fail".

>
> 2. Is it the case that only one of the other LSMs (SELinux, Yama,
>    AppArmor, etc.) is invoked, or can more than one be invoked.
>    I thought only one is invoked, but perhaps I am out of date
>    in my understanding.

All registered modules are invoked, but only one "major"
module can be registered. The "minor" modules show up in
security_init, while the majors come in via do_security_initcalls.

I am in the process of messing that all up with patches
allowing multiple major modules. Stay tuned.

>
> Cheers,
>
> Michael
>
>

Re: Documenting ptrace access mode checking

[Kees Cook]

On Fri, Jun 24, 2016 at 8:18 AM, Casey Schaufler <casey@schaufler-ca.com> wrote:
> On 6/24/2016 1:40 AM, Michael Kerrisk (man-pages) wrote:
>> So, I just want to check my understanding of a couple of points:
>>
>> 1. The commoncap LSM is invoked first, and if it denies access,
>>    then no further LSM is/needs to be called.
>
> Yes. The LSM infrastructure is "bail on fail".
>
>>
>> 2. Is it the case that only one of the other LSMs (SELinux, Yama,
>>    AppArmor, etc.) is invoked, or can more than one be invoked.
>>    I thought only one is invoked, but perhaps I am out of date
>>    in my understanding.
>
> All registered modules are invoked, but only one "major"
> module can be registered. The "minor" modules show up in
> security_init, while the majors come in via do_security_initcalls.

Just to fill in the history: prior the the recent LSM stacking changes
(v4.2), commoncap (which is effectively an LSM) was hard-coded to be
stacked with the single selected primary LSM. Then Yama got hard-coded
stacked with the primary LSM too, and then Casey saved us from total
insanity by providing a proper way to stack LSMs.

-Kees

-- 
Kees Cook
Chrome OS & Brillo Security

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

On 06/24/2016 05:18 PM, Casey Schaufler wrote:
>
>
> On 6/24/2016 1:40 AM, Michael Kerrisk (man-pages) wrote:
>> On 06/22/2016 11:11 PM, Kees Cook wrote:
>>> On Wed, Jun 22, 2016 at 12:21 PM, Michael Kerrisk (man-pages)
>>> <mtk.manpages@gmail.com> wrote:
>>>> On 06/21/2016 10:55 PM, Jann Horn wrote:
>>>>> On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages)
>>>>> wrote:
>>>>>>        5.  The  kernel LSM security_ptrace_access_check() interface is
>>>>>>            invoked to see if ptrace access is permitted.  The  results
>>>>>>            depend on the LSM.  The implementation of this interface in
>>>>>>            the default LSM performs the following steps:
>>>>>
>>>>>
>>>>> For people who are unaware of how the LSM API works, it might be good to
>>>>> clarify that the commoncap LSM is *always* invoked; otherwise, it might
>>>>> give the impression that using another LSM would replace it.
>>>>
>>>>
>>>> As we can see, I am one of those who are unaware of how the LSM API
>>>> works :-/.
>>>>
>>>>> (Also, are there other documents that refer to it as "default LSM"? I
>>>>> think that that term is slightly confusing.)
>>>>
>>>>
>>>> No, that's a terminological confusion of my own making. Fixed now.
>>>>
>>>> I changed this text to:
>>>>
>>>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>>>        operations), require so-called "ptrace access mode permissions"
>>>>        which are gated by any enabled Linux Security Module (LSMs)—for
>>>>        example,  SELinux,  Yama, or Smack—and by the the commoncap LSM
>>>>        (which is always invoked).  Prior to  Linux  2.6.27,  all  such
>>>>        checks  were  of a single type.  Since Linux 2.6.27, two access
>>>>        mode levels are distinguished:
>>>>
>>>> BTW, can you point me at the piece(s) of kernel code that show that
>>>> "commoncap" is always invoked in addition to any other LSM that has
>>>> been installed?
>>>
>>> It's not entirely obvious, but the bottom of security/commoncap.c shows:
>>>
>>> #ifdef CONFIG_SECURITY
>>>
>>> struct security_hook_list capability_hooks[] = {
>>>         LSM_HOOK_INIT(capable, cap_capable),
>>> ...
>>> };
>>>
>>> void __init capability_add_hooks(void)
>>> {
>>>         security_add_hooks(capability_hooks, ARRAY_SIZE(capability_hooks));
>>> }
>>>
>>> #endif
>>>
>>> And security/security.c shows the initialization order of the LSMs:
>>>
>>> int __init security_init(void)
>>> {
>>>         pr_info("Security Framework initialized\n");
>>>
>>>         /*
>>>          * Load minor LSMs, with the capability module always first.
>>>          */
>>>         capability_add_hooks();
>>>         yama_add_hooks();
>>>         loadpin_add_hooks();
>>>
>>>         /*
>>>          * Load all the remaining security modules.
>>>          */
>>>         do_security_initcalls();
>>>
>>>         return 0;
>>> }
>>
>> So, I just want to check my understanding of a couple of points:
>>
>> 1. The commoncap LSM is invoked first, and if it denies access,
>>    then no further LSM is/needs to be called.
>
> Yes. The LSM infrastructure is "bail on fail".
>
>>
>> 2. Is it the case that only one of the other LSMs (SELinux, Yama,
>>    AppArmor, etc.) is invoked, or can more than one be invoked.
>>    I thought only one is invoked, but perhaps I am out of date
>>    in my understanding.
>
> All registered modules are invoked, but only one "major"
> module can be registered. The "minor" modules show up in
> security_init, while the majors come in via do_security_initcalls.
>
> I am in the process of messing that all up with patches
> allowing multiple major modules. Stay tuned.

Thanks for the info, 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: Documenting ptrace access mode checking

[Jann Horn]

[-- Attachment #1: Type: text/plain, Size: 3451 bytes --]

On Wed, Jun 22, 2016 at 09:21:29PM +0200, Michael Kerrisk (man-pages) wrote:
> On 06/21/2016 10:55 PM, Jann Horn wrote:
> >On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages) wrote:
> >>Here's the new ptrace(2) text. Any comments, technical or terminological
> >>fixes, other improvements, etc. are welcome.
> >
> >As others have said, I'm surprised about seeing documentation about
> >kernel-internal constants in manpages - but I think it might be a good
> >thing to have there, given that people who look at ptrace(2) are likely
> >to be interested in low-level details.
> 
> I agree that it is a little surprising to add kernel-internal
> constants in a man page. (There are precedents, but they are few.)
> But see my reply to Kees. It's more than just explaining low level
> details: there are various kinds of user-space behavior differences
> (real vs filesystem credentials; permitted vs effective capabilities)
> produced by the ptrace_may_access() checks, and those behaviors need
> to be described and *somehow* labeled for cross-referencing from
> other man pages.

Makes sense.


> >>       The  algorithm  employed for ptrace access mode checking deter‐
> >>       mines whether the calling process is  allowed  to  perform  the
> >>       corresponding action on the target process, as follows:
> >>
> >>       1.  If the calling thread and the target thread are in the same
> >>           thread group, access is always allowed.
> >>
> >>       2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
> >>           the  check in the next step, employ the caller's filesystem
> >>           user ID and group ID (see credentials(7));  otherwise  (the
> >>           access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
> >>           caller's real user ID and group ID.
> >
> >Might want to add a "for historical reasons" or so here.
> 
> Can you be a little more precise about "here", and maybe tell me why
> you think it helps?

I'm not sure, but it might be a good idea to add something like this at the
end of 2.:
"(Most other APIs that check one of the caller's UIDs use the effective one.
This API uses the real UID instead for historical reasons.)"

In my opinion, it is inconsistent to use the real UID/GID here, the
effective one would be more appropriate. But since the existing code uses
the real UID/GID and that's not a security issue for existing users of
the ptrace API, this wasn't changed when I added the REALCREDS/FSCREDS
distinction.

I think that for a reader, it might help to point out that in most cases,
when a process is the subject in an access check, its effective UID/GID
are used, and this is (together with kill()) an exception to that rule.
But you're the expert on writing documentation, if you think that that's
too much detail / confusing here, it probably is.


> I changed this text to:
> 
>        Various parts of the kernel-user-space API (not just  ptrace(2)
>        operations), require so-called "ptrace access mode permissions"
>        which are gated by any enabled Linux Security Module (LSMs)—for
>        example,  SELinux,  Yama, or Smack—and by the the commoncap LSM
>        (which is always invoked).  Prior to  Linux  2.6.27,  all  such
>        checks  were  of a single type.  Since Linux 2.6.27, two access
>        mode levels are distinguished:

Sounds good to me.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Hi Jann,

Thanks for your further review. Follow-up of one point below.

On 06/23/2016 12:44 AM, Jann Horn wrote:
> On Wed, Jun 22, 2016 at 09:21:29PM +0200, Michael Kerrisk (man-pages) wrote:
>> On 06/21/2016 10:55 PM, Jann Horn wrote:
>>> On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages) wrote:

[...]

>>>>       The  algorithm  employed for ptrace access mode checking deter‐
>>>>       mines whether the calling process is  allowed  to  perform  the
>>>>       corresponding action on the target process, as follows:
>>>>
>>>>       1.  If the calling thread and the target thread are in the same
>>>>           thread group, access is always allowed.
>>>>
>>>>       2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>>>>           the  check in the next step, employ the caller's filesystem
>>>>           user ID and group ID (see credentials(7));  otherwise  (the
>>>>           access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>>>>           caller's real user ID and group ID.
>>>
>>> Might want to add a "for historical reasons" or so here.
>>
>> Can you be a little more precise about "here", and maybe tell me why
>> you think it helps?
>
> I'm not sure, but it might be a good idea to add something like this at the
> end of 2.:
> "(Most other APIs that check one of the caller's UIDs use the effective one.
> This API uses the real UID instead for historical reasons.)"
>
> In my opinion, it is inconsistent to use the real UID/GID here, the
> effective one would be more appropriate. But since the existing code uses
> the real UID/GID and that's not a security issue for existing users of
> the ptrace API, this wasn't changed when I added the REALCREDS/FSCREDS
> distinction.
>
> I think that for a reader, it might help to point out that in most cases,
> when a process is the subject in an access check, its effective UID/GID
> are used, and this is (together with kill()) an exception to that rule.
> But you're the expert on writing documentation, if you think that that's
> too much detail / confusing here, it probably is.

Okay -- got it now, I think. I made this text:

        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then, for
            the check in the next step, employ the caller's  filesystem
            UID  and  GID.  (As noted in credentials(7), the filesystem
            UID and GID almost always have the same values as the  cor‐
            responding effective IDs.)

            Otherwise, the access mode specifies PTRACE_MODE_REALCREDS,
            so use the caller's real UID and GID for the checks in  the
            next  step.  (Most APIs that check the caller's UID and GID
            use  the  effective  IDs.   For  historical  reasons,   the
            PTRACE_MODE_REALCREDS check uses the real IDs instead.)

[...]

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: Documenting ptrace access mode checking

[Jann Horn]

[-- Attachment #1: Type: text/plain, Size: 3075 bytes --]

On Thu, Jun 23, 2016 at 09:42:09AM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Jann,
> 
> Thanks for your further review. Follow-up of one point below.
> 
> On 06/23/2016 12:44 AM, Jann Horn wrote:
> >On Wed, Jun 22, 2016 at 09:21:29PM +0200, Michael Kerrisk (man-pages) wrote:
> >>On 06/21/2016 10:55 PM, Jann Horn wrote:
> >>>On Tue, Jun 21, 2016 at 11:41:16AM +0200, Michael Kerrisk (man-pages) wrote:
> 
> [...]
> 
> >>>>      The  algorithm  employed for ptrace access mode checking deter‐
> >>>>      mines whether the calling process is  allowed  to  perform  the
> >>>>      corresponding action on the target process, as follows:
> >>>>
> >>>>      1.  If the calling thread and the target thread are in the same
> >>>>          thread group, access is always allowed.
> >>>>
> >>>>      2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
> >>>>          the  check in the next step, employ the caller's filesystem
> >>>>          user ID and group ID (see credentials(7));  otherwise  (the
> >>>>          access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
> >>>>          caller's real user ID and group ID.
> >>>
> >>>Might want to add a "for historical reasons" or so here.
> >>
> >>Can you be a little more precise about "here", and maybe tell me why
> >>you think it helps?
> >
> >I'm not sure, but it might be a good idea to add something like this at the
> >end of 2.:
> >"(Most other APIs that check one of the caller's UIDs use the effective one.
> >This API uses the real UID instead for historical reasons.)"
> >
> >In my opinion, it is inconsistent to use the real UID/GID here, the
> >effective one would be more appropriate. But since the existing code uses
> >the real UID/GID and that's not a security issue for existing users of
> >the ptrace API, this wasn't changed when I added the REALCREDS/FSCREDS
> >distinction.
> >
> >I think that for a reader, it might help to point out that in most cases,
> >when a process is the subject in an access check, its effective UID/GID
> >are used, and this is (together with kill()) an exception to that rule.
> >But you're the expert on writing documentation, if you think that that's
> >too much detail / confusing here, it probably is.
> 
> Okay -- got it now, I think. I made this text:
> 
>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then, for
>            the check in the next step, employ the caller's  filesystem
>            UID  and  GID.  (As noted in credentials(7), the filesystem
>            UID and GID almost always have the same values as the  cor‐
>            responding effective IDs.)
> 
>            Otherwise, the access mode specifies PTRACE_MODE_REALCREDS,
>            so use the caller's real UID and GID for the checks in  the
>            next  step.  (Most APIs that check the caller's UID and GID
>            use  the  effective  IDs.   For  historical  reasons,   the
>            PTRACE_MODE_REALCREDS check uses the real IDs instead.)

Thanks, that sounds good.

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Documenting ptrace access mode checking

[Stephen Smalley]

On 06/21/2016 05:41 AM, Michael Kerrisk (man-pages) wrote:
> Hi Jann, Stephen, et al.
> 
> Jann, since you recently committed a patch in this area, and Stephen,
> since you committed 006ebb40d3d much further back in time, I wonder if
> you might help me by reviewing the text below that I propose to add to
> the ptrace(2) man page, in order to document "ptrace access mode 
> checking" that is performed in various parts of the kernel-user-space
> interface. Of course, I welcome input from anyone else as well.
> 
> Here's the new ptrace(2) text. Any comments, technical or terminological
> fixes, other improvements, etc. are welcome.
> 
> [[
>    Ptrace access mode checking
>        Various parts of the kernel-user-space API (not just  ptrace(2)
>        operations), require so-called "ptrace access mode permissions"
>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>        2.6.27, all such checks were of a  single  type.   Since  Linux
>        2.6.27, two access mode levels are distinguished:
> 
>        PTRACE_MODE_READ
>               For  "read" operations or other operations that are less
>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>               file.
> 
>        PTRACE_MODE_ATTACH
>               For  "write"  operations,  or  other operations that are
>               more    dangerous,    such    as:    ptrace    attaching
>               (PTRACE_ATTACH)    to   another   process   or   calling
>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>               tively the default before Linux 2.6.27.)

That was the intent when the distinction was introduced, but it doesn't
appear to have been properly maintained, e.g. there is now a common
helper lock_trace() that is used for
/proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show().  Likely
should review and make them consistent.  There was also some debate
about proper handling of /proc/pid/fd.  Arguably that one might belong
back in the _ATTACH camp.

> 
>        Since  Linux  4.5, the above access mode checks may be combined
>        (ORed) with one of the following modifiers:
> 
>        PTRACE_MODE_FSCREDS
>               Use the caller's filesystem UID  and  GID  (see  creden‐
>               tials(7)) or effective capabilities for LSM checks.
> 
>        PTRACE_MODE_REALCREDS
>               Use the caller's real UID and GID or permitted capabili‐
>               ties for LSM checks.  This was effectively  the  default
>               before Linux 4.5.
> 
>        Because  combining  one of the credential modifiers with one of
>        the aforementioned access modes is  typical,  some  macros  are
>        defined in the kernel sources for the combinations:
> 
>        PTRACE_MODE_READ_FSCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
> 
>        PTRACE_MODE_READ_REALCREDS
>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
> 
>        PTRACE_MODE_ATTACH_FSCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
> 
>        PTRACE_MODE_ATTACH_REALCREDS
>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
> 
>        One further modifier can be ORed with the access mode:
> 
>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>               Don't audit this access mode check.
> 
> [I'd quite welcome some text to explain "auditing" here.]

Some ptrace access mode checks, such as checks when reading
/proc/pid/stat, merely cause the output to be filtered/sanitized rather
than an error to be returned to the caller.  In these cases, accessing
the file is not a security violation and there is no reason to generate
a security audit record.  This modifier suppresses the generation of
such an audit record for the particular access check.

> 
>        The  algorithm  employed for ptrace access mode checking deter‐
>        mines whether the calling process is  allowed  to  perform  the
>        corresponding action on the target process, as follows:
> 
>        1.  If the calling thread and the target thread are in the same
>            thread group, access is always allowed.
> 
>        2.  If the access mode specifies PTRACE_MODE_FSCREDS, then  for
>            the  check in the next step, employ the caller's filesystem
>            user ID and group ID (see credentials(7));  otherwise  (the
>            access  mode  specifies  PTRACE_MODE_REALCREDS, so) use the
>            caller's real user ID and group ID.
> 
>        3.  Deny access if neither of the following is true:
> 
>            · The real, effective, and saved-set user IDs of the target
>              match  the caller's user ID, and the real, effective, and
>              saved-set group IDs of  the  target  match  the  caller's
>              group ID.
> 
>            · The caller has the CAP_SYS_PTRACE capability.
> 
>        4.  Deny  access if the target process "dumpable" attribute has
>            a value other than 1 (SUID_DUMP_USER; see the discussion of
>            PR_SET_DUMPABLE  in prctl(2)), and the caller does not have
>            the CAP_SYS_PTRACE capability in the user namespace of  the
>            target process.
> 
>        5.  The  kernel LSM security_ptrace_access_check() interface is
>            invoked to see if ptrace access is permitted.  The  results
>            depend on the LSM.  The implementation of this interface in
>            the default LSM performs the following steps:
> 
>            a) If the access mode  includes  PTRACE_MODE_FSCREDS,  then
>               use the caller's effective capability set in the follow‐
>               ing  check;  otherwise  (the   access   mode   specifies
>               PTRACE_MODE_REALCREDS,  so)  use  the caller's permitted
>               capability set.
> 
>            b) Deny access if neither of the following is true:
> 
>               · The caller's capabilities are a proper superset of the
>                 target process's permitted capabilities.
> 
>               · The  caller  has  the CAP_SYS_PTRACE capability in the
>                 target process's user namespace.
> 
>               Note that the default LSM does not  distinguish  between
>               PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
> 
>        6.  If  access  has  not  been  denied  by any of the preceding
>            steps, then access is allowed.
> ]]
> 
> There are accompanying changes to various pages that refer to 
> the new text in ptrace(2), so that, for example, kcmp(2) adds:
> 
>        Permission  to  employ kcmp() is governed by ptrace access mode
>        PTRACE_MODE_ATTACH_REALCREDS checks against both pid1 and pid2;
>        see ptrace(2).
> 
> and proc.5 has additions such as:
> 
>        /proc/[pid]/auxv (since 2.6.0-test7)
>               ...
>               Permission to access this file is governed by  a  ptrace
>               access    mode   PTRACE_MODE_READ_FSCREDS   check;   see
>               ptrace(2).
> 
>        /proc/[pid]/cwd
>               ...
>               Permission to dereference  or  read  (readlink(2))  this
>               symbolic  link  is  governed  by  a  ptrace  access mode
>               PTRACE_MODE_READ_FSCREDS check; see ptrace(2).
> 
> Thanks,
> 
> Michael
> 

Re: Documenting ptrace access mode checking

[Michael Kerrisk (man-pages)]

Stephen,

On 06/23/2016 08:05 PM, Stephen Smalley wrote:
> On 06/21/2016 05:41 AM, Michael Kerrisk (man-pages) wrote:
>> Hi Jann, Stephen, et al.
>>
>> Jann, since you recently committed a patch in this area, and Stephen,
>> since you committed 006ebb40d3d much further back in time, I wonder if
>> you might help me by reviewing the text below that I propose to add to
>> the ptrace(2) man page, in order to document "ptrace access mode
>> checking" that is performed in various parts of the kernel-user-space
>> interface. Of course, I welcome input from anyone else as well.
>>
>> Here's the new ptrace(2) text. Any comments, technical or terminological
>> fixes, other improvements, etc. are welcome.
>>
>> [[
>>    Ptrace access mode checking
>>        Various parts of the kernel-user-space API (not just  ptrace(2)
>>        operations), require so-called "ptrace access mode permissions"
>>        which are gated  by  Linux  Security  Modules  (LSMs)  such  as
>>        SELinux,  Yama,  Smack,  or  the  default  LSM.  Prior to Linux
>>        2.6.27, all such checks were of a  single  type.   Since  Linux
>>        2.6.27, two access mode levels are distinguished:
>>
>>        PTRACE_MODE_READ
>>               For  "read" operations or other operations that are less
>>               dangerous, such as: get_robust_list(2); kcmp(2); reading
>>               /proc/[pid]/auxv,         /proc/[pid]/environ,        or
>>               /proc/[pid]/stat; or readlink(2) of  a  /proc/[pid]/ns/*
>>               file.
>>
>>        PTRACE_MODE_ATTACH
>>               For  "write"  operations,  or  other operations that are
>>               more    dangerous,    such    as:    ptrace    attaching
>>               (PTRACE_ATTACH)    to   another   process   or   calling
>>               process_vm_writev(2).   (PTRACE_MODE_ATTACH  was  effec‐
>>               tively the default before Linux 2.6.27.)
>
> That was the intent when the distinction was introduced, but it doesn't
> appear to have been properly maintained, e.g. there is now a common
> helper lock_trace() that is used for
> /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
> PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show().  Likely
> should review and make them consistent.  There was also some debate
> about proper handling of /proc/pid/fd.  Arguably that one might belong
> back in the _ATTACH camp.

Thanks for the background info.

>>        Since  Linux  4.5, the above access mode checks may be combined
>>        (ORed) with one of the following modifiers:
>>
>>        PTRACE_MODE_FSCREDS
>>               Use the caller's filesystem UID  and  GID  (see  creden‐
>>               tials(7)) or effective capabilities for LSM checks.
>>
>>        PTRACE_MODE_REALCREDS
>>               Use the caller's real UID and GID or permitted capabili‐
>>               ties for LSM checks.  This was effectively  the  default
>>               before Linux 4.5.
>>
>>        Because  combining  one of the credential modifiers with one of
>>        the aforementioned access modes is  typical,  some  macros  are
>>        defined in the kernel sources for the combinations:
>>
>>        PTRACE_MODE_READ_FSCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_READ_REALCREDS
>>               Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
>>
>>        PTRACE_MODE_ATTACH_FSCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
>>
>>        PTRACE_MODE_ATTACH_REALCREDS
>>               Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
>>
>>        One further modifier can be ORed with the access mode:
>>
>>        PTRACE_MODE_NOAUDIT (since Linux 3.3)
>>               Don't audit this access mode check.
>>
>> [I'd quite welcome some text to explain "auditing" here.]
>
> Some ptrace access mode checks, such as checks when reading
> /proc/pid/stat, merely cause the output to be filtered/sanitized rather
> than an error to be returned to the caller.  In these cases, accessing
> the file is not a security violation and there is no reason to generate
> a security audit record.  This modifier suppresses the generation of
> such an audit record for the particular access check.

Thanks, I've added that text to the man page more or less as you
gave it here.

Cheers,

Michael



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