From owner-svn-src-stable@FreeBSD.ORG Mon Jun 24 08:55:21 2013 Return-Path: Delivered-To: svn-src-stable@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 73C50F1C; Mon, 24 Jun 2013 08:55:21 +0000 (UTC) (envelope-from glebius@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 5653E1731; Mon, 24 Jun 2013 08:55:21 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5O8tLI4002569; Mon, 24 Jun 2013 08:55:21 GMT (envelope-from glebius@svn.freebsd.org) Received: (from glebius@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5O8tLBN002568; Mon, 24 Jun 2013 08:55:21 GMT (envelope-from glebius@svn.freebsd.org) Message-Id: <201306240855.r5O8tLBN002568@svn.freebsd.org> From: Gleb Smirnoff Date: Mon, 24 Jun 2013 08:55:21 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-9@freebsd.org Subject: svn commit: r252144 - stable/9/share/man/man4 X-SVN-Group: stable-9 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.14 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: Mon, 24 Jun 2013 08:55:21 -0000 Author: glebius Date: Mon Jun 24 08:55:20 2013 New Revision: 252144 URL: http://svnweb.freebsd.org/changeset/base/252144 Log: Merge r243151: o Remove meaningless PROTOCOLS section. o Describe passing file descriptors as separate section. - Descriptors can be passed through any protocol of the UNIX family, not SOCK_STREAM and SOCK_SEQPACKET only. [1] o Describe socket options as separate section. - Move LOCAL_PEERCRED option to this section. - Describe struct xucred. - In LOCAL_CREDS section mention that credentials are passed only on the first read on non-datagram sockets. o Xref all mentioned system calls. Noticed by: Igor Sysoev [1] Modified: stable/9/share/man/man4/unix.4 Directory Properties: stable/9/share/man/man4/ (props changed) Modified: stable/9/share/man/man4/unix.4 ============================================================================== --- stable/9/share/man/man4/unix.4 Mon Jun 24 05:18:31 2013 (r252143) +++ stable/9/share/man/man4/unix.4 Mon Jun 24 08:55:20 2013 (r252144) @@ -32,7 +32,7 @@ .\" @(#)unix.4 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" -.Dd October 5, 2009 +.Dd November 16, 2012 .Dt UNIX 4 .Os .Sh NAME @@ -123,20 +123,10 @@ of a or .Xr sendto 2 must be writable. -.Sh PROTOCOLS +.Sh PASSING FILE DESCRIPTORS The .Ux Ns -domain -protocol family is comprised of simple -transport protocols that support the -.Dv SOCK_STREAM , -.Dv SOCK_SEQPACKET , -and -.Dv SOCK_DGRAM -abstractions. -.Dv SOCK_STREAM -and -.Dv SOCK_SEQPACKET -sockets also support the communication of +sockets support the communication of .Ux file descriptors through the use of the .Va msg_control @@ -173,36 +163,7 @@ passed to a receiver. Descriptors that are awaiting delivery, or that are purposely not received, are automatically closed by the system when the destination socket is closed. -.Pp -The effective credentials (i.e., the user ID and group list) of a -peer on a -.Dv SOCK_STREAM -socket may be obtained using the -.Dv LOCAL_PEERCRED -socket option. -This may be used by a server to obtain and verify the credentials of -its client, and vice versa by the client to verify the credentials -of the server. -These will arrive in the form of a filled in -.Vt "struct xucred" -(defined in -.In sys/ucred.h ) . -The credentials presented to the server (the -.Xr listen 2 -caller) are those of the client when it called -.Xr connect 2 ; -the credentials presented to the client (the -.Xr connect 2 -caller) are those of the server when it called -.Xr listen 2 . -This mechanism is reliable; there is no way for either party to influence -the credentials presented to its peer except by calling the appropriate -system call (e.g., -.Xr connect 2 -or -.Xr listen 2 ) -under different effective credentials. -.Pp +.Sh SOCKET OPTIONS .Tn UNIX domain sockets support a number of socket options which can be set with .Xr setsockopt 2 @@ -256,6 +217,13 @@ cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups cmsg_level = SOL_SOCKET cmsg_type = SCM_CREDS .Ed +.Pp +On +.Dv SOCK_STREAM +and +.Dv SOCK_SEQPACKET +sockets credentials are passed only on the first read from a socket, +then system clears the option on socket. .It Dv LOCAL_CONNWAIT Used with .Dv SOCK_STREAM @@ -264,8 +232,62 @@ sockets, this option causes the function to block until .Xr accept 2 has been called on the listening socket. +.It Dv LOCAL_PEERCRED +Requested via +.Xr getsockopt 2 +on a +.Dv SOCK_STREAM +socket returns credentials of the remote side. +These will arrive in the form of a filled in +.Vt xucred +structure, defined in +.In sys/ucred.h +as follows: +.Bd -literal +struct xucred { + u_int cr_version; /* structure layout version */ + uid_t cr_uid; /* effective user id */ + short cr_ngroups; /* number of groups */ + gid_t cr_groups[XU_NGROUPS]; /* groups */ +}; +.Ed +The +.Vt cr_version +fields should be checked against +.Dv XUCRED_VERSION +define. +.Pp +The credentials presented to the server (the +.Xr listen 2 +caller) are those of the client when it called +.Xr connect 2 ; +the credentials presented to the client (the +.Xr connect 2 +caller) are those of the server when it called +.Xr listen 2 . +This mechanism is reliable; there is no way for either party to influence +the credentials presented to its peer except by calling the appropriate +system call (e.g., +.Xr connect 2 +or +.Xr listen 2 ) +under different effective credentials. +.Pp +To reliably obtain peer credentials on a +.Dv SOCK_DGRAM +socket refer to the +.Dv LOCAL_CREDS +socket option. .El .Sh SEE ALSO +.Xr connect 2 , +.Xr dup 2 , +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr listen 2 , +.Xr recvmsg 2 , +.Xr sendto 2 , +.Xr setsockopt 2 , .Xr socket 2 , .Xr intro 4 .Rs