#include <net/ethernet.h>
#include <linux/udp.h>
#include <linux/ip.h>
#include <arpa/inet.h>
#include <stdio.h>
#include <stdbool.h>
#include <string.h>

Data Structures
struct	ipaddrs
	Structure to store a couple of source and destinaion IPv4 addresses. More...

Macros
#define	MAC_FILE_PATH_SIZE 23

#define	MAC_ADDR_SIZE 6

#define	ERR_WLAN_NOIF 0

#define	ERR_WLAN_SOCK -1

#define	ERR_WLAN_GETIFADDRS -2

#define	ERR_WLAN_INDEX -3

#define	ERR_WLAN_GETSRCMAC -4

#define	ERR_WLAN_GETIFINDEX -5

#define	ERR_WLAN_GETSRCIP -6

#define	ERR_IPHEAD_SOCK -10

#define	ERR_IPHEAD_NOSRCADDR -11

#define	ERR_VIFPRINTER_SOCK -20

#define	ERR_VIFPRINTER_GETIFADDRS -21

#define	WLANLOOKUP_WLAN 0

#define	WLANLOOKUP_NONWLAN 1

#define	MAC_NULL 0x00

#define	MAC_BROADCAST 0x01

#define	MAC_UNICAST 0x02

#define	MAC_MULTICAST 0x03

#define	MAC_ZERO 0x04

#define	ETHERTYPE_GEONET 0x8947

#define	ETHERTYPE_WSMP 0x88DC

#define	WLANLOOKUP_LOOPBACK -1

#define	BASIC_IHL 5

#define	IPV4 4

#define	BASIC_UDP_TTL 64

#define	UDPHEADERLEN 8

#define	FLAG_NOFRAG_MASK (1<<6)

#define	FLAG_RESERVED_MASK (1<<7)

#define	FLAG_MOREFRAG_MASK (1<<5)

#define	CSUM_IP 0x00

#define	CSUM_UDP 0x01

#define	CSUM_UDPIP 0x80

#define	PRI_MAC "%02x:%02x:%02x:%02x:%02x:%02x"

#define	MAC_PRINTER(mac_array) mac_array[0], mac_array[1], mac_array[2], mac_array[3], mac_array[4], mac_array[5]

#define	SCN_MAC "%x:%x:%x:%x:%x:%x%*c"

#define	MAC_SCANNER(mac_array) &mac_array[0], &mac_array[1], &mac_array[2], &mac_array[3], &mac_array[4], &mac_array[5]

#define	UDP_PACKET_SIZE(data) sizeof(struct udphdr)+sizeof(data)

#define	IP_UDP_PACKET_SIZE(data) sizeof(struct iphdr)+sizeof(struct udphdr)+sizeof(data)

#define	ETH_IP_UDP_PACKET_SIZE(data) sizeof(struct ether_header)+sizeof(struct iphdr)+sizeof(struct udphdr)+sizeof(data)

#define	UDP_PACKET_SIZE_S(size) sizeof(struct udphdr)+size

#define	IP_UDP_PACKET_SIZE_S(size) sizeof(struct iphdr)+sizeof(struct udphdr)+size

#define	ETH_IP_UDP_PACKET_SIZE_S(size) sizeof(struct ether_header)+sizeof(struct iphdr)+sizeof(struct udphdr)+size

#define	BYTE_TYPE

Typedefs
typedef uint8_t	byte_t

typedef uint8_t *	macaddr_t

typedef unsigned short	ethertype_t

typedef int	rawsockerr_t

typedef unsigned char	csumt_t

typedef __sum16	csum16_t

Enumerations
enum	protocol_t { UNSET_P, UDP, AMQP_0_9, AMQP_1_0 }
	Protocol type enumerator. More...

Functions
rawsockerr_t	wlanLookup (char devname, int ifindex, macaddr_t mac, struct in_addr *srcIP, int index, int mode)
	Automatically look for available WLAN, non-WLAN or loopback interfaces. More...

rawsockerr_t	vifPrinter (FILE *stream)
	Print information about available interfaces. More...

macaddr_t	prepareMacAddrT ()
	Prepare a macaddr_t variable. More...

unsigned int	macAddrTypeGet (macaddr_t mac)
	Get the MAC address type. More...

void	freeMacAddrT (macaddr_t mac)
	Free a macaddr_t variable. More...

void	rs_printerror (FILE *stream, rawsockerr_t code)
	Print more detailed error messages. More...

void	display_packet (const char text, byte_t packet, unsigned int len)
	Display packet in hexadecimal form. More...

void	display_packetc (const char text, byte_t packet, unsigned int len)
	Display packet in character form. More...

uint64_t	hton64 (uint64_t hostu64)
	Convert a 64-bit unsigned value between host and network byte order. More...

uint64_t	ntoh64 (uint64_t netu64)
	Convert a 64-bit unsigned value between network and host byte order. More...

void	etherheadPopulateB (struct ether_header *etherHeader, macaddr_t mac, ethertype_t type)
	Populate broadcast Ethernet header (variant of etherheadPopulate()) More...

void	etherheadPopulate (struct ether_header *etherHeader, macaddr_t macsrc, macaddr_t macdst, ethertype_t type)
	Populate Ethernet header. More...

size_t	etherEncapsulate (byte_t packet, struct ether_header header, byte_t *sdu, size_t sdusize)
	Combine Ethernet SDU and PCI. More...

void	getSrcMAC (struct ether_header *etherHeader, macaddr_t macsrc)
	Retrieve source MAC address field from Ethernet header. More...

rawsockerr_t	IP4headPopulateB (struct iphdr IPhead, char devname, unsigned char tos, unsigned short frag_offset, unsigned char ttl, unsigned char protocol, unsigned int flags, struct ipaddrs *addrs)
	Populate broadcast IP version 4 header (variant of IP4headPopulate()) More...

rawsockerr_t	IP4headPopulateS (struct iphdr IPhead, char devname, struct in_addr destIP, unsigned char tos, unsigned short frag_offset, unsigned char ttl, unsigned char protocol, unsigned int flags, struct ipaddrs *addrs)
	Populate IP version 4 header with struct in_addr addresses (variant of IP4headPopulate()) More...

