1159045Smaxim$FreeBSD: releng/11.0/tools/regression/sockets/unix_cmsg/README 246670 2013-02-11 12:56:23Z pluknet $ 2159045Smaxim 3159045SmaximAbout unix_cmsg 4246670Spluknet=============== 5159045Smaxim 6246670SpluknetThis program is a collection of regression tests for ancillary data 7246670Spluknet(control information) for PF_LOCAL sockets (local domain or Unix domain 8246670Spluknetsockets). There are tests for stream and datagram sockets. 9159045Smaxim 10246670SpluknetUsually each test does following steps: creates Server, forks Client, 11246670SpluknetClient sends something to Server, Server verifies whether everything is 12246670Spluknetcorrect in received message(s). 13159045Smaxim 14159045SmaximIt is better to change the owner of unix_cmsg to some safe user 15246670Spluknet(eg. nobody:nogroup) and set SUID and SGID bits, else some tests that 16246670Spluknetcheck credentials can give correct results for wrong implementation. 17159045Smaxim 18246670SpluknetIt is better to run this program by a user that belongs to more 19246670Spluknetthan 16 groups. 20246670Spluknet 21159045SmaximAvailable options 22159045Smaxim================= 23159045Smaxim 24246670Spluknetusage: unix_cmsg [-dh] [-n num] [-s size] [-t type] [-z value] [testno] 25159045Smaxim 26246670Spluknet Options are: 27246670Spluknet -d Output debugging information 28246670Spluknet -h Output the help message and exit 29246670Spluknet -n num Number of messages to send 30246670Spluknet -s size Specify size of data for IPC 31246670Spluknet -t type Specify socket type (stream, dgram) for tests 32246670Spluknet -z value Do not send data in a message (bit 0x1), do not send 33246670Spluknet data array associated with a cmsghdr structure (bit 0x2) 34246670Spluknet testno Run one test by its number (require the -t option) 35159045Smaxim 36246670SpluknetDescription 37246670Spluknet=========== 38159045Smaxim 39246670SpluknetIf Client sends something to Server, then it sends 5 messages by default. 40246670SpluknetNumber of messages can be changed in the -n command line option. Number 41246670Spluknetof messages will be given as N in the following descriptions. 42159045Smaxim 43246670SpluknetIf Client sends something to Server, then it sends some data (few bytes) 44246670Spluknetin each message by default. The size of this data can be changed by the -s 45246670Spluknetcommand line option. The "-s 0" command line option means, that Client will 46246670Spluknetsend zero bytes represented by { NULL, 0 } value of struct iovec{}, referenced 47246670Spluknetby the msg_iov field from struct msghdr{}. The "-z 1" or "-z 3" command line 48246670Spluknetoption means, that Client will send zero bytes represented by the NULL value 49246670Spluknetin the msg_iov field from struct msghdr{}. 50159045Smaxim 51246670SpluknetIf Client sends some ancillary data object, then this ancillary data object 52246670Spluknetalways has associated data array by default. The "-z 2" or "-z 3" option 53246670Spluknetmeans, that Client will not send associated data array if possible. 54159045Smaxim 55159045SmaximFor SOCK_STREAM sockets: 56159045Smaxim----------------------- 57159045Smaxim 58159045Smaxim 1: Sending, receiving cmsgcred 59159045Smaxim 60246670Spluknet Client connects to Server and sends N messages with SCM_CREDS ancillary 61246670Spluknet data object. Server should receive N messages, each message should 62246670Spluknet have SCM_CREDS ancillary data object followed by struct cmsgcred{}. 63159045Smaxim 64246670Spluknet 2: Receiving sockcred (listening socket) 65159045Smaxim 66246670Spluknet Server creates a listening stream socket and sets the LOCAL_CREDS 67246670Spluknet socket option for it. Client connects to Server two times, each time 68246670Spluknet it sends N messages. Server accepts two connections and receives N 69246670Spluknet messages from each connection. The first message from each connection 70246670Spluknet should have SCM_CREDS ancillary data object followed by struct sockcred{}, 71246670Spluknet next messages from the same connection should not have ancillary data. 72159045Smaxim 73246670Spluknet 3: Receiving sockcred (accepted socket) 74159045Smaxim 75246670Spluknet Client connects to Server. Server accepts connection and sets the 76246670Spluknet LOCAL_CREDS socket option for just accepted socket. Client sends N 77246670Spluknet messages to Server. Server should receive N messages, the first 78246670Spluknet message should have SCM_CREDS ancillary data object followed by 79246670Spluknet struct sockcred{}, next messages should not have ancillary data. 80159045Smaxim 81159045Smaxim 4: Sending cmsgcred, receiving sockcred 82159045Smaxim 83246670Spluknet Server creates a listening stream socket and sets the LOCAL_CREDS 84246670Spluknet socket option for it. Client connects to Server and sends N messages 85246670Spluknet with SCM_CREDS ancillary data object. Server should receive N messages, 86246670Spluknet the first message should have SCM_CREDS ancillary data object followed 87246670Spluknet by struct sockcred{}, each of next messages should have SCM_CREDS 88246670Spluknet ancillary data object followed by struct cmsgcred{}. 89159045Smaxim 90246670Spluknet 5: Sending, receiving timeval 91159045Smaxim 92246670Spluknet Client connects to Server and sends message with SCM_TIMESTAMP ancillary 93246670Spluknet data object. Server should receive one message with SCM_TIMESTAMP 94246670Spluknet ancillary data object followed by struct timeval{}. 95159045Smaxim 96246670Spluknet 6: Sending, receiving bintime 97246670Spluknet 98246670Spluknet Client connects to Server and sends message with SCM_BINTIME ancillary 99246670Spluknet data object. Server should receive one message with SCM_BINTIME 100246670Spluknet ancillary data object followed by struct bintime{}. 101246670Spluknet 102246670Spluknet 7: Checking cmsghdr.cmsg_len 103246670Spluknet 104246670Spluknet Client connects to Server and tries to send several messages with 105246670Spluknet SCM_CREDS ancillary data object that has wrong cmsg_len field in its 106246670Spluknet struct cmsghdr{}. All these attempts should fail, since cmsg_len 107246670Spluknet in all requests is less than CMSG_LEN(0). 108246670Spluknet 109246670Spluknet 8: Check LOCAL_PEERCRED socket option 110246670Spluknet 111246670Spluknet This test does not use ancillary data, but can be implemented here. 112246670Spluknet Client connects to Server. Both Client and Server verify that 113246670Spluknet credentials of the peer are correct using LOCAL_PEERCRED socket option. 114246670Spluknet 115159045SmaximFor SOCK_DGRAM sockets: 116159045Smaxim---------------------- 117159045Smaxim 118159045Smaxim 1: Sending, receiving cmsgcred 119159045Smaxim 120246670Spluknet Client connects to Server and sends N messages with SCM_CREDS ancillary 121246670Spluknet data object. Server should receive N messages, each message should 122246670Spluknet have SCM_CREDS ancillary data object followed by struct cmsgcred{}. 123159045Smaxim 124159045Smaxim 2: Receiving sockcred 125159045Smaxim 126246670Spluknet Server creates datagram socket and sets the LOCAL_CREDS socket option 127246670Spluknet for it. Client sends N messages to Server. Server should receive N 128246670Spluknet messages, each message should have SCM_CREDS ancillary data object 129246670Spluknet followed by struct sockcred{}. 130159045Smaxim 131159045Smaxim 3: Sending cmsgcred, receiving sockcred 132159045Smaxim 133246670Spluknet Server creates datagram socket and sets the LOCAL_CREDS socket option 134246670Spluknet for it. Client sends N messages with SCM_CREDS ancillary data object 135246670Spluknet to Server. Server should receive N messages, the first message should 136246670Spluknet have SCM_CREDS ancillary data object followed by struct sockcred{}, 137246670Spluknet each of next messages should have SCM_CREDS ancillary data object 138246670Spluknet followed by struct cmsgcred{}. 139159045Smaxim 140246670Spluknet 4: Sending, receiving timeval 141159045Smaxim 142246670Spluknet Client sends one message with SCM_TIMESTAMP ancillary data object 143246670Spluknet to Server. Server should receive one message with SCM_TIMESTAMP 144246670Spluknet ancillary data object followed by struct timeval{}. 145246670Spluknet 146246670Spluknet 5: Sending, receiving bintime 147246670Spluknet 148246670Spluknet Client sends one message with SCM_BINTIME ancillary data object 149246670Spluknet to Server. Server should receive one message with SCM_BINTIME 150246670Spluknet ancillary data object followed by struct bintime{}. 151246670Spluknet 152246670Spluknet 6: Checking cmsghdr.cmsg_len 153246670Spluknet 154246670Spluknet Client tries to send Server several messages with SCM_CREDS ancillary 155246670Spluknet data object that has wrong cmsg_len field in its struct cmsghdr{}. 156246670Spluknet All these attempts should fail, since cmsg_len in all requests is less 157246670Spluknet than CMSG_LEN(0). 158246670Spluknet 159159045Smaxim- Andrey Simonenko 160246670Spluknetandreysimonenko@users.sourceforge.net 161