From owner-svn-src-stable@freebsd.org Sun Feb 12 18:52:03 2017 Return-Path: Delivered-To: svn-src-stable@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 12790CDCC73; Sun, 12 Feb 2017 18:52:03 +0000 (UTC) (envelope-from jilles@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id D6B4F17E9; Sun, 12 Feb 2017 18:52:02 +0000 (UTC) (envelope-from jilles@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v1CIq1Bx002858; Sun, 12 Feb 2017 18:52:01 GMT (envelope-from jilles@FreeBSD.org) Received: (from jilles@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v1CIq1Ur002671; Sun, 12 Feb 2017 18:52:01 GMT (envelope-from jilles@FreeBSD.org) Message-Id: <201702121852.v1CIq1Ur002671@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: jilles set sender to jilles@FreeBSD.org using -f From: Jilles Tjoelker Date: Sun, 12 Feb 2017 18:52:01 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r313685 - in stable/10: lib/libc/sys share/man/man4 X-SVN-Group: stable-10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-stable@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for all the -stable branches of the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 12 Feb 2017 18:52:03 -0000 Author: jilles Date: Sun Feb 12 18:52:01 2017 New Revision: 313685 URL: https://svnweb.freebsd.org/changeset/base/313685 Log: 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). Modified: stable/10/lib/libc/sys/recv.2 stable/10/share/man/man4/unix.4 Directory Properties: stable/10/ (props changed) Modified: stable/10/lib/libc/sys/recv.2 ============================================================================== --- stable/10/lib/libc/sys/recv.2 Sun Feb 12 15:22:50 2017 (r313684) +++ stable/10/lib/libc/sys/recv.2 Sun Feb 12 18:52:01 2017 (r313685) @@ -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 .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. Modified: stable/10/share/man/man4/unix.4 ============================================================================== --- stable/10/share/man/man4/unix.4 Sun Feb 12 15:22:50 2017 (r313684) +++ stable/10/share/man/man4/unix.4 Sun Feb 12 18:52:01 2017 (r313685) @@ -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