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

[Michael Kerrisk (man-pages)]

Hello Stephen,

On 9/17/20 7:31 PM, Stephen Smalley wrote:
> 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>

Thanks. I've applied this patch, and added Pauls 'Reviewed-by:'

Cheers,

Michael

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


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