[PATCH] ip.7: Document IP_PASSSEC for UDP sockets

[Stephen Smalley]

Document the IP_PASSSEC socket option and SCM_SECURITY
ancillary/control message type for UDP sockets.

IP_PASSSEC for UDP sockets was introduced in Linux 2.6.17 [1].

Example NetLabel and IPSEC configurations and usage of this option
can be found in the SELinux Notebook [2] and SELinux testsuite [3].

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

[2] https://github.com/SELinuxProject/selinux-notebook

[3] https://github.com/SELinuxProject/selinux-testsuite

Signed-off-by: Stephen Smalley <stephen.smalley.work at gmail.com>
---
 man7/ip.7 | 48 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/man7/ip.7 b/man7/ip.7
index 03a9f3f7c..681234c90 100644
--- a/man7/ip.7
+++ b/man7/ip.7
@@ -17,11 +17,6 @@
 .\" 	IP_IPSEC_POLICY (2.5.47)
 .\"	    Needs CAP_NET_ADMIN
 .\"
-.\" 	IP_PASSSEC (2.6.17)
-.\" 	    Boolean
-.\"	    commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
-.\"	    Author: Catherine Zhang <cxzhang at watson.ibm.com>
-.\"
 .\"	IP_MINTTL (2.6.34)
 .\"	    commit d218d11133d888f9745802146a50255a4781d37a
 .\"	    Author: Stephen Hemminger <shemminger at vyatta.com>
@@ -664,6 +659,47 @@ with
 .B IP_OPTIONS
 puts the current IP options used for sending into the supplied buffer.
 .TP
+.BR IP_PASSSEC " (since Linux 2.6.17)"
+.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
+If labeled IPSEC or NetLabel is configured on the sending and receiving
+hosts, this option enables receiving of the security context of the peer
+socket in an ancillary message of type
+.B SCM_SECURITY
+retrieved using
+.BR recvmsg (2).
+This option is only supported for UDP sockets; for TCP or SCTP sockets,
+see the description of the
+.B SO_PEERSEC
+option below.
+.IP
+The value given as an argument to
+.BR setsockopt (2)
+and returned as the result of
+.BR getsockopt (2)
+is an integer boolean flag.
+.IP
+The security context returned in the
+.B SCM_SECURITY
+ancillary message
+is of the same format as the one described under the
+.B SO_PEERSEC
+option below.
+.IP
+NOTE: The reuse of the
+.B SCM_SECURITY
+message type
+for the
+.B IP_PASSSEC
+socket option was likely a mistake since other IP control messages use
+their own numbering scheme in the IP namespace and often use the
+socket option value as the message type.  There is no conflict
+currently since the IP option with the same value
+as
+.B SCM_SECURITY
+is
+.B IP_HDRINCL
+and this is never used for a control message type.
+.TP
 .BR IP_PKTINFO " (since Linux 2.2)"
 .\" Precisely: 2.1.68
 Pass an
@@ -1290,13 +1326,13 @@ and
 .BR IP_MTU ,
 .BR IP_MTU_DISCOVER ,
 .BR IP_RECVORIGDSTADDR ,
+.BR IP_PASSSEC ,
 .BR IP_PKTINFO ,
 .BR IP_RECVERR ,
 .BR IP_ROUTER_ALERT ,
 and
 .BR IP_TRANSPARENT
 are Linux-specific.
-.\" IP_PASSSEC is Linux-specific
 .\" IP_XFRM_POLICY is Linux-specific
 .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs
 .PP
-- 
2.25.1