diff options
author | jilles <jilles@FreeBSD.org> | 2017-02-12 18:52:01 +0000 |
---|---|---|
committer | jilles <jilles@FreeBSD.org> | 2017-02-12 18:52:01 +0000 |
commit | 7f744e86ff06be037edeee6f6535e91834c87711 (patch) | |
tree | 71217e81c785b04467e61fdd50e7dcfab2183e08 | |
parent | 16f159656f0b3e31a58c10c817fb70d11aaef12a (diff) | |
download | FreeBSD-src-7f744e86ff06be037edeee6f6535e91834c87711.zip FreeBSD-src-7f744e86ff06be037edeee6f6535e91834c87711.tar.gz |
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).
-rw-r--r-- | lib/libc/sys/recv.2 | 55 | ||||
-rw-r--r-- | share/man/man4/unix.4 | 81 |
2 files changed, 76 insertions, 60 deletions
diff --git a/lib/libc/sys/recv.2 b/lib/libc/sys/recv.2 index e0a1f04..7ad7aa7 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 March 19, 2013 +.Dd February 3, 2017 .Dt RECV 2 .Os .Sh NAME @@ -218,57 +218,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 c53cc42..0e8470f 100644 --- a/share/man/man4/unix.4 +++ b/share/man/man4/unix.4 @@ -32,7 +32,7 @@ .\" @(#)unix.4 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" -.Dd March 19, 2013 +.Dd February 3, 2017 .Dt UNIX 4 .Os .Sh NAME @@ -123,12 +123,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 @@ -136,13 +136,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. @@ -165,6 +164,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 @@ -180,7 +212,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 @@ -205,6 +243,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 @@ -225,7 +267,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 |