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
