From 755b3ecb73616c4d80715ac44d69215f562acf4a Mon Sep 17 00:00:00 2001 From: Stephen Smalley Date: Thu, 17 Sep 2020 13:31:43 -0400 Subject: [PATCH] ip.7: Document IP_PASSSEC for UDP sockets 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 Reviewed-by: Paul Moore Signed-off-by: Stephen Smalley Signed-off-by: Michael Kerrisk --- man7/ip.7 | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/man7/ip.7 b/man7/ip.7 index c1ce6aa5f..2d9b9b760 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 -.\" .\" IP_MINTTL (2.6.34) .\" commit d218d11133d888f9745802146a50255a4781d37a .\" Author: Stephen Hemminger @@ -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 @@ -1291,13 +1327,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