diff mbox series

socket.7,ip.7: Document SO_PEERSEC for AF_INET sockets

Message ID 20200915163959.25334-1-stephen.smalley.work@gmail.com
State New
Headers show
Series socket.7,ip.7: Document SO_PEERSEC for AF_INET sockets | expand

Commit Message

Stephen Smalley Sept. 15, 2020, 4:39 p.m. UTC
Augment the description of SO_PEERSEC to cover AF_INET sockets
in addition to the prior description for AF_UNIX.

SO_PEERSEC for TCP sockets was introduced in Linux 2.6.17 [1], and
SO_PEERSEC for SCTP sockets was introduced in Linux 4.17 [2].

This does not cover usage of SCM_SECURITY for UDP sockets, which
was also introduced in the same commit for 2.6.17.

Examples of the necessary labeled IPSEC and NetLabel configurations
to enable use of SO_PEERSEC for TCP and SCTP sockets can be found in
the SELinux Notebook [3] and the selinux-testsuite [4].

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

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

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

[4] https://github.com/SELinuxProject/selinux-testsuite
---
 man7/ip.7     | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++
 man7/socket.7 |  2 +-
 2 files changed, 57 insertions(+), 1 deletion(-)

Comments

Michael Kerrisk (man-pages) Sept. 17, 2020, 7:30 a.m. UTC | #1
Hello Stephen

On 9/15/20 6:39 PM, Stephen Smalley wrote:
> Augment the description of SO_PEERSEC to cover AF_INET sockets
> in addition to the prior description for AF_UNIX.
> 
> SO_PEERSEC for TCP sockets was introduced in Linux 2.6.17 [1], and
> SO_PEERSEC for SCTP sockets was introduced in Linux 4.17 [2].
> 
> This does not cover usage of SCM_SECURITY for UDP sockets, which
> was also introduced in the same commit for 2.6.17.

(Would you by chance be able to write a patch for this also?)

