| Message ID | 20200917173143.57241-1-stephen.smalley.work@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Delegated to: | Stephen Smalley |
| Headers | show |
| Series | ip.7: Document IP_PASSSEC for UDP sockets | expand |
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>
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 --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
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(-)