README
1$FreeBSD$
2
3About unix_cmsg
4===============
5
6This program is a collection of regression tests for ancillary data
7(control information) for PF_LOCAL sockets (local domain or Unix domain
8sockets). There are tests for stream and datagram sockets.
9
10Usually each test does following steps: creates Server, forks Client,
11Client sends something to Server, Server verifies whether everything is
12correct in received message(s).
13
14It 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
16check credentials can give correct results for wrong implementation.
17
18It is better to run this program by a user that belongs to more
19than 16 groups.
20
21Available options
22=================
23
24usage: 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
36Description
37===========
38
39If Client sends something to Server, then it sends 5 messages by default.
40Number of messages can be changed in the -n command line option. Number
41of messages will be given as N in the following descriptions.
42
43If Client sends something to Server, then it sends some data (few bytes)
44in each message by default. The size of this data can be changed by the -s
45command line option. The "-s 0" command line option means, that Client will
46send zero bytes represented by { NULL, 0 } value of struct iovec{}, referenced
47by the msg_iov field from struct msghdr{}. The "-z 1" or "-z 3" command line
48option means, that Client will send zero bytes represented by the NULL value
49in the msg_iov field from struct msghdr{}.
50
51If Client sends some ancillary data object, then this ancillary data object
52always has associated data array by default. The "-z 2" or "-z 3" option
53means, that Client will not send associated data array if possible.
54
55For 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
115For 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
160andreysimonenko@users.sourceforge.net
161