libmac.h File Reference

Descriptions of the functions and data structures in this library. More...

#include <sys/types.h>
#include <sys/socket.h>
#include <stdio.h>
#include <math.h>
#include <errno.h>
#include <fcntl.h>
#include <ctype.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/ioctl.h>
#include <netinet/in.h>
#include <netinet/ether.h>
#include <arpa/inet.h>
#include <net/if_arp.h>
#include <libnet.h>
#include <pcap.h>
#include <assert.h>
#include <time.h>
#include <syslog.h>
#include <stdarg.h>
#include "libmac_cmn.h"
#include <limits.h>

Go to the source code of this file.

Data Structures
struct	mac_promisc_recv_frame_info
	Structure, to store per-packet information between the callback function of pcap_loop and mac_promisc_recv. More...
struct	mac_recv_frame_info
	Structure, to store per-packet information between the callback function of pcap_loop and mac_recv. More...
struct	mac_ifinfo_list
	Linked list containing structures, as members, for existing interfaces. More...
struct	mac_ifinfo
	Structure, containing a linked list and a version number field, as members. More...
struct	mac_params
	Structure, to implement the parameters as key-value pairs. More...
struct	mac_params_flags
	Structure, to implement what the application wants to do (set/get/append/receive), with regards to the parameters, using flag variables. More...
Defines
#define	DEBUG_ERR
	Debug macro. Always present.
#define	DEBUG_BASIC
	Debug macro. Higher level of debugging.
#define	USE_PROC_INTERFACE_OK   0
	Macro that says that use of proc interface is allowed. If not defined, then ioctl is used to setting txpower as well.
#define	IFNAME   8
	Constant name for size of interface.
#define	IPSIZE   16
	Constant name for size of IP address.
#define	MACSIZE   6
	Constant name for size of MAC address.
#define	VERSION   1.2
	Current version # of this library.
#define	FRM_TYPE   0x0900
	WINLAB frame type.
#define	MAX_FRAME_SIZE   1500
	Libnet-restricted max. frame size.
#define	IOCTL_BUF_SIZE   1024
	IOCTL Buffer size. Used by the ioctl that obtains basic information on all interfaces.
#define	PROC_BUF_SIZE   128
	Buffer size used to store command that is passed to system call for setting txpower parameter.
#define	SET   0
	Constant that results in flag bits being set, defined for the mode1 byte in the mac_params_setflags function.
#define	RESET   1
	Constant that results in flag bits being reset, defined for the mode1 byte in the mac_params_setflags function.
#define	GET_FLAG   0
	Constant that results in the get_flag bits being set/reset, defined for the mode2 byte in the mac_params_setflags function.
#define	SET_FLAG   1
	Constant that results in the set_flag bits being set/reset, defined for the mode2 byte in the mac_params_setflags function.
#define	APPEND_FLAG   2
	Constant that results in the append_flag bits being set/reset, defined for the mode2 byte in the mac_params_setflags function.
#define	INCLUDE_FLAG   3
	Constant that results in flag bits of include_flag, being set/reset, defined for the mode2 byte in the mac_params_setflags function.
#define	CHANGE_FLAG   4
	Constant that results in flag bits of change_flag, being set/reset, defined for the mode2 byte in the mac_params_setflags function.
#define	OUTGOING   0
	Constant that results in parameters being appended to all outgoing frames, defined for direction byte in the mac_append_params function.
#define	INCOMING   1
	Constant that results in parameters being appended to all incoming frames, defined for direction byte in the mac_append_params function.
#define	APPEND_OFF   2
	Constant that results in the stopping of parameter-appending to all frames.
#define	INIT_VAL   -1
	Constant that is the value to which all <key, value> pairs are initialized.
#define	UNSUPPORTED   INT_MIN
	Constant that is the value to which the value, corresponding to a key, is set, in the mac_set_params function, in case the parameter is not supported.
#define	READONLY   INT_MAX
	Constant that is the value to which the value, corresponding to a key, is set, in the mac_set_params function, in case the parameter is read-only.
