| Message ID | 20200910210059.34759-1-stephen.smalley.work@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | socket.7,unix.7: add initial description for SO_PEERSEC | expand |
On Thu, 10 Sep 2020 at 17:00:59 -0400, Stephen Smalley wrote: > +For SELinux, the security context string is a null-terminated > +string and the returned length includes the terminating null. > +Other security modules may differ. We discussed this interface a while ago when I was setting up dbus to use SO_PEERSEC. It would be really useful if the man page documented what callers can and can't expect from an unknown LSM, so that the author of the next D-Bus-equivalent doesn't have to turn up on the linux-security-module list and annoy maintainers like I did. Perhaps something like this? The security context string may include a terminating null character in the returned length, but is not guaranteed to do so: a security context "foo" might be represented as either {'f','o','o'} of length 3 or {'f','o','o','\0'} of length 4, which are considered to be interchangeable. It is printable, does not contain non-terminating null characters, and is in an unspecified encoding (in particular it is not guaranteed to be ASCII or UTF-8). Thanks, smcv
On Fri, Sep 11, 2020 at 5:23 AM Simon McVittie <smcv@collabora.com> wrote: > > On Thu, 10 Sep 2020 at 17:00:59 -0400, Stephen Smalley wrote: > > +For SELinux, the security context string is a null-terminated > > +string and the returned length includes the terminating null. > > +Other security modules may differ. > > We discussed this interface a while ago when I was setting up dbus to > use SO_PEERSEC. It would be really useful if the man page documented > what callers can and can't expect from an unknown LSM, so that the > author of the next D-Bus-equivalent doesn't have to turn up on the > linux-security-module list and annoy maintainers like I did. > > Perhaps something like this? > > The security context string may include a terminating null character > in the returned length, but is not guaranteed to do so: > a security context "foo" might be represented as either {'f','o','o'} > of length 3 or {'f','o','o','\0'} of length 4, which are considered > to be interchangeable. It is printable, does not contain non-terminating > null characters, and is in an unspecified encoding (in particular it is > not guaranteed to be ASCII or UTF-8). Works for me. Do the security subsystem maintainers concur?
On Thu, Sep 10, 2020 at 5:01 PM Stephen Smalley <stephen.smalley.work@gmail.com> wrote: > > SO_PEERSEC was introduced for AF_UNIX stream sockets connected via > connect(2) in Linux 2.6.2 and later augmented to support AF_UNIX stream > and datagram sockets created via socketpair(2) in Linux 4.18. Document > SO_PEERSEC in the socket.7 and unix.7 man pages following the example > of the existing SO_PEERCRED descriptions. SO_PEERSEC is also supported > on AF_INET sockets when using labeled IPSEC or NetLabel but defer > adding a description of that support to a separate patch. > > Signed-off-by: Stephen Smalley <stephen.smalley.work@gmail.com> Here are the relevant commits introducing SO_PEERSEC and the socketpair support (the first one is from the pre-git history tree since it predates git): https://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git/commit/?id=da6e57a2e6bd7939f610d957afacaf6a131e75ed https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0b811db2cb2aabc910e53d34ebb95a15997c33e7 Can add those into the commit message. Not sure if you want them in the man pages themselves (especially the first pre-git one).
diff --git a/man7/socket.7 b/man7/socket.7 index 21e891791..c3635f95b 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -690,6 +690,11 @@ Return the credentials of the peer process connected to this socket. For further details, see .BR unix (7). .TP +.BR SO_PEERSEC " (since Linux 2.6.2)" +Return the security context of the peer socket connected to this socket. +For further details, see +.BR unix (7). +.TP .B SO_PRIORITY Set the protocol-defined priority for all packets to be sent on this socket. diff --git a/man7/unix.7 b/man7/unix.7 index f61b51424..1032c0aa1 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -349,6 +349,46 @@ stream sockets and for .B AF_UNIX stream and datagram socket pairs created using .BR socketpair (2). +.TP +.B SO_PEERSEC +This read-only socket option returns the +security context of the peer socket connected to this socket. +By default, this will be the same as the security context of +the process that created the peer socket unless overridden +by the policy or by a process with the required permissions. +.IP +The argument to +.BR getsockopt (2) +is a pointer to a +buffer of the specified length in bytes +into which the security context string will be copied. +If the buffer length is less than the length of the security +context string, then +.BR getsockopt (2) +will return the required length +via +.I optlen +and return \-1 and sets +.I errno +to +.BR ERANGE . +The caller should allocate at least +.BR NAME_MAX +bytes for the buffer initially although this is not guaranteed +to be sufficient. Resizing the buffer to the returned length +and retrying may be necessary. +.IP +For SELinux, the security context string is a null-terminated +string and the returned length includes the terminating null. +Other security modules may differ. +.IP +The use of this option for sockets in the +.B AF_UNIX +address family +is supported since Linux 2.6.2 for connected stream sockets and +since Linux 4.18, also for stream and datagram socket pairs created +using +.BR socketpair (2). .\" .SS Autobind feature If a
SO_PEERSEC was introduced for AF_UNIX stream sockets connected via connect(2) in Linux 2.6.2 and later augmented to support AF_UNIX stream and datagram sockets created via socketpair(2) in Linux 4.18. Document SO_PEERSEC in the socket.7 and unix.7 man pages following the example of the existing SO_PEERCRED descriptions. SO_PEERSEC is also supported on AF_INET sockets when using labeled IPSEC or NetLabel but defer adding a description of that support to a separate patch. Signed-off-by: Stephen Smalley <stephen.smalley.work@gmail.com> --- man7/socket.7 | 5 +++++ man7/unix.7 | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+)