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 November 9, 2020
  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 for the options level
 199 .Dv SOL_LOCAL ,
 200 which can be set with
 201 .Xr setsockopt 2
 202 and tested with
 203 .Xr getsockopt 2 :
 204 .Bl -tag -width ".Dv LOCAL_CREDS_PERSISTENT"
 205 .It Dv LOCAL_CREDS
 206 This option may be enabled on
 207 .Dv SOCK_DGRAM ,
 208 .Dv SOCK_SEQPACKET ,
 209 or a
 210 .Dv SOCK_STREAM
 211 socket.
 212 This option provides a mechanism for the receiver to
 213 receive the credentials of the process calling
 214 .Xr write 2 ,
 215 .Xr send 2 ,
 216 .Xr sendto 2
 217 or
 218 .Xr sendmsg 2
 219 as a
 220 .Xr recvmsg 2
 221 control message.
 222 The
 223 .Va msg_control
 224 field in the
 225 .Vt msghdr
 226 structure points to a buffer that contains a
 227 .Vt cmsghdr
 228 structure followed by a variable length
 229 .Vt sockcred
 230 structure, defined in
 231 .In sys/socket.h
 232 as follows:
 233 .Bd -literal
 234 struct sockcred {
 235   uid_t sc_uid;         /* real user id */
 236   uid_t sc_euid;        /* effective user id */
 237   gid_t sc_gid;         /* real group id */
 238   gid_t sc_egid;        /* effective group id */
 239   int   sc_ngroups;     /* number of supplemental groups */
 240   gid_t sc_groups[1];   /* variable length */
 241 };
 242 .Ed
 243 .Pp
 244 The current implementation truncates the group list to at most
 245 .Dv CMGROUP_MAX
 246 groups.
 247 .Pp
 248 The
 249 .Fn SOCKCREDSIZE
 250 macro computes the size of the
 251 .Vt sockcred
 252 structure for a specified number
 253 of groups.
 254 The
 255 .Vt cmsghdr
 256 fields have the following values:
 257 .Bd -literal
 258 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 259 cmsg_level = SOL_SOCKET
 260 cmsg_type = SCM_CREDS
 261 .Ed
 262 .Pp
 263 On
 264 .Dv SOCK_STREAM
 265 and
 266 .Dv SOCK_SEQPACKET
 267 sockets credentials are passed only on the first read from a socket,
 268 then the system clears the option on the socket.
 269 .Pp
 270 This option and the above explicit
 271 .Vt "struct cmsgcred"
 272 both use the same value
 273 .Dv SCM_CREDS
 274 but incompatible control messages.
 275 If this option is enabled and the sender attached a
 276 .Dv SCM_CREDS
 277 control message with a
 278 .Vt "struct cmsgcred" ,
 279 it will be discarded and a
 280 .Vt "struct sockcred"
 281 will be included.
 282 .Pp
 283 Many setuid programs will
 284 .Xr write 2
 285 data at least partially controlled by the invoker,
 286 such as error messages.
 287 Therefore, a message accompanied by a particular
 288 .Fa sc_euid
 289 value should not be trusted as being from that user.
 290 .It Dv LOCAL_CREDS_PERSISTENT
 291 This option is similar to
 292 .Dv LOCAL_CREDS ,
 293 except that socket credentials are passed on every read from a
 294 .Dv SOCK_STREAM
 295 or
 296 .Dv SOCK_SEQPACKET
 297 socket, instead of just the first read.
 298 Additionally, the
 299 .Va msg_control
 300 field in the
 301 .Vt msghdr
 302 structure points to a buffer that contains a
 303 .Vt cmsghdr
 304 structure followed by a variable length
 305 .Vt sockcred2
 306 structure, defined in
 307 .In sys/socket.h
 308 as follows:
 309 .Bd -literal
 310 struct sockcred2 {
 311   int   sc_version;     /* version of this structure */
 312   pid_t sc_pid;         /* PID of sending process */
 313   uid_t sc_uid;         /* real user id */
 314   uid_t sc_euid;        /* effective user id */
 315   gid_t sc_gid;         /* real group id */
 316   gid_t sc_egid;        /* effective group id */
 317   int   sc_ngroups;     /* number of supplemental groups */
 318   gid_t sc_groups[1];   /* variable length */
 319 };
 320 .Ed
 321 .Pp
 322 The current version is zero.
 323 .Pp
 324 The
 325 .Vt cmsghdr
 326 fields have the following values:
 327 .Bd -literal
 328 cmsg_len = CMSG_LEN(SOCKCRED2SIZE(ngroups))
 329 cmsg_level = SOL_SOCKET
 330 cmsg_type = SCM_CREDS2
 331 .Ed
 332 .Pp
 333 The
 334 .Dv LOCAL_CREDS
 335 and
 336 .Dv LOCAL_CREDS_PERSISTENT
 337 options are mutually exclusive.
 338 .It Dv LOCAL_CONNWAIT
 339 Used with
 340 .Dv SOCK_STREAM
 341 sockets, this option causes the
 342 .Xr connect 2
 343 function to block until
 344 .Xr accept 2
 345 has been called on the listening socket.
 346 .It Dv LOCAL_PEERCRED
 347 Requested via
 348 .Xr getsockopt 2
 349 on a
 350 .Dv SOCK_STREAM
 351 socket returns credentials of the remote side.
 352 These will arrive in the form of a filled in
 353 .Vt xucred
 354 structure, defined in
 355 .In sys/ucred.h
 356 as follows:
 357 .Bd -literal
 358 struct xucred {
 359   u_int cr_version;             /* structure layout version */
 360   uid_t cr_uid;                 /* effective user id */
 361   short cr_ngroups;             /* number of groups */
 362   gid_t cr_groups[XU_NGROUPS];  /* groups */
 363   pid_t cr_pid;                 /* process id of the sending process */
 364 };
 365 .Ed
 366 The
 367 .Vt cr_version
 368 fields should be checked against
 369 .Dv XUCRED_VERSION
 370 define.
 371 .Pp
 372 The credentials presented to the server (the
 373 .Xr listen 2
 374 caller) are those of the client when it called
 375 .Xr connect 2 ;
 376 the credentials presented to the client (the
 377 .Xr connect 2
 378 caller) are those of the server when it called
 379 .Xr listen 2 .
 380 This mechanism is reliable; there is no way for either party to influence
 381 the credentials presented to its peer except by calling the appropriate
 382 system call (e.g.,
 383 .Xr connect 2
 384 or
 385 .Xr listen 2 )
 386 under different effective credentials.
 387 .Pp
 388 To reliably obtain peer credentials on a
 389 .Dv SOCK_DGRAM
 390 socket refer to the
 391 .Dv LOCAL_CREDS
 392 socket option.
 393 .El
 394 .Sh SEE ALSO
 395 .Xr connect 2 ,
 396 .Xr dup 2 ,
 397 .Xr fcntl 2 ,
 398 .Xr getsockopt 2 ,
 399 .Xr listen 2 ,
 400 .Xr recvmsg 2 ,
 401 .Xr sendto 2 ,
 402 .Xr setsockopt 2 ,
 403 .Xr socket 2 ,
 404 .Xr CMSG_DATA 3 ,
 405 .Xr intro 4
 406 .Rs
 407 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 408 .%B PS1
 409 .%N 7
 410 .Re
 411 .Rs
 412 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 413 .%B PS1
 414 .%N 8
 415 .Re