share/man/man4/unix.4

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)unix.4      8.1 (Berkeley) 6/9/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd August 19, 2018
  32 .Dt UNIX 4
  33 .Os
  34 .Sh NAME
  35 .Nm unix
  36 .Nd UNIX-domain protocol family
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/un.h
  40 .Sh DESCRIPTION
  41 The
  42 .Ux Ns -domain
  43 protocol family is a collection of protocols
  44 that provides local (on-machine) interprocess
  45 communication through the normal
  46 .Xr socket 2
  47 mechanisms.
  48 The
  49 .Ux Ns -domain
  50 family supports the
  51 .Dv SOCK_STREAM ,
  52 .Dv SOCK_SEQPACKET ,
  53 and
  54 .Dv SOCK_DGRAM
  55 socket types and uses
  56 file system pathnames for addressing.
  57 .Sh ADDRESSING
  58 .Ux Ns -domain
  59 addresses are variable-length file system pathnames of
  60 at most 104 characters.
  61 The include file
  62 .In sys/un.h
  63 defines this address:
  64 .Bd -literal -offset indent
  65 struct sockaddr_un {
  66         u_char  sun_len;
  67         u_char  sun_family;
  68         char    sun_path[104];
  69 };
  70 .Ed
  71 .Pp
  72 Binding a name to a
  73 .Ux Ns -domain
  74 socket with
  75 .Xr bind 2
  76 causes a socket file to be created in the file system.
  77 This file is
  78 .Em not
  79 removed when the socket is closed \(em
  80 .Xr unlink 2
  81 must be used to remove the file.
  82 .Pp
  83 The length of
  84 .Ux Ns -domain
  85 address, required by
  86 .Xr bind 2
  87 and
  88 .Xr connect 2 ,
  89 can be calculated by the macro
  90 .Fn SUN_LEN
  91 defined in
  92 .In sys/un.h .
  93 The
  94 .Va sun_path
  95 field must be terminated by a
  96 .Dv NUL
  97 character to be used with
  98 .Fn SUN_LEN ,
  99 but the terminating
 100 .Dv NUL
 101 is
 102 .Em not
 103 part of the address.
 104 .Pp
 105 The
 106 .Ux Ns -domain
 107 protocol family does not support broadcast addressing or any form
 108 of
 109 .Dq wildcard
 110 matching on incoming messages.
 111 All addresses are absolute- or relative-pathnames
 112 of other
 113 .Ux Ns -domain
 114 sockets.
 115 Normal file system access-control mechanisms are also
 116 applied when referencing pathnames; e.g., the destination
 117 of a
 118 .Xr connect 2
 119 or
 120 .Xr sendto 2
 121 must be writable.
 122 .Sh CONTROL MESSAGES
 123 The
 124 .Ux Ns -domain
 125 sockets support the communication of
 126 .Ux
 127 file descriptors and process credentials through the use of the
 128 .Va msg_control
 129 field in the
 130 .Fa msg
 131 argument to
 132 .Xr sendmsg 2
 133 and
 134 .Xr recvmsg 2 .
 135 The items to be passed are described using a
 136 .Vt "struct cmsghdr"
 137 that is defined in the include file
 138 .In sys/socket.h .
 139 .Pp
 140 To send file descriptors, the type of the message is
 141 .Dv SCM_RIGHTS ,
 142 and the data portion of the messages is an array of integers
 143 representing the file descriptors to be passed.
 144 The number of descriptors being passed is defined
 145 by the length field of the message;
 146 the length field is the sum of the size of the header
 147 plus the size of the array of file descriptors.
 148 .Pp
 149 The received descriptor is a
 150 .Em duplicate
 151 of the sender's descriptor, as if it were created via
 152 .Li dup(fd)
 153 or
 154 .Li fcntl(fd, F_DUPFD_CLOEXEC, 0)
 155 depending on whether
 156 .Dv MSG_CMSG_CLOEXEC
 157 is passed in the
 158 .Xr recvmsg 2
 159 call.
 160 Descriptors that are awaiting delivery, or that are
 161 purposely not received, are automatically closed by the system
 162 when the destination socket is closed.
 163 .Pp
 164 Credentials of the sending process can be transmitted explicitly using a
 165 control message of type
 166 .Dv SCM_CREDS
 167 with a data portion of type
 168 .Vt "struct cmsgcred" ,
 169 defined in
 170 .In sys/socket.h
 171 as follows:
 172 .Bd -literal
 173 struct cmsgcred {
 174   pid_t cmcred_pid;             /* PID of sending process */
 175   uid_t cmcred_uid;             /* real UID of sending process */
 176   uid_t cmcred_euid;            /* effective UID of sending process */
 177   gid_t cmcred_gid;             /* real GID of sending process */
 178   short cmcred_ngroups;         /* number of groups */
 179   gid_t cmcred_groups[CMGROUP_MAX];     /* groups */
 180 };
 181 .Ed
 182 .Pp
 183 The sender should pass a zeroed buffer which will be filled in by the system.
 184 .Pp
 185 The group list is truncated to at most
 186 .Dv CMGROUP_MAX
 187 GIDs.
 188 .Pp
 189 The process ID
 190 .Fa cmcred_pid
 191 should not be looked up (such as via the
 192 .Dv KERN_PROC_PID
 193 sysctl) for making security decisions.
 194 The sending process could have exited and its process ID already been
 195 reused for a new process.
 196 .Sh SOCKET OPTIONS
 197 .Tn UNIX
 198 domain sockets support a number of socket options which can be set with
 199 .Xr setsockopt 2
 200 and tested with
 201 .Xr getsockopt 2 :
 202 .Bl -tag -width ".Dv LOCAL_CONNWAIT"
 203 .It Dv LOCAL_CREDS
 204 This option may be enabled on
 205 .Dv SOCK_DGRAM ,
 206 .Dv SOCK_SEQPACKET ,
 207 or a
 208 .Dv SOCK_STREAM
 209 socket.
 210 This option provides a mechanism for the receiver to
 211 receive the credentials of the process calling
 212 .Xr write 2 ,
 213 .Xr send 2 ,
 214 .Xr sendto 2
 215 or
 216 .Xr sendmsg 2
 217 as a
 218 .Xr recvmsg 2
 219 control message.
 220 The
 221 .Va msg_control
 222 field in the
 223 .Vt msghdr
 224 structure points to a buffer that contains a
 225 .Vt cmsghdr
 226 structure followed by a variable length
 227 .Vt sockcred
 228 structure, defined in
 229 .In sys/socket.h
 230 as follows:
 231 .Bd -literal
 232 struct sockcred {
 233   uid_t sc_uid;         /* real user id */
 234   uid_t sc_euid;        /* effective user id */
 235   gid_t sc_gid;         /* real group id */
 236   gid_t sc_egid;        /* effective group id */
 237   int   sc_ngroups;     /* number of supplemental groups */
 238   gid_t sc_groups[1];   /* variable length */
 239 };
 240 .Ed
 241 .Pp
 242 The current implementation truncates the group list to at most
 243 .Dv CMGROUP_MAX
 244 groups.
 245 .Pp
 246 The
 247 .Fn SOCKCREDSIZE
 248 macro computes the size of the
 249 .Vt sockcred
 250 structure for a specified number
 251 of groups.
 252 The
 253 .Vt cmsghdr
 254 fields have the following values:
 255 .Bd -literal
 256 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 257 cmsg_level = SOL_SOCKET
 258 cmsg_type = SCM_CREDS
 259 .Ed
 260 .Pp
 261 On
 262 .Dv SOCK_STREAM
 263 and
 264 .Dv SOCK_SEQPACKET
 265 sockets credentials are passed only on the first read from a socket,
 266 then the system clears the option on the socket.
 267 .Pp
 268 This option and the above explicit
 269 .Vt "struct cmsgcred"
 270 both use the same value
 271 .Dv SCM_CREDS
 272 but incompatible control messages.
 273 If this option is enabled and the sender attached a
 274 .Dv SCM_CREDS
 275 control message with a
 276 .Vt "struct cmsgcred" ,
 277 it will be discarded and a
 278 .Vt "struct sockcred"
 279 will be included.
 280 .Pp
 281 Many setuid programs will
 282 .Xr write 2
 283 data at least partially controlled by the invoker,
 284 such as error messages.
 285 Therefore, a message accompanied by a particular
 286 .Fa sc_euid
 287 value should not be trusted as being from that user.
 288 .It Dv LOCAL_CONNWAIT
 289 Used with
 290 .Dv SOCK_STREAM
 291 sockets, this option causes the
 292 .Xr connect 2
 293 function to block until
 294 .Xr accept 2
 295 has been called on the listening socket.
 296 .It Dv LOCAL_PEERCRED
 297 Requested via
 298 .Xr getsockopt 2
 299 on a
 300 .Dv SOCK_STREAM
 301 socket returns credentials of the remote side.
 302 These will arrive in the form of a filled in
 303 .Vt xucred
 304 structure, defined in
 305 .In sys/ucred.h
 306 as follows:
 307 .Bd -literal
 308 struct xucred {
 309   u_int cr_version;             /* structure layout version */
 310   uid_t cr_uid;                 /* effective user id */
 311   short cr_ngroups;             /* number of groups */
 312   gid_t cr_groups[XU_NGROUPS];  /* groups */
 313   pid_t cr_pid;                 /* process id of the sending process */
 314 };
 315 .Ed
 316 The
 317 .Vt cr_version
 318 fields should be checked against
 319 .Dv XUCRED_VERSION
 320 define.
 321 .Pp
 322 The credentials presented to the server (the
 323 .Xr listen 2
 324 caller) are those of the client when it called
 325 .Xr connect 2 ;
 326 the credentials presented to the client (the
 327 .Xr connect 2
 328 caller) are those of the server when it called
 329 .Xr listen 2 .
 330 This mechanism is reliable; there is no way for either party to influence
 331 the credentials presented to its peer except by calling the appropriate
 332 system call (e.g.,
 333 .Xr connect 2
 334 or
 335 .Xr listen 2 )
 336 under different effective credentials.
 337 .Pp
 338 To reliably obtain peer credentials on a
 339 .Dv SOCK_DGRAM
 340 socket refer to the
 341 .Dv LOCAL_CREDS
 342 socket option.
 343 .El
 344 .Sh SEE ALSO
 345 .Xr connect 2 ,
 346 .Xr dup 2 ,
 347 .Xr fcntl 2 ,
 348 .Xr getsockopt 2 ,
 349 .Xr listen 2 ,
 350 .Xr recvmsg 2 ,
 351 .Xr sendto 2 ,
 352 .Xr setsockopt 2 ,
 353 .Xr socket 2 ,
 354 .Xr CMSG_DATA 3 ,
 355 .Xr intro 4
 356 .Rs
 357 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 358 .%B PS1
 359 .%N 7
 360 .Re
 361 .Rs
 362 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 363 .%B PS1
 364 .%N 8
 365 .Re