> Examples of the necessary labeled IPSEC and NetLabel configurations
> to enable use of SO_PEERSEC for TCP and SCTP sockets can be found in
> the SELinux Notebook [3] and the selinux-testsuite [4].
> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=2c7946a7bf45ae86736ab3b43d0085e43947945c
> 
> [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d452930fd3b9031e59abfeddb2fa383f1403d61a
> 
> [3] https://github.com/SELinuxProject/selinux-notebook
> 
> [4] https://github.com/SELinuxProject/selinux-testsuite

Thanks. I've applied the patch. I'll wait a few hours before pushing
in case Reviews/Acks come in.

Thanks,

Michael

> ---
>  man7/ip.7     | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  man7/socket.7 |  2 +-
>  2 files changed, 57 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/ip.7 b/man7/ip.7
> index c522b219c..03a9f3f7c 100644
> --- a/man7/ip.7
> +++ b/man7/ip.7
> @@ -979,6 +979,62 @@ Argument is an
>  .I ip_mreq_source
>  structure as described under
>  .BR IP_ADD_SOURCE_MEMBERSHIP .
> +.TP
> +.BR SO_PEERSEC " (since Linux 2.6.17)"
> +If labeled IPSEC or NetLabel is configured on both the sending and
> +receiving hosts, this read-only socket option returns the security
> +context of the peer socket connected to this socket.  By default, this
> +will be the same as the security context of the process that created
> +the peer socket unless overridden by the policy or by a process with
> +the required permissions.
> +.IP
> +The argument to
> +.BR getsockopt (2)
> +is a pointer to a
> +buffer of the specified length in bytes
> +into which the security context string will be copied.
> +If the buffer length is less than the length of the security
> +context string, then
> +.BR getsockopt (2)
> +will return the required length
> +via
> +.I optlen
> +and return \-1 and sets
> +.I errno
> +to
> +.BR ERANGE .
> +The caller should allocate at least
> +.BR NAME_MAX
> +bytes for the buffer initially although this is not guaranteed
> +to be sufficient.  Resizing the buffer to the returned length
> +and retrying may be necessary.
> +.IP
> +The security context string may include a terminating null character
> +in the returned length, but is not guaranteed to do so: a security
> +context "foo" might be represented as either {'f','o','o'} of length 3
> +or {'f','o','o','\\0'} of length 4, which are considered to be
> +interchangeable. It is printable, does not contain non-terminating
> +null characters, and is in an unspecified encoding (in particular it
> +is not guaranteed to be ASCII or UTF-8).
> +.IP
> +The use of this option for sockets in the
> +.B AF_INET
> +address family
> +is supported since Linux 2.6.17
> +.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
> +for TCP sockets and since Linux
> +4.17
> +.\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a
> +for SCTP sockets.
> +.IP
> +For SELinux, NetLabel only conveys the MLS portion of the security
> +context of the peer across the wire, defaulting the rest of the
> +security context to the values defined in the policy for the
> +netmsg initial security identifier (SID). However, NetLabel can
> +be configured to pass full security contexts over loopback.  Labeled
> +IPSEC always passes full security contexts as part of establishing
> +the security association (SA) and looks them up based on the association
> +for each packet.
>  .SS /proc interfaces
>  The IP protocol
>  supports a set of
> diff --git a/man7/socket.7 b/man7/socket.7
> index c3635f95b..2f9039333 100644
> --- a/man7/socket.7
> +++ b/man7/socket.7
> @@ -693,7 +693,7 @@ For further details, see
>  .BR SO_PEERSEC " (since Linux 2.6.2)"
>  Return the security context of the peer socket connected to this socket.
>  For further details, see
> -.BR unix (7).
> +.BR unix (7) and ip(7).
>  .TP
>  .B SO_PRIORITY
>  Set the protocol-defined priority for all packets to be sent on
>
diff mbox series

Patch

diff --git a/man7/ip.7 b/man7/ip.7
index c522b219c..03a9f3f7c 100644
--- a/man7/ip.7
+++ b/man7/ip.7
@@ -979,6 +979,62 @@  Argument is an
 .I ip_mreq_source
 structure as described under
 .BR IP_ADD_SOURCE_MEMBERSHIP .
+.TP
+.BR SO_PEERSEC " (since Linux 2.6.17)"
+If labeled IPSEC or NetLabel is configured on both the sending and
+receiving hosts, this read-only socket option returns the security
+context of the peer socket connected to this socket.  By default, this
+will be the same as the security context of the process that created
+the peer socket unless overridden by the policy or by a process with
+the required permissions.
+.IP
+The argument to
+.BR getsockopt (2)
+is a pointer to a
+buffer of the specified length in bytes
+into which the security context string will be copied.
+If the buffer length is less than the length of the security
+context string, then
+.BR getsockopt (2)
+will return the required length
+via
+.I optlen
+and return \-1 and sets
+.I errno
+to
+.BR ERANGE .
+The caller should allocate at least
+.BR NAME_MAX
+bytes for the buffer initially although this is not guaranteed
+to be sufficient.  Resizing the buffer to the returned length
+and retrying may be necessary.
+.IP
+The security context string may include a terminating null character
+in the returned length, but is not guaranteed to do so: a security
+context "foo" might be represented as either {'f','o','o'} of length 3
+or {'f','o','o','\\0'} of length 4, which are considered to be
+interchangeable. It is printable, does not contain non-terminating
+null characters, and is in an unspecified encoding (in particular it
+is not guaranteed to be ASCII or UTF-8).
+.IP
+The use of this option for sockets in the
+.B AF_INET
+address family
+is supported since Linux 2.6.17
+.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
+for TCP sockets and since Linux
+4.17
+.\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a
+for SCTP sockets.
+.IP
+For SELinux, NetLabel only conveys the MLS portion of the security
+context of the peer across the wire, defaulting the rest of the
+security context to the values defined in the policy for the
+netmsg initial security identifier (SID). However, NetLabel can
+be configured to pass full security contexts over loopback.  Labeled
+IPSEC always passes full security contexts as part of establishing
+the security association (SA) and looks them up based on the association
+for each packet.
 .SS /proc interfaces
 The IP protocol
 supports a set of
diff --git a/man7/socket.7 b/man7/socket.7
index c3635f95b..2f9039333 100644
--- a/man7/socket.7
+++ b/man7/socket.7
@@ -693,7 +693,7 @@  For further details, see
 .BR SO_PEERSEC " (since Linux 2.6.2)"
 Return the security context of the peer socket connected to this socket.
 For further details, see
-.BR unix (7).
+.BR unix (7) and ip(7).
 .TP
 .B SO_PRIORITY
 Set the protocol-defined priority for all packets to be sent on