rawsockerr_t	IP4headPopulate (struct iphdr IPhead, char devname, char destIP, unsigned char tos, unsigned short frag_offset, unsigned char ttl, unsigned char protocol, unsigned int flags, struct ipaddrs addrs)
	Populate IP version 4 header. More...

void	IP4headAddID (struct iphdr *IPhead, unsigned short id)
	Add ID to a given IPv4 header. More...

void	IP4headAddTotLen (struct iphdr *IPhead, unsigned short len)
	Add Total Length to a given IPv4 header. More...

size_t	IP4Encapsulate (byte_t packet, struct iphdr header, byte_t *sdu, size_t sdusize)
	Combine IPv4 SDU and PCI. More...

void	UDPheadPopulate (struct udphdr *UDPhead, unsigned short sourceport, unsigned short destport)
	Populate UDP header. More...

size_t	UDPencapsulate (byte_t packet, struct udphdr header, byte_t *data, size_t payloadsize, struct ipaddrs addrs)
	Combine UDP payload and header. More...

byte_t *	UDPgetpacketpointers (byte_t pktbuf, struct ether_header etherHeader, struct iphdr IPheader, struct udphdr *UDPheader)
	Get pointers to headers and payload in UDP packet buffer. More...

unsigned short	UDPgetpayloadsize (struct udphdr *UDPheader)
	Get UDP payload size, given a UDP header. More...

bool	validateEthCsum (byte_t packet, csum16_t csum, csum16_t combinedcsum, csumt_t type, void *args)
	Validate the checksum of a raw "Ethernet" packet, i.e. of any packet containing a struct ether_header as first bytes. More...

void	test_injectIPCsumError (byte_t *IPpacket)
	Test function: inject a checksum error in an IP packet. More...

void	test_injectUDPCsumError (byte_t *UDPpacket)
	Test function: inject a checksum error in an UDP packet. More...

Detailed Description

This file represents the main header file of the Rawsock library.

This file, represeting the main header file of the Rawsock library, should be included in your project everytime you want to use the library to simplify and enhance the use of Linux raw sockets. It supports, as of now, IPv4 and UDP.

Version: 0.3.4

Date: 2020-01-24

Copyright: Licensed under GPLv2

Definition in file rawsock.h.

Macro Definition Documentation

#define BASIC_IHL 5

IPv4 constant: basic Internet Header Length, without any options.

Definition at line 65 of file rawsock.h.

#define BASIC_UDP_TTL 64

IPv4 constant: some sort of "default" TTL which can be used to generate IPv4/UDP packets with a TTL of 64.

Definition at line 67 of file rawsock.h.

#define CSUM_IP 0x00

Simple validateEthCsum() checksum type (csum_t): compute IPv4 checksum by specifying CSUM_IP as type.

Definition at line 79 of file rawsock.h.

#define CSUM_UDP 0x01

Simple validateEthCsum() checksum type (csum_t): compute UDP checksum by specifying CSUM_UDP as type.

Definition at line 80 of file rawsock.h.

#define CSUM_UDPIP 0x80

Combined validateEthCsum() checksum type (csum_t): compute IPv4 and UDP checksums by specifying CSUM_UDPIP as type.

Warning: If you are extending the library and you want to add another combined type, always use a value from 0x81 to 0xFF, as 0x00 to 0x7F should be simple types, and 0x80 to 0xFF combined ones, to keep things clear.

Definition at line 81 of file rawsock.h.

#define ERR_IPHEAD_NOSRCADDR -11

IP4headPopulate*() error definition: unable to retrieve current device IP address.

Definition at line 40 of file rawsock.h.

#define ERR_IPHEAD_SOCK -10

IP4headPopulate*() error definition: internal socket creation error.

Definition at line 39 of file rawsock.h.

#define ERR_VIFPRINTER_GETIFADDRS -21

vifPrinter() error definition: getifaddrs() (to obtain interfaces list) error.

Definition at line 43 of file rawsock.h.

#define ERR_VIFPRINTER_SOCK -20

vifPrinter() error definition: socket creation error.

Definition at line 42 of file rawsock.h.

#define ERR_WLAN_GETIFADDRS -2

wlanLookup() error definition: getifaddrs() (to obtain interfaces list) error.

Definition at line 33 of file rawsock.h.

#define ERR_WLAN_GETIFINDEX -5

wlanLookup() error definition: unable to get source interface index (if requested).

Definition at line 36 of file rawsock.h.

#define ERR_WLAN_GETSRCIP -6

wlanLookup() error definition: unable to get source interface index (if requested).

Definition at line 37 of file rawsock.h.

#define ERR_WLAN_GETSRCMAC -4

wlanLookup() error definition: unable to get source MAC address (if requested).

Definition at line 35 of file rawsock.h.

#define ERR_WLAN_INDEX -3

wlanLookup() error definition: wrong index specified.

Definition at line 34 of file rawsock.h.

#define ERR_WLAN_NOIF 0

wlanLookup() error definition: no WLAN interfaces found.

Definition at line 31 of file rawsock.h.

#define ERR_WLAN_SOCK -1

wlanLookup() error definition: socket creation error.

Definition at line 32 of file rawsock.h.

#define ETH_IP_UDP_PACKET_SIZE ( data ) sizeof(struct ether_header)+sizeof(struct iphdr)+sizeof(struct udphdr)+sizeof(data)

Size definition: given data, as any variable, the IPv4 + UDP payload size (with basic IHL, i.e. no options), including struct ether_header, containing the specified data is calculated and returned in bytes.

Definition at line 94 of file rawsock.h.

#define ETH_IP_UDP_PACKET_SIZE_S ( size ) sizeof(struct ether_header)+sizeof(struct iphdr)+sizeof(struct udphdr)+size

Size definition: given size, in bytes, the IPv4 + UDP payload size (with basic IHL, i.e. no options), including struct ether_header, containing a payload with the specified size is calculated and returned in bytes.

Definition at line 98 of file rawsock.h.

#define ETHERTYPE_GEONET 0x8947

Additional EtherType definition: GeoNetworking, as defined in ETSI EN 302 636-4-1.

Definition at line 58 of file rawsock.h.

#define ETHERTYPE_WSMP 0x88DC

Additional EtherType definition: WAVE Short Message Protocol, as defined in IEEE Std 1609.3-2016.

Definition at line 59 of file rawsock.h.

#define FLAG_MOREFRAG_MASK (1<<5)

