tools/regression/sockets/unix_cmsg/README

   1 $FreeBSD$
   2
   3 About unix_cmsg
   4 ===============
   5
   6 This program is a collection of regression tests for ancillary data
   7 (control information) for PF_LOCAL sockets (local domain or Unix domain
   8 sockets).  There are tests for stream and datagram sockets.
   9
  10 Usually each test does following steps: creates Server, forks Client,
  11 Client sends something to Server, Server verifies whether everything is
  12 correct in received message(s).
  13
  14 It is better to change the owner of unix_cmsg to some safe user
  15 (eg. nobody:nogroup) and set SUID and SGID bits, else some tests that
  16 check credentials can give correct results for wrong implementation.
  17
  18 It is better to run this program by a user that belongs to more
  19 than 16 groups.
  20
  21 Available options
  22 =================
  23
  24 usage: unix_cmsg [-dh] [-n num] [-s size] [-t type] [-z value] [testno]
  25
  26  Options are:
  27   -d            Output debugging information
  28   -h            Output the help message and exit
  29   -n num        Number of messages to send
  30   -s size       Specify size of data for IPC
  31   -t type       Specify socket type (stream, dgram) for tests
  32   -z value      Do not send data in a message (bit 0x1), do not send
  33                 data array associated with a cmsghdr structure (bit 0x2)
  34   testno        Run one test by its number (require the -t option)
  35
  36 Description
  37 ===========
  38
  39 If Client sends something to Server, then it sends 5 messages by default.
  40 Number of messages can be changed in the -n command line option.  Number
  41 of messages will be given as N in the following descriptions.
  42
  43 If Client sends something to Server, then it sends some data (few bytes)
  44 in each message by default.  The size of this data can be changed by the -s
  45 command line option.  The "-s 0" command line option means, that Client will
  46 send zero bytes represented by { NULL, 0 } value of struct iovec{}, referenced
  47 by the msg_iov field from struct msghdr{}.  The "-z 1" or "-z 3" command line
  48 option means, that Client will send zero bytes represented by the NULL value
  49 in the msg_iov field from struct msghdr{}.
  50
  51 If Client sends some ancillary data object, then this ancillary data object
  52 always has associated data array by default.  The "-z 2" or "-z 3" option
  53 means, that Client will not send associated data array if possible.
  54
  55 For SOCK_STREAM sockets:
  56 -----------------------
  57
  58  1: Sending, receiving cmsgcred
  59
  60     Client connects to Server and sends N messages with SCM_CREDS ancillary
  61     data object.  Server should receive N messages, each message should
  62     have SCM_CREDS ancillary data object followed by struct cmsgcred{}.
  63
  64  2: Receiving sockcred (listening socket)
  65
  66     Server creates a listening stream socket and sets the LOCAL_CREDS
  67     socket option for it.  Client connects to Server two times, each time
  68     it sends N messages.  Server accepts two connections and receives N
  69     messages from each connection.  The first message from each connection
  70     should have SCM_CREDS ancillary data object followed by struct sockcred{},
  71     next messages from the same connection should not have ancillary data.
  72
  73  3: Receiving sockcred (accepted socket)
  74
  75     Client connects to Server.  Server accepts connection and sets the
  76     LOCAL_CREDS socket option for just accepted socket.  Client sends N
  77     messages to Server.  Server should receive N messages, the first
  78     message should have SCM_CREDS ancillary data object followed by
  79     struct sockcred{}, next messages should not have ancillary data.
  80
  81  4: Sending cmsgcred, receiving sockcred
  82
  83     Server creates a listening stream socket and sets the LOCAL_CREDS
  84     socket  option for it.  Client connects to Server and sends N messages
  85     with SCM_CREDS ancillary data object.  Server should receive N messages,
  86     the first message should have SCM_CREDS ancillary data object followed
  87     by struct sockcred{}, each of next messages should have SCM_CREDS
  88     ancillary data object followed by struct cmsgcred{}.
  89
  90  5: Sending, receiving timeval
  91
  92     Client connects to Server and sends message with SCM_TIMESTAMP ancillary
  93     data object.  Server should receive one message with SCM_TIMESTAMP
  94     ancillary data object followed by struct timeval{}.
  95
  96  6: Sending, receiving bintime
  97
  98     Client connects to Server and sends message with SCM_BINTIME ancillary
  99     data object.  Server should receive one message with SCM_BINTIME
 100     ancillary data object followed by struct bintime{}.
 101
 102  7: Checking cmsghdr.cmsg_len
 103
 104     Client connects to Server and tries to send several messages with
 105     SCM_CREDS ancillary data object that has wrong cmsg_len field in its
 106     struct cmsghdr{}.  All these attempts should fail, since cmsg_len
 107     in all requests is less than CMSG_LEN(0).
 108
 109  8: Check LOCAL_PEERCRED socket option
 110
 111     This test does not use ancillary data, but can be implemented here.
 112     Client connects to Server.  Both Client and Server verify that
 113     credentials of the peer are correct using LOCAL_PEERCRED socket option.
 114
 115 For SOCK_DGRAM sockets:
 116 ----------------------
 117
 118  1: Sending, receiving cmsgcred
 119
 120     Client connects to Server and sends N messages with SCM_CREDS ancillary
 121     data object.  Server should receive N messages, each message should
 122     have SCM_CREDS ancillary data object followed by struct cmsgcred{}.
 123
 124  2: Receiving sockcred
 125
 126     Server creates datagram socket and sets the LOCAL_CREDS socket option
 127     for it.  Client sends N messages to Server.  Server should receive N
 128     messages, each message should have SCM_CREDS ancillary data object
 129     followed by struct sockcred{}.
 130
 131  3: Sending cmsgcred, receiving sockcred
 132
 133     Server creates datagram socket and sets the LOCAL_CREDS socket option
 134     for it.  Client sends N messages with SCM_CREDS ancillary data object
 135     to Server.  Server should receive N messages, the first message should
 136     have SCM_CREDS ancillary data object followed by struct sockcred{},
 137     each of next messages should have SCM_CREDS ancillary data object
 138     followed by struct cmsgcred{}.
 139
 140  4: Sending, receiving timeval
 141
 142     Client sends one message with SCM_TIMESTAMP ancillary data object
 143     to Server.  Server should receive one message with SCM_TIMESTAMP
 144     ancillary data object followed by struct timeval{}.
 145
 146  5: Sending, receiving bintime
 147
 148     Client sends one message with SCM_BINTIME ancillary data object
 149     to Server.  Server should receive one message with SCM_BINTIME
 150     ancillary data object followed by struct bintime{}.
 151
 152  6: Checking cmsghdr.cmsg_len
 153
 154     Client tries to send Server several messages with SCM_CREDS ancillary
 155     data object that has wrong cmsg_len field in its struct cmsghdr{}.
 156     All these attempts should fail, since cmsg_len in all requests is less
 157     than CMSG_LEN(0).
 158
 159 - Andrey Simonenko
 160 andreysimonenko@users.sourceforge.net