[PATCH] socket.7,unix.7: add initial description for SO_PEERSEC

[PATCH] socket.7,unix.7: add initial description for SO_PEERSEC

[Stephen Smalley]

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(+)

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
-- 
2.25.1

Re: [PATCH] socket.7,unix.7: add initial description for SO_PEERSEC

[Simon McVittie]

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

Re: [PATCH] socket.7,unix.7: add initial description for SO_PEERSEC

[Stephen Smalley]

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?

Re: [PATCH] socket.7,unix.7: add initial description for SO_PEERSEC

[Stephen Smalley]

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).