#define	SIZEOF_PARAMS_LIST_LEN   sizeof(char)
	Constant that indicates the size, in bytes, of the length field that is prepended to the parameter information.
#define	SIZEOF_PARAMS_LIST_KEY   sizeof(char)
	Constant that indicates the size, in bytes, of the key field in the parameter information that is appended.
#define	SIZEOF_PARAMS_LIST_VALUE   sizeof(unsigned short)
	Constant that indicates the size, in bytes, of the value field in the parameter information that is appended.
#define	BYTE_SIZE_MAX_16b_VALUE   5
	Constant that represents the size in bytes of the maximum 16-bit value (65535).
Functions
int	mac_get_ifinfo (struct mac_ifinfo **mac_ptr)
	Function returns information about all existing interfaces.
void	mac_free_ifinfo (struct mac_ifinfo **mac_ptr)
	Memory allocated by the function mac_get_ifinfo(), to store information on existing interfaces, is set free by this function.
int	iw_sockets_open (void)
	Function that opens a socket and returns the descriptor on success.
char *	pr_ether (unsigned char *ptr)
	Function that returns a string containing the MAC address seperated by colons.
int	mac_send_broadcast (u_char *payload, short len, struct mac_ifinfo_list *q)
	Function sends an 802.11 frame to the broadcast MAC address.
int	mac_send_unicast (u_char *payload, short len, struct mac_ifinfo_list *q, unsigned char *ucast_mac)
	Function sends an 802.11 frame to a unicast MAC address.
int	mac_recv (struct ether_header **header, char **payload, unsigned short *len, unsigned char **send_params, unsigned char **recv_params, struct mac_ifinfo_list *q, char *filter)
	Function receives the ethernet frame, encapsulated within an 802.11 frame, on an interface specified by the user and retrieves pointers to the header, payload and parameters.
int	mac_promisc_recv (unsigned char **frame, unsigned short *frame_len, unsigned char **send_params, unsigned char **recv_params, struct mac_ifinfo_list *q)
	Function receives the 802.11 frame, on an interface specified by the user and retrieves pointers to the frame, length and parameters.
int	mac_init_params (struct mac_params **h, struct mac_params_flags **g)
	Function allocates memory and initializes the mac_params and mac_params_flags structures.
void	mac_free_params (struct mac_params **h, struct mac_params_flags **g)
	Memory allocated by the function mac_init_params(), is set free by this function.
int	mac_get_params (struct mac_params *h, struct mac_ifinfo_list *if_ptr, int argc,...)
	Function that requests the driver to return parameter information, specified by the fourth argument onwards.
int	mac_set_params (struct mac_params *h, struct mac_ifinfo_list *if_ptr, int argc,...)
	Function that requests the driver to operate on particular parameter settings, specified by the fourth argument onwards.
int	mac_append_params (struct mac_ifinfo_list *if_ptr, unsigned char direction, int argc,...)
	Function that requests the driver to append parameter information, specified by the fourth argument onwards.

---

Detailed Description

---

Function Documentation

int mac_get_ifinfo (  struct mac_ifinfo **  mac_ptr  )

Function returns a structure that contains information about all existing interfaces that are "up". Arguments : A pointer to a pointer to the struct, mac_ifinfo. This argument SHOULD BE the address of a struct mac_ifinfo pointer, initialized to NULL. Return Values : On failure, errno is returned. On success, 0 is returned with relevant information about all interfaces in the first argument. Error codes returned for Failed socket open call. Failed ioctl calls. Insufficient memory.

void mac_free_ifinfo (  struct mac_ifinfo **  mac_ptr  )

Arguments : A pointer to a pointer to struct, mac_ifinfo. Return Values : No value (void) is returned. Error codes returned for None.

int iw_sockets_open (  void   )

Borrowed from wireless_tools.26/iwlib.c. Open a socket depending on the protocol present. The socket descriptor is used for all the ioctl calls made to fill the mac_ifinfo struct. Arguments : void. Return Values : socket descriptor on success or -1 on error. Error codes returned for Failed socket system call.

char* pr_ether (  unsigned char *  ptr  )

