diff mbox series

ip.7: Document IP_PASSSEC for UDP sockets

Message ID 20200917173143.57241-1-stephen.smalley.work@gmail.com (mailing list archive)
State New, archived
Headers show
Series ip.7: Document IP_PASSSEC for UDP sockets | expand

Commit Message

Stephen Smalley Sept. 17, 2020, 5:31 p.m. UTC 
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@gmail.com>
---
 man7/ip.7 | 48 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 6 deletions(-)

Comments

Paul Moore Sept. 17, 2020, 11:16 p.m. UTC | #1 
On Thu, Sep 17, 2020 at 1:31 PM Stephen Smalley
<stephen.smalley.work@gmail.com> 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@gmail.com>
> ---
>  man7/ip.7 | 48 ++++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 42 insertions(+), 6 deletions(-)

Thanks for including the note about the SCM_SECURITY/IP_HDRINCL
conflict.  I figure it's probably not the best for another SELinux
person to ACK this, but I will mark it as "reviewed".

Reviewed-by: Paul Moore <paul@paul-moore.com>
Michael Kerrisk (man-pages) Sept. 19, 2020, 8:23 a.m. UTC | #2 
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@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@watson.ibm.com>
> -.\"
>  .\"	IP_MINTTL (2.6.34)
>  .\"	    commit d218d11133d888f9745802146a50255a4781d37a
>  .\"	    Author: Stephen Hemminger <shemminger@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
>
diff mbox series

Patch

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@watson.ibm.com>
-.\"
 .\"	IP_MINTTL (2.6.34)
 .\"	    commit d218d11133d888f9745802146a50255a4781d37a
 .\"	    Author: Stephen Hemminger <shemminger@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