IPv4 flags mask: Mask to set the More Fragments (MF) IPv4 flag, in the flags argument of IP4headPopulate*()

Note: It can be OR-ed with other masks.

Definition at line 75 of file rawsock.h.

#define FLAG_NOFRAG_MASK (1<<6)

IPv4 flags mask: Mask to set the Don't Fragment (DF) IPv4 flag, in the flags argument of IP4headPopulate*()

Note: It can be OR-ed with other masks.

Definition at line 73 of file rawsock.h.

#define FLAG_RESERVED_MASK (1<<7)

IPv4 flags mask: Mask to set the Reserved IPv4 flag, in the flags argument of IP4headPopulate*()

Note: It can be OR-ed with other masks.

Definition at line 74 of file rawsock.h.

#define IP_UDP_PACKET_SIZE ( data ) sizeof(struct iphdr)+sizeof(struct udphdr)+sizeof(data)

Size definition: given data, as any variable, the IPv4 + UDP payload size (with basic IHL, i.e. no options) containing the specified data is calculated and returned in bytes.

Definition at line 93 of file rawsock.h.

#define IP_UDP_PACKET_SIZE_S ( size ) sizeof(struct iphdr)+sizeof(struct udphdr)+size

Size definition: given size, in bytes, the IPv4 + UDP payload size (with basic IHL, i.e. no options) containing a payload with the specified size is calculated and returned in bytes.

Definition at line 97 of file rawsock.h.

#define IPV4 4

IPv4 constant: basic Internet Header Length, in bytes without any options.

Definition at line 66 of file rawsock.h.

#define MAC_ADDR_SIZE 6

Size of a MAC address, in bytes. You can use this definition to declare your own uint8_t, unsigned char or byte_t array, with MAC_ADDR_SIZE elements, to store any MAC address. For instance: uint8_t macaddress[MAC_ADDR_SIZE];

Definition at line 28 of file rawsock.h.

#define MAC_BROADCAST 0x01

MAC type definition (managed by prepareMacAddrT(), macAddrTypeGet() and freeMacAddrT()): broadcast (FF:FF:FF:FF:FF:FF) MAC address.

Definition at line 51 of file rawsock.h.

#define MAC_FILE_PATH_SIZE 23

Reserved for future use.

Definition at line 27 of file rawsock.h.

#define MAC_MULTICAST 0x03

MAC type definition (managed by prepareMacAddrT(), macAddrTypeGet() and freeMacAddrT()): multicast (01:xx:xx:xx:xx:xx) MAC address.

Definition at line 53 of file rawsock.h.

#define MAC_NULL 0x00

MAC type definition (managed by prepareMacAddrT(), macAddrTypeGet() and freeMacAddrT()): NULL MAC-address (NULL pointer returned).

Definition at line 50 of file rawsock.h.

#define MAC_PRINTER ( mac_array ) mac_array[0], mac_array[1], mac_array[2], mac_array[3], mac_array[4], mac_array[5]

MAC_PRINTER(address-variable) should be used in combination with PRI_MAC to specify the variable containing the MAC address. For instance, if addr is a variable of type macaddr_t, it is possible to print the corresponding address with printf("Address: " PRI_MAC "\\n",MAC_PRINTER(addr)).

Warning: No check is performed to ensure that a NULL pointer (MAC_NULL) is not passed to MAC_PRINTER. The check must be manually performed to avoid a segmentation fault.

Definition at line 85 of file rawsock.h.

#define MAC_SCANNER ( mac_array ) &mac_array[0], &mac_array[1], &mac_array[2], &mac_array[3], &mac_array[4], &mac_array[5]

MAC_SCANNER(address-variable) should be used in combination with SCN_MAC to specify the variable containing the MAC address (without &, as it is already added by MAC_SCANNER). For instance, if addr is an allocated variable of type macaddr_t, it is possible to store an address inside addr with scanf(SCN_MAC,MAC_SCANNER(addr)).

Warning: No check is performed to ensure that a NULL pointer (MAC_NULL) is not passed to MAC_SCANNER. The check must be manually performed to avoid a segmentation fault (the variable should be already allocated with prepareMacAddrT()).

Definition at line 89 of file rawsock.h.

#define MAC_UNICAST 0x02

MAC type definition (managed by prepareMacAddrT(), macAddrTypeGet() and freeMacAddrT()): unicast MAC address.

Definition at line 52 of file rawsock.h.

#define MAC_ZERO 0x04

MAC type definition (managed by prepareMacAddrT(), macAddrTypeGet() and freeMacAddrT()): all-zero (00:00:00:00:00:00) MAC address (no MAC is set).

Definition at line 54 of file rawsock.h.

#define PRI_MAC "%02x:%02x:%02x:%02x:%02x:%02x"

Useful macro specifier for printing MAC addresses inside the printf() familty of functions. PRI_MAC works as a single specifier for the whole address, like PRIuxx in inttypes.h for printing xx bits integers, but without the leading %. See also the strictly related MAC_PRINTER macro.

Definition at line 84 of file rawsock.h.

#define SCN_MAC "%x:%x:%x:%x:%x:%x%*c"

Useful macro specifier for reading MAC addresses inside the scanf() familty of functions. SCN_MAC works as a single specifier for the whole address, like SCNuxx in inttypes.h for reading xx bits integers, but without the leading %. See also the strictly related MAC_SCANNER macro.

Definition at line 88 of file rawsock.h.

#define UDP_PACKET_SIZE ( data ) sizeof(struct udphdr)+sizeof(data)

Size definition: given data, as any variable, the UDP payload size containing the specified data is calculated and returned in bytes.

Definition at line 92 of file rawsock.h.

#define UDP_PACKET_SIZE_S ( size ) sizeof(struct udphdr)+size

Size definition: given size, in bytes, the UDP payload size containing a payload with the specified size is calculated and returned in bytes.

Definition at line 96 of file rawsock.h.

#define UDPHEADERLEN 8

UDP constant: number of bytes inside the UDP header.

Definition at line 70 of file rawsock.h.

#define WLANLOOKUP_LOOPBACK -1

wlanLookup() special index value definition: use WLANLOOKUP_LOOPBACK to search for loopback IF instead of WLAN IF.

Definition at line 62 of file rawsock.h.

