[PATCH] socket.7,ip.7: Document SO_PEERSEC for AF_INET sockets

[Michael Kerrisk (man-pages)]

Hello Stephen

On 9/15/20 6:39 PM, Stephen Smalley wrote:
> Augment the description of SO_PEERSEC to cover AF_INET sockets
> in addition to the prior description for AF_UNIX.
> 
> SO_PEERSEC for TCP sockets was introduced in Linux 2.6.17 [1], and
> SO_PEERSEC for SCTP sockets was introduced in Linux 4.17 [2].
> 
> This does not cover usage of SCM_SECURITY for UDP sockets, which
> was also introduced in the same commit for 2.6.17.

(Would you by chance be able to write a patch for this also?)

> Examples of the necessary labeled IPSEC and NetLabel configurations
> to enable use of SO_PEERSEC for TCP and SCTP sockets can be found in
> the SELinux Notebook [3] and the selinux-testsuite [4].
> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=2c7946a7bf45ae86736ab3b43d0085e43947945c
> 
> [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d452930fd3b9031e59abfeddb2fa383f1403d61a
> 
> [3] https://github.com/SELinuxProject/selinux-notebook
> 
> [4] https://github.com/SELinuxProject/selinux-testsuite

Thanks. I've applied the patch. I'll wait a few hours before pushing
in case Reviews/Acks come in.

Thanks,

Michael

> ---
>  man7/ip.7     | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  man7/socket.7 |  2 +-
>  2 files changed, 57 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/ip.7 b/man7/ip.7
> index c522b219c..03a9f3f7c 100644
> --- a/man7/ip.7
> +++ b/man7/ip.7
> @@ -979,6 +979,62 @@ Argument is an
>  .I ip_mreq_source
>  structure as described under
>  .BR IP_ADD_SOURCE_MEMBERSHIP .
> +.TP
> +.BR SO_PEERSEC " (since Linux 2.6.17)"
> +If labeled IPSEC or NetLabel is configured on both the sending and
> +receiving hosts, 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_INET
> +address family
> +is supported since Linux 2.6.17
> +.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
> +for TCP sockets and since Linux
> +4.17
> +.\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a
> +for SCTP sockets.
> +.IP
> +For SELinux, NetLabel only conveys the MLS portion of the security
> +context of the peer across the wire, defaulting the rest of the
> +security context to the values defined in the policy for the
> +netmsg initial security identifier (SID). However, NetLabel can
> +be configured to pass full security contexts over loopback.  Labeled
> +IPSEC always passes full security contexts as part of establishing
> +the security association (SA) and looks them up based on the association
> +for each packet.
>  .SS /proc interfaces
>  The IP protocol
>  supports a set of
> diff --git a/man7/socket.7 b/man7/socket.7
> index c3635f95b..2f9039333 100644
> --- a/man7/socket.7
> +++ b/man7/socket.7
> @@ -693,7 +693,7 @@ For further details, see
>  .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).
> +.BR unix (7) and ip(7).
>  .TP
>  .B SO_PRIORITY
>  Set the protocol-defined priority for all packets to be sent on
> 


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