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

[PATCH v2] 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 [1] and later augmented to support AF_UNIX stream
and datagram sockets created via socketpair(2) in Linux 4.18 [2].  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.

The module-independent description of the security context returned
by SO_PEERSEC is from Simon McVittie <smcv@collabora.com>.

[1] https://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git/commit/?id=da6e57a2e6bd7939f610d957afacaf6a131e75ed

[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0b811db2cb2aabc910e53d34ebb95a15997c33e7

Signed-off-by: Stephen Smalley <stephen.smalley.work@gmail.com>
---
v2 adds kernel commit info to the description and man page and uses
the suggested text from Simon McVittie for the description of
the security context string in a module-neutral way.

 man7/socket.7 |  5 +++++
 man7/unix.7   | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 51 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 50828a5bc..298521d4a 100644
--- a/man7/unix.7
+++ b/man7/unix.7
@@ -349,6 +349,52 @@ 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
+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).
+.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,
+.\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7
+also for stream and datagram socket pairs created
+using
+.BR socketpair (2).
 .\"
 .SS Autobind feature
 If a
-- 
2.25.1

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

[Michael Kerrisk (man-pages)]

Hello Stephen,

On Mon, 14 Sep 2020 at 20:07, 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 [1] and later augmented to support AF_UNIX stream
> and datagram sockets created via socketpair(2) in Linux 4.18 [2].  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.
>
> The module-independent description of the security context returned
> by SO_PEERSEC is from Simon McVittie <smcv@collabora.com>.

Thanks for the patch, The text looks in reasonable shape to me. I'm
just hanging off applying for a bit in case some Reviewed/Acked-by
comes in.

Cheers,

Michael


> [1] https://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git/commit/?id=da6e57a2e6bd7939f610d957afacaf6a131e75ed
>
> [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0b811db2cb2aabc910e53d34ebb95a15997c33e7
>
> Signed-off-by: Stephen Smalley <stephen.smalley.work@gmail.com>
> ---
> v2 adds kernel commit info to the description and man page and uses
> the suggested text from Simon McVittie for the description of
> the security context string in a module-neutral way.
>
>  man7/socket.7 |  5 +++++
>  man7/unix.7   | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 51 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 50828a5bc..298521d4a 100644
> --- a/man7/unix.7
> +++ b/man7/unix.7
> @@ -349,6 +349,52 @@ 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
> +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).
> +.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,
> +.\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7
> +also for stream and datagram socket pairs created
> +using
> +.BR socketpair (2).
>  .\"
>  .SS Autobind feature
>  If a
> --
> 2.25.1
>


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

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

[Serge E. Hallyn]

On Tue, Sep 15, 2020 at 10:56:18AM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Stephen,
> 
> On Mon, 14 Sep 2020 at 20:07, 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 [1] and later augmented to support AF_UNIX stream
> > and datagram sockets created via socketpair(2) in Linux 4.18 [2].  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.
> >
> > The module-independent description of the security context returned
> > by SO_PEERSEC is from Simon McVittie <smcv@collabora.com>.
> 
> Thanks for the patch, The text looks in reasonable shape to me. I'm
> just hanging off applying for a bit in case some Reviewed/Acked-by
> comes in.
> 

fwiw just as someone who's used this,

Reviewed-by: Serge Hallyn <serge@hallyn.com>

Thanks Stephen, thanks Michael.

> Cheers,
> 
> Michael
> 
> 
> > [1] https://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git/commit/?id=da6e57a2e6bd7939f610d957afacaf6a131e75ed
> >
> > [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0b811db2cb2aabc910e53d34ebb95a15997c33e7
> >
> > Signed-off-by: Stephen Smalley <stephen.smalley.work@gmail.com>
> > ---
> > v2 adds kernel commit info to the description and man page and uses
> > the suggested text from Simon McVittie for the description of
> > the security context string in a module-neutral way.
> >
> >  man7/socket.7 |  5 +++++
> >  man7/unix.7   | 46 ++++++++++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 51 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 50828a5bc..298521d4a 100644
> > --- a/man7/unix.7
> > +++ b/man7/unix.7
> > @@ -349,6 +349,52 @@ 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
> > +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).
> > +.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,
> > +.\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7
> > +also for stream and datagram socket pairs created
> > +using
> > +.BR socketpair (2).
> >  .\"
> >  .SS Autobind feature
> >  If a
> > --
> > 2.25.1
> >
> 
> 
> -- 
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/

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

[Michael Kerrisk (man-pages)]

Hello Stephen,

On 9/14/20 8:07 PM, Stephen Smalley wrote:
> SO_PEERSEC was introduced for AF_UNIX stream sockets connected via
> connect(2) in Linux 2.6.2 [1] and later augmented to support AF_UNIX stream
> and datagram sockets created via socketpair(2) in Linux 4.18 [2].  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.
> 
> The module-independent description of the security context returned
> by SO_PEERSEC is from Simon McVittie <smcv@collabora.com>.
> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git/commit/?id=da6e57a2e6bd7939f610d957afacaf6a131e75ed
> 
> [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0b811db2cb2aabc910e53d34ebb95a15997c33e7
> 
> Signed-off-by: Stephen Smalley <stephen.smalley.work@gmail.com>
> ---
> v2 adds kernel commit info to the description and man page and uses
> the suggested text from Simon McVittie for the description of
> the security context string in a module-neutral way.

Thanks. I've applied this patch, and added Serge's Reviewed-by.

Cheers,

Michael

> 
>  man7/socket.7 |  5 +++++
>  man7/unix.7   | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 51 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 50828a5bc..298521d4a 100644
> --- a/man7/unix.7
> +++ b/man7/unix.7
> @@ -349,6 +349,52 @@ 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
> +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).
> +.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,
> +.\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7
> +also for stream and datagram socket pairs created
> +using
> +.BR socketpair (2).
>  .\"
>  .SS Autobind feature
>  If a
> 


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