#define WLANLOOKUP_NONWLAN 1

wlanLookup() mode definition: look for non-wireless interfaces only.

Definition at line 47 of file rawsock.h.

#define WLANLOOKUP_WLAN 0

wlanLookup() mode definition: look for wireless interfaces only.

Definition at line 46 of file rawsock.h.

Typedef Documentation

typedef uint8_t byte_t

Custom type to store a single byte. It should be defined only if it was not defined elsewhere.

Definition at line 102 of file rawsock.h.

typedef __sum16 csum16_t

Custom type to store checksums (it may be a bit clearer that using directly __sum16, although __sum16 is perfectly fine too).

Definition at line 109 of file rawsock.h.

typedef unsigned char csumt_t

Custom type to store checksum types to be passed to validateEthCsum().

Definition at line 108 of file rawsock.h.

typedef unsigned short ethertype_t

Custom type which can be used to store the EtherType.

Definition at line 106 of file rawsock.h.

typedef uint8_t* macaddr_t

Custom type to store a MAC address. It is better and should be managed with the provided prepareMacAddrT(), macAddrTypeGet() and freeMacAddrT() functions, to avoid messing up with pointer.

Definition at line 105 of file rawsock.h.

typedef int rawsockerr_t

Custom type to store errors returned by the library functions.

Definition at line 107 of file rawsock.h.

Enumeration Type Documentation

enum protocol_t

Protocol type enumerator.

Protocol type enumerator, useful to manage more than one protocol on a single program. As more protocols will be supported, this enum will be updated accordingly.

Enumerator
UNSET_P	Unspecified protocol type
UDP	UDP over IPv4
AMQP_0_9	AMQP 0.9 (RabbitMQ) - not yet supported by the library
AMQP_1_0	AMQP 1.0 (ActiveMQ) - not yet supported by the library

Definition at line 125 of file rawsock.h.

Function Documentation

void display_packet	(	const char *	text,
		byte_t *	packet,
		unsigned int	len
	)

Display packet in hexadecimal form.

This function can be used to display a packet content in hexadecimal form, given the pointer to a buffer of bytes and its length (len).

text can be used to specify an additional text that will be printer before printing the actual packet content.

Note: stdout is always used to print the requested information.

Parameters

[in]	text	Additional text preceding the packet content
[in]	packet	Buffer containing the whole packet to be printed
[in]	len	Length, in bytes, of the buffer to be printed (i.e. number of elements of the bytes buffer to be printed)

Returns: None.

Definition at line 459 of file rawsock.c.

void display_packetc	(	const char *	text,
		byte_t *	packet,
		unsigned int	len
	)

Display packet in character form.

This function can be used to display a packet content in character form, given the pointer to a buffer of bytes and its length (len).

text can be used to specify an additional text that will be printer before printing the actual packet content.

Note: stdout is always used to print the requested information.

Parameters

[in]	text	Additional text preceding the packet content
[in]	packet	Buffer containing the whole packet to be printed
[in]	len	Length, in bytes, of the buffer to be printed (i.e. number of elements of the bytes buffer to be printed)

Returns: None.

Definition at line 487 of file rawsock.c.

size_t etherEncapsulate	(	byte_t *	packet,
		struct ether_header *	header,
		byte_t *	sdu,
		size_t	sdusize
	)

Combine Ethernet SDU and PCI.

This function combines an Ethernet SDU and PCI, the latter in the form of a struct ether_header Linux structure.

The user shall specify a buffer in which the full packet will be put, the ethernet header, the SDU (byte_t *sdu) and its size in bytes.

Warning: The packet buffer should be already allocated, and it should be big enough to contain both the header and the SDU. It is possible to use the macros defined in rawsock.h, such as ETH_IP_UDP_PACKET_SIZE_S(udp_payload_size), to find the required size starting from an higher layer payload size and then call a malloc() with that size to allocate the memory for packet.

Parameters

[out]	packet	Packet buffer (should be already allocated) that will contain the full packet (SDU+PCI).
[in]	header	Ethernet header, as struct ether_header. Should be filled in with etherheadPopulate*() before being passed to this function.
[in]	sdu	Buffer containing the SDU.
[in]	sdusize	Size, in bytes, of the SDU.

Returns: The full packet size (SDU+PCI), in bytes, is returned.

Definition at line 612 of file rawsock.c.

void etherheadPopulate	(	struct ether_header *	etherHeader,
		macaddr_t	macsrc,
		macaddr_t	macdst,
		ethertype_t	type
	)

Populate Ethernet header.

This function can be used to populate an ethernet header (struct ether_header).

A variant, etherheadPopulateB(), addressed specifically to broadcast transmissions, exists.

The user shall specify the pointer to an already existing ether_header structure to be filled in, the source and destination MAC addresses and the EtherType (either one type in net/ethernet.h or one type in rawsock.h).

Note: Like all the other functions inside this library, it already takes care of byte ordering.

Warning: All the parameters passed to this function should be in host byte order, i.e. the "normal" one for the application.

Parameters

[out]	etherHeader	Pointer to the Ethernet header structure, used in raw sockets (for instance, to send data over a ETH_P_ALL socket).
[in]	macsrc	macaddr_t variable containing the source MAC address.
[in]	macdst	macaddr_t variable containing the destination MAC address.
[in]	type	ethertype_t variable containing the EtherType.

Returns: None.

Definition at line 587 of file rawsock.c.

void etherheadPopulateB	(	struct ether_header *	etherHeader,
		macaddr_t	mac,
		ethertype_t	type
	)

Populate broadcast Ethernet header (variant of etherheadPopulate())

This function can be used to populate an ethernet header (struct ether_header) for broadcast transmissions (i.e. a broadcast MAC address is automatically inserted).

The user shall specify the pointer to an already existing ether_header structure to be filled in, the source MAC and the EtherType (either one type in net/ethernet.h or one type in rawsock.h).

Note: Like all the other functions inside this library, it already takes care of byte ordering.

Warning: All the parameters passed to this function should be in host byte order, i.e. the "normal" one for the application.

Parameters

[in,out]	etherHeader	Pointer to the Ethernet header structure, used in raw sockets (for instance, to send data over a ETH_P_ALL socket).
[in]	mac	macaddr_t variable containing the source MAC address.
[in]	type	ethertype_t variable containing the EtherType.