Borrowed from wireless_tools.26/iwlib.c. Arguments : unsigned char pointer to the MAC address. Return Values : MAC address seperated by colons on success or NULL on error. Error codes returned for NULL argument value.

int mac_send_broadcast (  u_char *  payload, short  len, struct mac_ifinfo_list *  q )

This function uses the libnet functions to send the application payload to a broadcast MAC address. Arguments : The first argument is a pointer to a char array that consists of the payload. The payload is NOT a null-terminated string. The second argument is the length of the payload. Length is explicitly provided since we need to make sure that it is bounded between the minimum and maximum allowable lengths on ethernet/802.11. We cannot user strlen(payload) since there can be NULL characters in the payload itself. The third argument is a pointer to the struct mac_ifinfo_list. Information in this struct is used by the libnet functions, for e.g. the device name of this interface, its hardware address, etc. The struct field mac_ifinfo_list->link_struct, is also filled in with relevant information for future use. Return Values : On failure, errno is returned. On success, 0 is returned. Error codes returned for unusable argument values. libnet library function call failures.

int mac_send_unicast (  u_char *  payload, short  len, struct mac_ifinfo_list *  q, unsigned char *  ucast_mac )

This function, is exactly the same as the mac_send_broadcast function except that it sends the frame to a unicast MAC address. The IP address of the destination is provided by the calling function and the unicast MAC address is obtained by executing an ioctl call that looks up the MAC address corresponding to this IP address in the ARP cache. Arguments : The first three arguments are the same as for the mac_send_broadcast function. The fourth argument is a pointer to the destination IP address. Return Values : On failure, errno or error code is returned. On success, 0 is returned. Error codes returned for unusable argument values. when length of (payload + parameters) greater than MAX_PAYLOAD_SIZE bytes. libnet library function call failures.

int mac_recv (  struct ether_header **  header, char **  payload, unsigned short *  len, unsigned char **  send_params, unsigned char **  recv_params, struct mac_ifinfo_list *  q, char *  filter )

Arguments : The first argument is a pointer to a pointer to the ethernet header of the received frame. The second argument is a pointer to a pointer to the received payload. When the function returns, this pointer contains the address of the payload in the received frame. The received payload is NOT a null-terminated string. This argument SHOULD BE the address of a char pointer, initialized to NULL. The third argument is a pointer to the length of the payload, in bytes. Length is an argument as there can be NULL characters in the payload itself. Memory for this argument should be allocated by the calling function. The fourth argument is a pointer to a pointer to an unsigned char. This argument is used to store the address of the first byte after the payload that is the starting point of the appended send-side parameter information. The first byte after the payload contains a number that represents the #(appended send-side params.). This argument SHOULD BE the address of a u_char pointer, initialized to NULL. The fifth argument is a pointer to a pointer to an unsigned char. This argument is used to store the address of the first byte after the send-side parameters that is the starting point of the appended recv-side parameter information. The first byte after the send-side params. contains a number that represents the #(appended recv-side params.). This argument SHOULD BE the address of a u_char pointer, initialized to NULL. The sixth argument is a pointer to the struct mac_ifinfo_list. Information in this struct is used by the libpcap functions, for e.g. the device name of this interface, its hardware address, etc. The struct field mac_ifinfo_list->pcap_descr, is also filled in with relevant information for future use. The seventh argument is a pointer to the string that contains the filter program to be set for this interface. CHANGE: Unlike previous versions, this argument need not always be set to "ether proto 0x0900". Other kinds of filters can be used as well. Values for this argument are the same as those defined for filters in the tcpdump/pcap libraries. Return Values : On failure, errno will be returned. On success, 0 is returned. Error codes returned for unusable argument values. Libpcap function call failures.

int mac_promisc_recv (  unsigned char **  frame, unsigned short *  frame_len, unsigned char **  send_params, unsigned char **  recv_params, struct mac_ifinfo_list *  q )

