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