Returns: None.

Definition at line 556 of file rawsock.c.

void freeMacAddrT ( macaddr_t mac )

Free a macaddr_t variable.

Frees a previously allocated MAC address variable (macaddr_t).

Parameters

[in] mac A previously allocated macaddr_t variable/pointer.

Returns: None.

Definition at line 78 of file rawsock.c.

void getSrcMAC	(	struct ether_header *	etherHeader,
		macaddr_t	macsrc
	)

Retrieve source MAC address field from Ethernet header.

Simple function to retrieve the source MAC address field from a struct ether_header, and copy it inside the macsrc variable.

Warning: Always be sure to pass a non-NULL macsrc to this function. In any case, if a NULL macsrc is passed, the function simply does nothing.

Parameters

[in]	etherHeader	struct ether_header, already filled in or extracted from a received packet.
[out]	macsrc	Source MAC address, filled in by the function.

Definition at line 633 of file rawsock.c.

uint64_t hton64 ( uint64_t hostu64 )

Convert a 64-bit unsigned value between host and network byte order.

This function works like htons() and htonl(), but with 64-bit unsigned integers (i.e. uint64_t).

Note: uint64_t is defined inside stdint.h and inttypes.h.; This function has no direct utility in IPv4/UDP packet management, but it can be used to manage any custom or non-custom 64 bit data field to be sent over the network.

Parameters

[in] hostu64 Host byte order integer to be converted into network byte order

Returns: 64-bit unsigned value value converted to network byte order

Definition at line 513 of file rawsock.c.

size_t IP4Encapsulate	(	byte_t *	packet,
		struct iphdr *	header,
		byte_t *	sdu,
		size_t	sdusize
	)

Combine IPv4 SDU and PCI.

This function combines an IPv4 SDU and PCI, the latter in the form of a struct iphdr Linux structure.

The user shall specify a buffer in which the full packet will be put, the IPv4 header, the SDU (byte_t *sdu) and its size in bytes.

Warning: The packet buffer should be already allocated, and it should be big enough to contain both the header and the SDU. It is possible to use the macros defined in rawsock.h, such as IP_UDP_PACKET_SIZE_S(udp_payload_size), to find the required size starting from an higher layer payload size and then call a malloc() with that size to allocate the memory for packet.

Parameters

[out]	packet	Packet buffer (should be already allocated) that will contain the full IPv4 packet (SDU+PCI).
[in]	header	IPv4 header, as struct iphdr. Should be filled in with IP4headPopulate*() before being passed to this function.
[in]	sdu	Buffer containing the SDU.
[in]	sdusize	Size, in bytes, of the SDU.

Returns: The full packet size (SDU+PCI), in bytes, is returned.

Definition at line 926 of file rawsock.c.

void IP4headAddID	(	struct iphdr *	IPhead,
		unsigned short	id
	)

Add ID to a given IPv4 header.

Since it can be useful, after preparing a certain header, to update quite often the IPv4 ID (depending on the application and on the use case, though), this function allows to perform the aformentioned operation, inserting a given id inside an already populated IPv4 header (IPhead).

Note: Since IP4headPopulate() and its variants only initialize the identification field to 0, a call to this function is required to set a specific ID inside an IPv4 header, before sending any packet over raw sockets.

Parameters

[in,out]	IPhead	IPv4 header structure (struct iphdr) in which the ID field has to be set.
[in]	id	16-bit IP identification value

Returns: None.

Definition at line 886 of file rawsock.c.

void IP4headAddTotLen	(	struct iphdr *	IPhead,
		unsigned short	len
	)

Add Total Length to a given IPv4 header.

This function can be used to force a certain length of the entire packet inside the IPv4 header Total Length field.

Note: This function should be used only if, for any reason, the packet to be sent will not be processed by IP4Encapsulate(). In all the other cases, when combining the IPv4 SDU and PCI with IP4Encapsulate() the Total Length field should be automatically set by the aforementioned function.

Parameters

[in,out]	IPhead	IPv4 header structure (struct iphdr) in which the Total Length field has to be set.
[in]	len	Length, in bytes, to be inserted inside the IPv4 header.

Returns: None.

Definition at line 904 of file rawsock.c.

rawsockerr_t IP4headPopulate	(	struct iphdr *	IPhead,
		char *	devname,
		char *	destIP,
		unsigned char	tos,
		unsigned short	frag_offset,
		unsigned char	ttl,
		unsigned char	protocol,
		unsigned int	flags,
		struct ipaddrs *	addrs
	)

Populate IP version 4 header.

This function can be used to populate an Ipv4 header (struct iphdr).

Two variants exist:

IP4headPopulateS(), to specify a struct in_addr destination IP address instead of a human-readable string
IP4headPopulateB(), to populate an IPv4 header for broadcast transmissions (a broadcast destination IP address is automatically inserted)

The user shall specify an already existing IP header structure to be filled in, the interface name inside devname (for instance wlan0), the destination IP address as a human-readable string (e.g. "192.168.1.180"), the TOS value, the fragment offset value, the TTL, the protocol and the IP header flags (reserved, DF, MF).

If struct ipaddrs *addrs is non-NULL, this function, other than returning possible errors (ERR_IPHEAD_SOCK or ERR_IPHEAD_NOSRCADDR) as return value, fills the structure pointed by addrs with the destination and source IP addresses.

Note: Like all the other functions inside this library, it already takes care of byte ordering.

Warning: All the parameters passed to this function should be in host byte order, i.e. the "normal" one for the application.; This function does not fill the ID field: an additional call to IP4headAddID() is required if you do not want to send a packet with 0 ID, for which, instead, it is not necessary to call IP4headAddID().

Parameters

[in,out]	IPhead	Pointer to the IPv4 header structure, used in raw sockets.
[in]	devname	Name of the interface which will be used to send the packet (it is used to automatically retrieve the source IP address)
[in]	destIP	Destination IP address, a string containing the address in a human-readable format.
[in]	tos	Type of Service (ToS) field.
[in]	frag_offset	IPv4 fragment offset field.
[in]	ttl	Time To Live (TTL) field.
[in]	protocol	Higher layer protocol field.
[in]	flags	IPv4 flags (reserved, DF, MF): should be filled in using the macros: FLAG_NOFRAG_MASK, FLAG_RESERVED_MASK and FLAG_MOREFRAG_MASK.
[out]	addrs	Pointer to the ipaddrs structure to be filled in with the destination and source IP addresses, or NULL if no structure has to be filled in.

