MFC r313174: Clean up documentation of AF_UNIX control messages.

Document AF_UNIX control messages in unix(4) only, not split between unix(4)
and recv(2).

Also, warn about LOCAL_CREDS effective uid/gid fields, since the write could
be from a setuid or setgid program (with the explicit SCM_CREDS and
LOCAL_PEERCRED, the credentials are read at such a time that it can be
assumed that the process intends for them to be used in this context).

2 files changed, 76 insertions, 60 deletions

diff --git a/lib/libc/sys/recv.2 b/lib/libc/sys/recv.2
index 4867ea7..36a8a9d 100644
--- a/lib/libc/sys/recv.2
+++ b/lib/libc/sys/recv.2
@@ -28,7 +28,7 @@
 .\"     @(#)recv.2	8.3 (Berkeley) 2/21/94
 .\" $FreeBSD$
 .\"
-.Dd January 29, 2016
+.Dd February 3, 2017
 .Dt RECV 2
 .Os
 .Sh NAME
@@ -267,57 +267,10 @@ with no data buffer provided immediately after an
 .Fn accept
 system call.
 .Pp
-Open file descriptors are now passed as ancillary data for
+With
 .Dv AF_UNIX
-domain sockets, with
-.Fa cmsg_level
-set to
-.Dv SOL_SOCKET
-and
-.Fa cmsg_type
-set to
-.Dv SCM_RIGHTS .
-The close-on-exec flag on received descriptors is set according to the
-.Dv MSG_CMSG_CLOEXEC
-flag passed to
-.Fn recvmsg .
-.Pp
-Process credentials can also be passed as ancillary data for
-.Dv AF_UNIX
-domain sockets using a
-.Fa cmsg_type
-of
-.Dv SCM_CREDS .
-In this case,
-.Fa cmsg_data
-should be a structure of type
-.Fa cmsgcred ,
-which is defined in
-.In sys/socket.h
-as follows:
-.Bd -literal
-struct cmsgcred {
-	pid_t	cmcred_pid;		/* PID of sending process */
-	uid_t	cmcred_uid;		/* real UID of sending process */
-	uid_t	cmcred_euid;		/* effective UID of sending process */
-	gid_t	cmcred_gid;		/* real GID of sending process */
-	short	cmcred_ngroups;		/* number or groups */
-	gid_t	cmcred_groups[CMGROUP_MAX];	/* groups */
-};
-.Ed
-.Pp
-If a sender supplies ancillary data with enough space for the above struct
-tagged as
-.Dv SCM_CREDS
-control message type to the
-.Fn sendmsg
-system call, then kernel will fill in the credential information of the
-sending process and deliver it to the receiver.
-Since receiver usually has no control over a sender, this method of retrieving
-credential information isn't reliable.
-For reliable retrieval of remote side credentials it is advised to use the
-.Dv LOCAL_CREDS
-socket option on the receiving socket.
+domain sockets, ancillary data can be used to pass file descriptors and
+process credentials.
 See
 .Xr unix 4
 for details.
diff --git a/share/man/man4/unix.4 b/share/man/man4/unix.4
index 93cd399..86b291e 100644
--- a/share/man/man4/unix.4
+++ b/share/man/man4/unix.4
@@ -28,7 +28,7 @@
 .\"     @(#)unix.4	8.1 (Berkeley) 6/9/93
 .\" $FreeBSD$
 .\"
-.Dd March 19, 2013
+.Dd February 3, 2017
 .Dt UNIX 4
 .Os
 .Sh NAME
@@ -119,12 +119,12 @@ of a
 or
 .Xr sendto 2
 must be writable.
-.Sh PASSING FILE DESCRIPTORS
+.Sh CONTROL MESSAGES
 The
 .Ux Ns -domain
 sockets support the communication of
 .Ux
-file descriptors through the use of the
+file descriptors and process credentials through the use of the
 .Va msg_control
 field in the
 .Fa msg
@@ -132,13 +132,12 @@ argument to
 .Xr sendmsg 2
 and
 .Xr recvmsg 2 .
-.Pp
-Any valid descriptor may be sent in a message.
-The file descriptor(s) to be passed are described using a
+The items to be passed are described using a
 .Vt "struct cmsghdr"
 that is defined in the include file
 .In sys/socket.h .
-The type of the message is
+.Pp
+To send file descriptors, the type of the message is
 .Dv SCM_RIGHTS ,
 and the data portion of the messages is an array of integers
 representing the file descriptors to be passed.
@@ -161,6 +160,39 @@ call.
 Descriptors that are awaiting delivery, or that are
 purposely not received, are automatically closed by the system
 when the destination socket is closed.
+.Pp
+Credentials of the sending process can be transmitted explicitly using a
+control message of type
+.Dv SCM_CREDS
+with a data portion of type
+.Vt "struct cmsgcred" ,
+defined in
+.In sys/socket.h
+as follows:
+.Bd -literal
+struct cmsgcred {
+  pid_t	cmcred_pid;		/* PID of sending process */
+  uid_t	cmcred_uid;		/* real UID of sending process */
+  uid_t	cmcred_euid;		/* effective UID of sending process */
+  gid_t	cmcred_gid;		/* real GID of sending process */
+  short	cmcred_ngroups;		/* number of groups */
+  gid_t	cmcred_groups[CMGROUP_MAX];	/* groups */
+};
+.Ed
+.Pp
+The sender should pass a zeroed buffer which will be filled in by the system.
+.Pp
+The group list is truncated to at most
+.Dv CMGROUP_MAX
+GIDs.
+.Pp
+The process ID
+.Fa cmcred_pid
+should not be looked up (such as via the
+.Dv KERN_PROC_PID
+sysctl) for making security decisions.
+The sending process could have exited and its process ID already been
+reused for a new process.
 .Sh SOCKET OPTIONS
 .Tn UNIX
 domain sockets support a number of socket options which can be set with
@@ -176,7 +208,13 @@ or a
 .Dv SOCK_STREAM
 socket.
 This option provides a mechanism for the receiver to
-receive the credentials of the process as a
+receive the credentials of the process calling
+.Xr write 2 ,
+.Xr send 2 ,
+.Xr sendto 2
+or
+.Xr sendmsg 2
+as a
 .Xr recvmsg 2
 control message.
 The
@@ -201,6 +239,10 @@ struct sockcred {
 };
 .Ed
 .Pp
+The current implementation truncates the group list to at most
+.Dv CMGROUP_MAX
+groups.
+.Pp
 The
 .Fn SOCKCREDSIZE
 macro computes the size of the
@@ -221,7 +263,28 @@ On
 and
 .Dv SOCK_SEQPACKET
 sockets credentials are passed only on the first read from a socket,
-then system clears the option on socket.
+then the system clears the option on the socket.
+.Pp
+This option and the above explicit
+.Vt "struct cmsgcred"
+both use the same value
+.Dv SCM_CREDS
+but incompatible control messages.
+If this option is enabled and the sender attached a
+.Dv SCM_CREDS
+control message with a
+.Vt "struct cmsgcred" ,
+it will be discarded and a
+.Vt "struct sockcred"
+will be included.
+.Pp
+Many setuid programs will
+.Xr write 2
+data at least partially controlled by the invoker,
+such as error messages.
+Therefore, a message accompanied by a particular
+.Fa sc_euid
+value should not be trusted as being from that user.
 .It Dv LOCAL_CONNWAIT
 Used with
 .Dv SOCK_STREAM