| 103 | | The rest of the report will discuss the lowest module, implemented as the shared library, \textbf{Libmac~\cite{Libmac+manual}}. |
| | 103 | The rest of this page will discuss the lowest module, implemented as the shared library, Libmac. |
| | 104 | |
| | 105 | === Libmac API === |
| | 106 | |
| | 107 | List of features implemented |
| | 108 | |
| | 109 | Features provided by this library include: \begin{enumerate} |
| | 110 | \item Ethernet frame injection and capture. |
| | 111 | \item Manipulation of a subset of wireless interface parameters at both aggregate and |
| | 112 | per-packet levels of granularity. |
| | 113 | \item Communication of a subset of wireless interface parameters from the sending end of a network |
| | 114 | connection to the receiving end, on a per-packet granularity level. |
| | 115 | \item Reception of the entire 802.11 frame, when the receiver is in RFMON mode. |
| | 116 | \item Appending parameters to all incoming frames and using the pcap filters to receive only |
| | 117 | those frames that the user of the library is interested in. |
| | 118 | \end{enumerate} |
| | 119 | |
| | 120 | Driver-level support is required for features 2, 3 and 5. This support has been provided by modifying the |
| | 121 | Cisco/Aironet driver (4500/4800/340/350 series cards) and the HostAP driver (v0.0.4) for wireless LAN cards |
| | 122 | based on Intersil Prism2/2.5/3 chipset. Details of these modifications can be found in the documentation |
| | 123 | that comes with the library. |
| | 124 | |
| | 125 | \subsection{Ethernet frame injection and capture} |
| | 126 | |
| | 127 | The usage paradigm, for sending or receiving frames using this library, is as follows: |
| | 128 | \begin{enumerate} |
| | 129 | \item Obtain parameter information using the mac\_get\_ifinfo function. The argument should be the address of a {NULL} pointer. |
| | 130 | \item {OPTIONAL:} Allocate memory for, and initialize, the mac\_params and the mac\_params\_flags structures in case you are going |
| | 131 | to use the mac\_get\_params or mac\_set\_params function. Use the mac\_init\_params function for the same. Again, the arguments |
| | 132 | {SHOULD BE} addresses of {NULL} pointers. |
| | 133 | \item {OPTIONAL:} Call any one of the parameter functions, mac\_get\_params or mac\_set\_params or mac\_append\_params. |
| | 134 | \item For each frame that you want to send and depending on the destination address, either call mac\_send\_broadcast or |
| | 135 | mac\_send\_unicast. \\For each frame that you want to recv, call mac\_recv. The double pointers, header, |
| | 136 | payload, send\_parameter\_info and recv\_parameter\_info SHOULD BE addresses of {NULL} pointers. The pointer len, should be |
| | 137 | the address of an unsigned short. |
| | 138 | \item {OPTIONAL:} Free memory, if allocated, for the mac\_params and the mac\_pa- |
| | 139 | rams\_flags structures using the mac\_free\_params function. |
| | 140 | \item Free interface information using the mac\_free\_ifinfo before exiting. |
| | 141 | \end{enumerate} |
| | 142 | |
| | 143 | The function, \texttt{int mac\_get\_ifinfo (struct mac\_ifinfo **mac\_ptr)}, is used to obtain information on all existing interfaces. |
| | 144 | It has one argument, which is a pointer to a linked list of structures. Each structure in the list contains members |
| | 145 | which can store the name of interface, hardware address, ip address, whether the interface is wireless or not and other relevant |
| | 146 | information. The information stored in these structures is used by the rest of the functions in the library. \newline |
| | 147 | |
| | 148 | Likewise, the function, \texttt{int mac\_free\_ifinfo (struct mac\_ifinfo \\ |
| | 149 | **mac\_ptr)}, is used to free the memory allocated for interface information. |
| | 150 | It also has one argument, which is the pointer to the linked list of structures. \newline |
| | 151 | |
| | 152 | The function, \texttt{int mac\_send\_broadcast (u\_char *payload, short len, \\ |
| | 153 | struct mac\_ifinfo\_list *q)}, is used to assemble an ethernet frame with the specified payload |
| | 154 | and broadcast (MAC-level) this frame. The first argument is the pointer to the payload, |
| | 155 | the second one is the length of the payload and the third one is the structure containing |
| | 156 | the name of the interface on which this frame needs to be sent. \newline |
| | 157 | |
| | 158 | The function, \texttt{int mac\_send\_unicast (u\_char *payload, short len, \\ |
| | 159 | struct mac\_ifinfo\_list *q, unsigned char *ucast\_mac)}, is used to |
| | 160 | assemble an ethernet frame with the specified payload and send this frame |
| | 161 | to a unicast MAC address. The first argument is the pointer to the payload, |
| | 162 | the second one is the length of the payload, the third one is the structure |
| | 163 | containing the name of the interface on which this frame needs to be sent and |
| | 164 | the fourth argument is a pointer to the MAC address of the destination. \newline |
| | 165 | |
| | 166 | The function, \texttt{int mac\_recv (struct ether\_header **header, \\ |
| | 167 | char **payload, unsigned short *len, unsigned char **send\_params, \\ |
| | 168 | unsigned char **recv\_params, struct mac\_ifinfo\_list *q, char *filter)}, is used to receive |
| | 169 | an ethernet frame. Its arguments include pointers to store ethernet header information, payload, length of the payload, |
| | 170 | sending side parameters that have been appended, receiving side parameters that have been appended and the pcap~\cite{Libpcap+doc} |
| | 171 | filter that is to applied. \newline |
| | 172 | |
| | 173 | Note that parameters are appended to all incoming frames and the pcap filters can be used to |
| | 174 | receive only those frames that the user of the library is interested in. |
| | 175 | |
| | 176 | \subsection{Manipulation of a subset of wireless interface parameters at both aggregate and |
| | 177 | per-packet levels of granularity} |
| | 178 | |
| | 179 | The function, \texttt{int mac\_get\_params (struct mac\_params *h, struct mac\_if- |
| | 180 | info\_list *if\_ptr, int argc, ...)}, is used to request the driver to return information |
| | 181 | on interface parameters, specified by the fourth argument onwards. The first argument |
| | 182 | is the pointer to the mac\_params structure, where information, on retrieved parameter |
| | 183 | values, is to be stored. The second one is a pointer to the struct mac\_ifinfo\_list |
| | 184 | that specifies the interface to which, a call to this function, applies. The parameter |
| | 185 | settings on the specified interface will be returned. The third argument is the number |
| | 186 | of arguments that follow after this one. Each argument that follows corresponds to the |
| | 187 | key of a parameter. \newline |
| | 188 | |
| | 189 | The function, \texttt{int mac\_set\_params (struct mac\_params *h, struct mac\_ |
| | 190 | ifinfo\_list *if\_ptr, int argc, ...)}, is used to request the driver to operate on |
| | 191 | interface parameter settings, specified by the fourth argument onwards. The first |
| | 192 | argument is the pointer to the mac\_params structure, where information, on parameter |
| | 193 | settings, is stored. The second one is a pointer to the struct mac\_ifinfo\_list that |
| | 194 | specifies the interface to which, a call to this function, applies. The parameter values |
| | 195 | on the specified interface will be set. The third argument is the number of (key,value) |
| | 196 | pairs that follow after this one. |
| | 197 | |
| | 198 | \subsection{Communication of a subset of wireless interface parameters from the sending end of a network |
| | 199 | connection to the receiving end, on a per-packet granularity level} |
| | 200 | |
| | 201 | The function, \texttt{int mac\_append\_params (struct mac\_ifinfo\_list *if\_ptr, \\ |
| | 202 | unsigned char direction, int argc, ...)}, is used to request the driver to append |
| | 203 | interface parameter information, specified by the fourth argument onwards. The first |
| | 204 | argument is the pointer to the struct mac\_ifinfo\_list that specifies the interface |
| | 205 | to which, a call to this function, applies. All outgoing/incoming frames on the specified |
| | 206 | interface will have the specified parameters appended to them. The appending of parameters |
| | 207 | can also be turned off. The second argument is a variable, direction, that indicates |
| | 208 | whether parameters should be appended on outgoing and/or incoming frames. The third |
| | 209 | argument is the number of arguments that follow after this one. Each argument that |
| | 210 | follows corresponds to the key of a parameter that needs to be appended. |
| | 211 | |
| | 212 | \subsection{Reception of the entire 802.11 frame, when the receiver is in RFMON mode} |
| | 213 | |
| | 214 | The function, \texttt{int mac\_promisc\_recv (unsigned char **frame, unsigned short |
| | 215 | *frame\_len, unsigned char **send\_params, unsigned char **recv\_params, struct mac\_ |
| | 216 | ifinfo\_list *q)}, is used to receive an 802.11 frame, in RFMON mode, on an interface |
| | 217 | specified by the user, and retrieve pointers to the frame, length and parameters. |
| | 218 | Its arguments include pointers to store the entire frame, length of the frame, sending side |
| | 219 | parameters that have been appended, receiving side parameters that have been appended |
| | 220 | and the structure that specifies the interface to which a call to this function applies. \newline |
| | 221 | |
| | 222 | Note that parameters are appended to all incoming 802.11 frames and current version of the library |
| | 223 | does not parse the received frame to extract send-side parameter information that is appended. |
| | 224 | |
| | 225 | Detailed documentation on all these functions and their implementation details are included in every |
| | 226 | release, which can be downloaded from /common/Orbit/repository. The interested reader is directed |
| | 227 | to these for more information. |
| | 228 | |
