README
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