Returns

0 if the header was filled in properly, or, in case of error, a rawsockerr_t error:

ERR_IPHEAD_SOCK -> internal socket creation error: unable to set source IP address inside the header
ERR_IPHEAD_NOSRCADDR -> cannot retrieve the source IP address to be inserted inside the header

Definition at line 678 of file rawsock.c.

rawsockerr_t IP4headPopulateB	(	struct iphdr *	IPhead,
		char *	devname,
		unsigned char	tos,
		unsigned short	frag_offset,
		unsigned char	ttl,
		unsigned char	protocol,
		unsigned int	flags,
		struct ipaddrs *	addrs
	)

Populate broadcast IP version 4 header (variant of IP4headPopulate())

This function can be used to populate an IPv4 header (struct iphdr) for broadcast transmissions.

The user shall specify an already existing IP header structure to be filled in, the interface name inside devname (for instance wlan0), the TOS value, the fragment offset value, the TTL, the protocol and the IP header flags (reserved, DF, MF).

A broadcast destination IP address is automatically inserted (i.e. 255.255.255.255).

If struct ipaddrs *addrs is non-NULL, this function, other than returning possible errors (ERR_IPHEAD_SOCK or ERR_IPHEAD_NOSRCADDR) as return value, fills the structure pointed by addrs with the destination and source IP addresses.

Note: Like all the other functions inside this library, it already takes care of byte ordering.

Warning: All the parameters passed to this function should be in host byte order, i.e. the "normal" one for the application.; This function does not fill the ID field: an additional call to IP4headAddID() is required if you do not want to send a packet with 0 ID, for which, instead, it is not necessary to call IP4headAddID().

Parameters

[in,out]	IPhead	Pointer to the IPv4 header structure, used in raw sockets.
[in]	devname	Name of the interface which will be used to send the packet (it is used to automatically retrieve the source IP address)
[in]	tos	Type of Service (ToS) field.
[in]	frag_offset	IPv4 fragment offset field.
[in]	ttl	Time To Live (TTL) field.
[in]	protocol	Higher layer protocol field.
[in]	flags	IPv4 flags (reserved, DF, MF): should be filled in using the macros: FLAG_NOFRAG_MASK, FLAG_RESERVED_MASK and FLAG_MOREFRAG_MASK.
[out]	addrs	Pointer to the ipaddrs structure to be filled in with the destination and source IP addresses, or NULL if no structure has to be filled in.

Returns

0 if the header was filled in properly, or, in case of error, a rawsockerr_t error:

ERR_IPHEAD_SOCK -> internal socket creation error: unable to set source IP address inside the header
ERR_IPHEAD_NOSRCADDR -> cannot retrieve the source IP address to be inserted inside the header

Definition at line 830 of file rawsock.c.

rawsockerr_t IP4headPopulateS	(	struct iphdr *	IPhead,
		char *	devname,
		struct in_addr	destIP,
		unsigned char	tos,
		unsigned short	frag_offset,
		unsigned char	ttl,
		unsigned char	protocol,
		unsigned int	flags,
		struct ipaddrs *	addrs
	)

Populate IP version 4 header with struct in_addr addresses (variant of IP4headPopulate())

This function can be used to populate an IPv4 header (struct iphdr).

The user shall specify an already existing IP header structure to be filled in, the interface name inside devname (for instance wlan0), the destination IP address, stored inside a struct in_addr, the TOS value, the fragment offset value, the TTL, the protocol and the IP header flags (reserved, DF, MF).

If struct ipaddrs *addrs is non-NULL, this function, other than returning possible errors (ERR_IPHEAD_SOCK or ERR_IPHEAD_NOSRCADDR) as return value, fills the structure pointed by addrs with the destination and source IP addresses.

Note: Like all the other functions inside this library, it already takes care of byte ordering.

Warning: All the parameters passed to this function should be in host byte order, i.e. the "normal" one for the application.; This function does not fill the ID field: an additional call to IP4headAddID() is required if you do not want to send a packet with 0 ID, for which, instead, it is not necessary to call IP4headAddID().

Parameters

[in,out]	IPhead	Pointer to the IPv4 header structure, used in raw sockets.
[in]	devname	Name of the interface which will be used to send the packet (it is used to automatically retrieve the source IP address)
[in]	destIP	Destination IP address, stored inside the s_addr field of the specified struct in_addr.
[in]	tos	Type of Service (ToS) field.
[in]	frag_offset	IPv4 fragment offset field.
[in]	ttl	Time To Live (TTL) field.
[in]	protocol	Higher layer protocol field.
[in]	flags	IPv4 flags (reserved, DF, MF): should be filled in using the macros: FLAG_NOFRAG_MASK, FLAG_RESERVED_MASK and FLAG_MOREFRAG_MASK.
[out]	addrs	Pointer to the ipaddrs structure to be filled in with the destination and source IP addresses, or NULL if no structure has to be filled in.

Returns

0 if the header was filled in properly, or, in case of error, a rawsockerr_t error:

ERR_IPHEAD_SOCK -> internal socket creation error: unable to set source IP address inside the header
ERR_IPHEAD_NOSRCADDR -> cannot retrieve the source IP address to be inserted inside the header

Definition at line 755 of file rawsock.c.

unsigned int macAddrTypeGet ( macaddr_t mac )

Get the MAC address type.

Starting from a MAC address type, its type is returned (unicast, multicast, broadcast).

Warning: As soon as a new MAC address is allocated, its type is set to the equivalent of MAC_NULL (i.e. a NULL pointer). You can use this to check if an address was properly allocated, by calling if(macAddrTypeGet(mac)!=MAC_NULL).

Parameters

[in] mac A previously allocated macaddr_t variable/pointer.

Returns: The MAC address tupe is returned: either MAC_NULL, MAC_UNICAST, MAC_MULTICAST, MAC_BROADCAST or MAC_ZERO. They are all threated as unsigned int.

Definition at line 96 of file rawsock.c.

uint64_t ntoh64 ( uint64_t netu64 )

Convert a 64-bit unsigned value between network and host byte order.