Arguments : The first argument is a pointer to a pointer to the entire 802.11 frame. The second argument is a pointer to the length of the received frame. The third argument is a pointer to a pointer to an unsigned char. This argument is used to store the address of the first byte after the payload that is the starting point of the appended send-side parameter information. The first byte after the payload contains a number that represents the #(appended send-side params.). This argument SHOULD BE the address of a u_char pointer, initialized to NULL. The fourth argument is a pointer to a pointer to an unsigned char. This argument is used to store the address of the first byte after the send-side parameters that is the starting point of the appended recv-side parameter information. The first byte after the send-side params. contains a number that represents the #(appended recv-side params.). This argument SHOULD BE the address of a u_char pointer, initialized to NULL. The fifth argument is a pointer to the struct mac_ifinfo_list. Information in this struct is used by the libpcap functions, for e.g. the device name of this interface, its hardware address, etc. The struct field mac_ifinfo_list->pcap_descr, is also filled in with relevant information for future use. Return Values : On failure, errno will be returned. On success, 0 is returned. Error codes returned for unusable argument values. Libpcap function call failures.

int mac_init_params (  struct mac_params **  h, struct mac_params_flags **  g )

Arguments: The first argument is a pointer to a pointer to the mac_params struct that is to be initialized. This argument SHOULD BE the address of a struct mac_params pointer, initialized to NULL. The second argument is a pointer to a pointer to the mac_params_flags struct that is to be initialized. This argument SHOULD BE the address of a struct mac_params_flags pointer, initialized to NULL. Return values: On failure, errno is returned. On success, 0 is returned. Error conditions: Insufficient allocation memory.

void mac_free_params (  struct mac_params **  h, struct mac_params_flags **  g )

Arguments: The first argument is a pointer to a pointer to the mac_params struct. The second argument is a pointer to a pointer to the mac_params_flags struct. Return values: No value (void) is returned. Error conditions: None.

int mac_get_params (  struct mac_params *  h, struct mac_ifinfo_list *  if_ptr, int  argc,   ... )

This function requests the driver to return parameter value information and stores it in the mac_params struct. Arguments: The first argument is a pointer to mac_params, where information, on retrieved parameter values, is to be stored. The second argument is a pointer to the struct mac_ifinfo_list that specifies the interface to which, a call to this function, applies. The parameter settings on the specified interface will be returned. The third argument is the number of arguments that follow after this one. Each argument that follows corresponds to the key of a parameter. Return values: On failure, errno is returned. On success, 0 is returned. Error conditions: unusable argument values. Failed socket open call. if key given corresponds to an unsupported parameter. ioctl function call failure. if this function is called for a wired interface.

int mac_set_params (  struct mac_params *  h, struct mac_ifinfo_list *  if_ptr, int  argc,   ... )

This function requests the driver to set parameter values to those specified in the variable argument list. Arguments: The first argument is a pointer to mac_params where information, on parameter values, is to be stored.. The second argument is a pointer to the struct mac_ifinfo_list that specifies the interface to which, a call to this function, applies. The parameter settings on the specified interface will be set. The third argument is the number of <key,value> pairs that follow after this one. Return values: On failure, error code or errno is returned. On success, 0 is returned. Error conditions: unusable argument values. Failed socket open call. if key given corresponds to an unsupported parameter. ioctl function call failure or "system" system call failure. if this function is called for a wired interface.

int mac_append_params (  struct mac_ifinfo_list *  if_ptr, unsigned char  direction, int  argc,   ... )

This function requests the driver to append parameters to each frame in the outgoing/incoming direction. It is also used to turn all parameter appending off. Arguments: The fisrt argument is a pointer to the struct mac_ifinfo_list that specifies the interface to which, a call to this function, applies. All outgoing/incoming frames on the specified interface will have the specified parameters appended to them. The appending of parameters can also be turned off. A char variable, direction, that indicates whether parameters should be appended on outgoing and/or incoming frames. Legal values are OUTGOING(0), INCOMING(1) and APPEND_OFF(2). Return values: On failure, errno is returned. On success, 0 is returned. Error conditions: unusable argument values. Failed socket open call. if key corresponds to a parameter that cannot be appended in a particular direction. For e.g. rssi on outgoing frames. if key given corresponds to an unsupported parameter. ioctl function call failure or "system" system call failure. if this function is called for a wired interface.

---