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

[Stephen Smalley]

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.

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