This function works like ntohs() and ntohl(), but with 64-bit unsigned integers (i.e. uint64_t).

Note: uint64_t is defined inside stdint.h and inttypes.h.; This function has no direct utility in IPv4/UDP packet management, but it can be used to manage any custom or non-custom 64 bit data field to be sent over the network.

Parameters

[in] netu64 Network byte order integer to be converted into host byte order

Returns: 64-bit unsigned value value converted to host byte order

Definition at line 532 of file rawsock.c.

macaddr_t prepareMacAddrT ( )

Prepare a macaddr_t variable.

Allocates a six element byte array to store any MAC address, using the macaddr_t custom type.

Warning: Every MAC address allocated with this function is initialized to FF:FF:FF:FF:FF:FF.

Returns: It returns the pointer to the allocated MAC address, in the form of a macaddr_t custom type. MAC_NULL is returned if it was not possibile to allocate the required memory.

Definition at line 54 of file rawsock.c.

void rs_printerror	(	FILE *	stream,
		rawsockerr_t	code
	)

Print more detailed error messages.

Given a stream (e.g. stdout or stderr) and the error code, as a rawsockerr_t type, more detailed information is printed on the selected stream.

This function essentialy works like perror(), but instead of describing the current value of errno, it describes what is stored inside code.

It can be useful to print any error that may occur after a call to wlanLookup() or other compatible library functions.

Parameters

[in]	stream	FILE stream to be used to print the requested error (it can be a file, stdout or stderr).
[in]	code	rawsockerr_t integer variable containing the error code (returned by another library function).

Returns: None.

Definition at line 399 of file rawsock.c.

void test_injectIPCsumError ( byte_t * IPpacket )

Test function: inject a checksum error in an IP packet.

This function can be used as a test function to specifically force a checksum error inside an already formed IP packet.

The pointer to the full IP packet shall be passed (IP header+payload).

Parameters

[in] IPpacket Pointer to a byte_t buffer containing the full IP packet.

Returns: None.

Definition at line 1185 of file rawsock.c.

void test_injectUDPCsumError ( byte_t * UDPpacket )

Test function: inject a checksum error in an UDP packet.

This function can be used as a test function to specifically force a checksum error inside an already formed UDP packet.

The pointer to the full UDP packet shall be passed (UDP header+payload - not including neither the Ethernet header nor the IPv4 one)

Parameters

[in] UDPpacket Pointer to a byte_t buffer containing the full UDP packet.

Returns: None.

Definition at line 1211 of file rawsock.c.

size_t UDPencapsulate	(	byte_t *	packet,
		struct udphdr *	header,
		byte_t *	data,
		size_t	payloadsize,
		struct ipaddrs	addrs
	)

Combine UDP payload and header.

This function combines a UDP payload and header, the latter in the form of a struct udphdr Linux structure.

The user shall specify a buffer in which the full packet will be put, the UDP header, the payload (byte_t *data), its size in bytes and a struct ipaddrs containing the source and destination IP addresses. In particular, the latter is needed to properly compute the UDP checksum.

Warning: The packet buffer should be already allocated, and it should be big enough to contain both the header and the payload. It is possible to use the macros defined in rawsock.h, such as UDP_PACKET_SIZE_S(udp_payload_size), to find the required size starting from an higher layer payload size and then call a malloc() with that size to allocate the memory for packet.

Parameters

[out]	packet	Packet buffer (should be already allocated) that will contain the full IPv4 packet (SDU+PCI).
[in]	header	IPv4 header, as struct iphdr. Should be filled in with IP4headPopulate*() before being passed to this function.
[in]	data	Buffer containing the data payload.
[in]	payloadsize	Size, in bytes, of the payload.

Returns: The full packet size (SDU+PCI), in bytes, is returned.

Definition at line 988 of file rawsock.c.

byte_t* UDPgetpacketpointers	(	byte_t *	pktbuf,
		struct ether_header **	etherHeader,
		struct iphdr **	IPheader,
		struct udphdr **	UDPheader
	)

Get pointers to headers and payload in UDP packet buffer.

This function can be used to obtain, given a certain buffer containing a full UDP packet, the pointers to the headers (i.e. to the struct ether_header, struct iphdr and struct udphdr structure respectively) and payload sections

Example of call:

payload=UDPgetpacketpointers(packet,&etherHeader,&IPheader,&udpHeader);

with:

struct ether_header *etherHeader;
struct iphdr *IPheader;
struct udphdr *udpHeader;
byte_t *payload;

If any argument is NULL, no pointer will be returned for that argument.

Note: You can use this function, after receiving a packet, to retrieve header specific data and parse the payload.

Warning: No memory is allocated by this function! It will return pointers inside the original pktbuf buffer, by doing the proper arithmetics.

Parameters

[in]	pktbuf	Packet buffer, containing a full valid UDP packet (the checksum can be wrong, "valid" means here "that is really UDP"), including struct ether_header.
[out]	etherHeader	This pointer will be written by the function, storing the pointer to the ethernet header inside the pktbuf packet buffer; as it is written by the function, a pointer to the pointer shall be passed to UDPgetpacketpointers() (see the example above)
[out]	IPheader	This pointer will be written by the function, storing the pointer to the IPv4 header inside the pktbuf packet buffer.
[out]	UDPheader	This pointer will be written by the function, storing the pointer to the UDP header inside the pktbuf packet buffer.

Returns: The pointer to the payload (of type byte_t) is returned by the function. If pktbuf is a valid pointer, it should never happen that the returned pointer is NULL. If pktbuf is NULL, NULL will be returned.

Definition at line 1034 of file rawsock.c.

unsigned short UDPgetpayloadsize ( struct udphdr * UDPheader )

Get UDP payload size, given a UDP header.

This function can be used to obtain the UDP payload size as unsigned short (int), given a UDP header pointer.

It basically extracts the length field and substracts the standard header length.

Parameters

[in] UDPheader Pointer to a struct udphdr, containing the UDP header.

Returns: It returns the length of the payload stored inside the packet corresponding to the UDP header passed as argument.

Definition at line 1060 of file rawsock.c.

void UDPheadPopulate	(	struct udphdr *	UDPhead,
		unsigned short	sourceport,
		unsigned short	destport
	)

Populate UDP header.

This function can be used to populate a UDP header (struct udphdr).

