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). Reviewed by: wblock MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D9298
This commit is contained in:
parent
4af17bf5c0
commit
e301fd984a
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=313174
|
@ -28,7 +28,7 @@
|
|||
.\" @(#)recv.2 8.3 (Berkeley) 2/21/94
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd August 18, 2016
|
||||
.Dd February 3, 2017
|
||||
.Dt RECV 2
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
@ -266,57 +266,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.
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue
Block a user