The user shall specify an already existing UDP header structure, the source port and the destination port.

Warning: This function will initialize the checksum field to 0. A subsequent call to UDPencapsulate(), specifying the payload you want to insert inside the UDP packet, is needed, since the latter is responsible for properly computing the UDP checksum, which, it may be important to recall, takes into account also the header and pseudo-header.

Note: Like all the other functions inside this library, it already takes care of byte ordering.

Parameters

[in,out]	UDPhead	Pointer to the UDP header structure, used in raw sockets.
[in]	sourceport	Source port (16 bit unsigned value)
[in]	destport	Destination port (16 bit unsigned value)

Returns: None.

Definition at line 960 of file rawsock.c.

bool validateEthCsum	(	byte_t *	packet,
		csum16_t	csum,
		csum16_t *	combinedcsum,
		csumt_t	type,
		void *	args
	)

Validate the checksum of a raw "Ethernet" packet, i.e. of any packet containing a struct ether_header as first bytes.

This function can be used to valide the checksum of any Ethernet raw packet, which can be, for instance, received through a raw socket.

A more detailed description is presented below, in the "Parameters" section.

Warning: Additional arguments are nedded, as of now, only when the type is CSUM_UDP or CSUM_UDPIP. In that case, you shall pass a pointer to a size_t variable containing the size of the UDP payload.

Parameters

[in]	packet	Pointer to the full packet buffer for which the checksum has to be validated.
[in]	csum	Checksum value to be checked against the newly computed value, from packet (see also csum16_t)
[in]	combinedcsum	This parameter is a pointer to a checksum value. It should be NULL for non combined checksum types, otherwise it should contain the pointer to the value of the second checksum to be checked (the ordering between csum and _combinedcsum_ is the same as the one in the checksum type constant - for instance: CSUM_UDPIP* requires csum to be related to UDP and _combinedcsum_ to IPv4). If NULL is specified for any combined type, the function will always return false*.
[in]	type	Checksum protocol (see also csum16_t): various protocols can be specified within the same function, in order to keep it easier to be extended as newer protocols will be implemented inside the library. The supported protocols are defined inside proper "Checksum protocols" constants in rawsock.h, starting with CSUM_ (e.g. CSUM_IP). Both simple protocols and combined ones are supported: in the first case, only the checksum related to the specified protocol is checked (csum16_t csum), in the second case, two checksums, contained inside the same packet, are checked (csum16_t csum and csum16_t combinedcsum). This can be useful, for instance, to check both the UDP and IP checksums all at once; in case a combined mode is selected _combinedcsum_ shall be non-NULL, otherwise the function will always return false.
[in]	args	Additional protocol-specific arguments: these are typically dependant on the specified protocol. For instance, using IPv4, they are not needed and NULL can be passed; instead, when using UDP (or UDP+IP), they shall contain the pointer to a single value which is the payload length (this may avoid computing it multiple times, outside and inside this function, when a variable containing it is already available). Everytime an additional argument is needed and it is not passed (i.e. NULL args), the function always returns false.

Returns: Boolean value containing true if the packet contained a valid checksum, false otherwise (or in case of errors).

Definition at line 1099 of file rawsock.c.

rawsockerr_t vifPrinter ( FILE * stream )

Print information about available interfaces.

This function can be used to automatically print some information about the interfaces which are up and available in the system.

The **"Interface internal index"** value can be used as a reference for the index value to be inserted in wlanLookup(), as last argument, when more than one wireless interface is available on the system.

Parameters

[out] stream File stream to print to (a file, stdout or stderr)

Returns

0 if no error occurred, or, in case of error, a rawsockerr_t error:

ERR_VIFPRINTER_SOCK -> cannot create socket to look for available interfaces
ERR_VIFPRINTER_GETIFADDRS -> error in calling getifaddrs()

Definition at line 327 of file rawsock.c.

rawsockerr_t wlanLookup	(	char *	devname,
		int *	ifindex,
		macaddr_t	mac,
		struct in_addr *	srcIP,
		int	index,
		int	mode
	)

Automatically look for available WLAN, non-WLAN or loopback interfaces.

This function can be used to automatically look for available and ready WLAN or non-WLAN (depending on mode) interfaces in the system.

From version 0.2.0 it is also possible to specify WLANLOOKUP_LOOPBACK as index to look for the first available lookback interface, instead of WLAN/non-WLAN ones.

When only one interface is available and 0 is specified as index, that interface name is returned inside devname. Then, if the other three arguments are not NULL, the interface index, the corresponding source MAC address (if available) and the corresponding source IP address (if available) are respectively returned.

If more than one interface is present, the number of available interfaces of the specified type (WLAN/non-WLAN) is returned by the function and index is used to point to a specific interface (for instance index=1 can be used to point to a possible wlan1 interface when mode is WLANLOOKUP_WLAN).

To print the available indeces, the user can use vifPrinter().

Parameters

[out]	devname	Name of the WLAN interface.
[out]	ifindex	Interface index corresponding to devname (filled in only if non-NULL).
[out]	mac	Interface (source) MAC address (filled in only if non-NULL / non-MAC_NULL).
[out]	srcIP	Interface (source) IPv4 address (filled in only if non-NULL and returned inside a struct in_addr, which should be available in the calling module).
[in]	index	Integer index used to point to a specific interface of the specified type (i.e. using the specified mode), when more than one is available (or equal to WLANLOOKUP_LOOPBACK to look for the first available loopback interface).
[in]	mode	Operating mode: WLANLOOKUP_WLAN to look for available WLAN interfaces only, WLANLOOKUP_NONWLAN to look for available non-WLAN/Ethernet interfaces only

Returns

Number of WLAN/non-WLAN interfaces that were found, > 0 , or, in case of error, a rawsockerr_t error:

ERR_WLAN_NOIF -> no interfaces found
ERR_WLAN_SOCK -> cannot create socket to look for available and running interfaces
ERR_WLAN_GETIFADDRS -> error in calling getifaddrs()
ERR_WLAN_INDEX -> invalid index value
ERR_WLAN_GETSRCMAC -> unable to get source MAC address (if requested)
ERR_WLAN_GETIFINDEX -> unable to get source interface index (if requested)
ERR_WLAN_GETSRCMAC -> unable to get source IP address (if requested)

Definition at line 149 of file rawsock.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation