Sending raw Ethernet frames in 6 easy steps

Part of my work entails building a protocol stack in C that lives alongside TCP/IP and which is constructed entirely in user space, save for a few standard system calls. Hence, I need the ability to craft raw Ethernet frames and send them using only the facilities the operating system provides.

Fortunately, I have two things going for me. First, the implementation is all being done under Linux (in particular, a 2.6.32 kernel, though I believe any 2.6.x kernel will do). Second, a few other authors have gone before me in deciphering the man pages and system calls and have put together some great example codes. Most notably, Andreas Schaufler, whose writeup inspired my implementation as well as the code in this post.

So why write more on the subject? Because it takes time to understand all the moving parts and pieces, and most of us are operating under deadlines. What I hope to contribute is a one-stop, soup-to-nuts explanation with example code to save time for the next person. I'm going to assume you are somewhat comfortable with the C programming language and have seen or done some network programming before. However, my goal is to make this as painless as possible.

Starting point

First, let's try to make things easy for whomever is using this code. If they want to send a raw Ethernet frame, what things can we reasonably ask them to provide?

• The destination MAC address would be nice, for sure. If they only know the IP, you can either have them look up the MAC with the arp command or code that lookup into your software. Let's assume you've done this if needed.
• Since the frame needs to go out some particular Ethernet interface, we'll assume they know this already and can specify it by its "friendly" name, e.g., "eth0". The source MAC is needed as well, but we can look that up from the interface, assuming they're not trying to fake it. If they are, I will point out where to do this.
• An Ethernet protocol number would also be good to know. This is the value that tells the receiving system which protocol is contained inside the frame. IP uses 0x0800, but perhaps you, like me, want to craft your own protocol that isn't processed by the TCP/IP stack.
• Finally, the bytes you want to put into the message. This part is entirely up to you. Maybe you want to inject the contents of a captured packet, or some payload of your own creation. All we care about is that the bytes are stored somewhere (we'll say a C byte or "char" array) and you know the number of bytes to be sent. (We'll also assume you're staying within the number of bytes that fit in a frame, a.k.a. the Maximum Transmission Unit or MTU.)

Given these four pieces of information, let's walk through the code to send a frame. It will take six steps, listed below. Depending on your starting point, you may omit some of these steps.

1. Defining our input and output data
2. Building a raw "packet" socket
3. Looking up the interface index and MAC address
4. Filling in the packet contents
5. Filling in the link layer socket address structure
6. Sending the packet

Defining data

We need to define variables for the information described above, plus the actual frame format. Here I give hard-coded definitions to demonstrate what kind of data the rest of the code expects:

  char *iface = "eth0";
  unsigned char dest[]
           = { 0x00, 0x12, 0x34, 0x56, 0x78, 0x90 };
  unsigned short proto = 0x1234;
  unsigned char data[] = "hello world";
  unsigned short data_len = strlen(data);

As described above, the interface is given by its friendly name. We will derive all other necessary information about the interface inside this code. Destination is specified as a MAC address; the byte array dest corresponds to the address 00:12:34:56:78:90. The protocol field is 16 bits; we will come back to this shortly (haha, it's a pun! ... *ahem* okay, moving right along...). The frame data payload is whatever you want it to be, but eventually it will end up as a byte array also, so we'll assume you've already serialized your data somehow.

For your application, these values might be hand-jammed, come from command line arguments, or from another part of your program. And not to get parental, but don't forget to add sanity checks to all these inputs unless you really, really trust them!

At the end of the day, all these variables have to be crunched together as a byte array, because that's what the sending function will expect. One important difference from using "normal" sockets is that we have to specify the entire frame, including headers. The only things done for us (by hardware) are the preamble and CRC (error-checking). Let's create a data structure to make this easier later:

  union ethframe
  {
    struct
    {
      struct ethhdr    header;
      unsigned char    data[1500];
    } field;
    unsigned char    buffer[1514];
  };

The structs break out the components of the frame (struct ethhdr is provided in the include file <linux/if_ether.h>), and the union lets us treat the data as either separate fields or a single byte array. I won't go into the details of the Ethernet frame format; for our purposes, the "basic" frame consists of three header fields (source, destination, and protocol) and data. The protocol field is simply an unsigned short integer (two bytes) in network byte order. Source and destination are both MAC addresses, which are six bytes each. The overall frame length is limited to 1514 bytes, meaning the maximum data length is 1500 bytes (1514 - 2 - 6 - 6).

Wow, a lot of numbers to remember, right? The include file <linux/if_ether.h> defines all these and more as constants, so we don't have to remember them. Instead, we can define our structure like this:

  union ethframe
  {
    struct
    {
      struct ethhdr    header;
      unsigned char    data[ETH_DATA_LEN];
    } field;
    unsigned char    buffer[ETH_FRAME_LEN];
  };

Building the socket

Next we need to build the socket we will use to send our frame. We are doing this early in the code because we also need the socket to look up the index and MAC address of the interface (this will be explained below).

  int s;

  s = socket(AF_PACKET, SOCK_RAW, htons(proto));

If you are not familiar with creating network sockets, this is roughly the networking equivalent of opening a file to read or write. What makes this instance unusual are the particular arguments supplied. For TCP and UDP sockets, the first argument is normally AF_INET (address family Internet), and the second argument is normally SOCK_DGRAM for UDP datagrams and SOCK_STREAM for TCP streams. The combination of AF_PACKET and SOCK_RAW tells the operating system to create a socket beneath the level of the entire TCP/IP stack. Now is probably a good time to point out that in general, only the superuser (root) can do this. The third argument is the protocol field, converted to network byte order by htons (host-to-network-short). The only header needed for this part should be <sys/socket.h>, though some systems may require <netinet/in.h> for htons.

Assuming all went well, s is now set to a socket descriptor (value > 0). If its value is less than zero, an error occurred, possibly due to permissions. 

Looking up interface properties

The user has provided us with an interface name, maybe "eth0". But there is no Linux command to send packets from eth0; we have to look up an internal number used to identify the interface, referred to as the interface index. Since the user did not supply us with a source MAC address, we will also look this up.

Okay, this might be the least straightforward step, and I'm going to ask you to hit the "I Believe" button a bit here. Linux has an interface to many underlying system properties, called ioctl (Input-Output-Control). The inner workings of ioctl are by many considered to be dark and scary, but I will walk you through how to use it without dragging you through how it works.

Here is the code for looking up the interface index:

  struct ifreq buffer;

  int ifindex;

  memset(&buffer, 0x00, sizeof(buffer));

  strncpy(buffer.ifr_name, iface, IFNAMSIZ);

  ioctl(s, SIOCGIFINDEX, &buffer);

  ifindex = buffer.ifr_ifindex;

Briefly, ioctl is capable of querying properties of network interfaces and storing them in a buffer we supply as an argument. The include file <linux/if.h> provides a giant struct, ifreq, used for specifying these queries and storing the results. We first need to (well, ought to) zero out the contents of our struct and load it with the friendly name of the interface (memset and strncpy, respectively). The constant IFNAMSIZ defines the maximum length of friendly interface names for the operating system. We then invoke ioctl on an open socket (as far as I know, it doesn't matter what kind of open socket) with a constant specifying what property we want, and ioctl will load the struct with the corresponding result, which we store into ifindex.

Likewise, we can look up the source MAC address this way:

  unsigned char source[ETH_ALEN];

  ioctl(s, SIOCGIFHWADDR, &buffer)

  memcpy((void*)source, (void*)(buffer.ifr_hwaddr.sa_data), 

         ETH_ALEN);

I've skipped a couple key details about how ioctl and ifreq structs work. Make sure you copy the results of each ioctl before invoking it again, as previous results may get overwritten. Like socket, ioctl returns < 0 on error. There are many other interface properties that you can look up as well, including the MTU (SIOCGIFMTU) and timestamp of the last packet received on that specific socket (SIOCGSTAMP). See <bits/ioctls.h> and <sys/socket.h> for more.

Filling in the packet fields

We're in the home stretch! Just some data structures to populate and it's time to fire this packet off! Let's go ahead and fill in the packet fields next.

  union ethframe frame;

  memcpy(frame.field.header.h_dest, dest, ETH_ALEN);

  memcpy(frame.field.header.h_source, source, ETH_ALEN);

  frame.field.header.h_proto = htons(proto);

  memcpy(frame.field.data, data, data_len);

We'll create an instance of the union we defined earlier, but initially treat it as the internal struct so we can set fields individually without worrying about typecasting. Struct ethhdr defines the standard three-field Ethernet header, with an "h_" preceding the field names. Since the addresses are byte arrays, we use memset to copy them. Again, proto must be converted to network byte order (unless you did this earlier and stored it for later use... but that would be WAY too efficient for our sensibilities, right?). As for the payload data, we'll assume that everything fits within the allocated space, but a quick check that data_len < ETH_DATA_LEN wouldn't hurt either.

Filling in the sockaddr_ll struct

This should be a familiar step for anyone who has used the sendto system call. But wait, there's a twist! What is this _ll on the end? As it turns out, there is a variant of the sockaddr struct just for packet sockets. This is where ifindex comes in handy.

  struct sockaddr_ll saddrll;

  memset((void*)&saddrll, 0, sizeof(saddrll));

  saddrll.sll_family = PF_PACKET;   

  saddrll.sll_ifindex = ifindex;

  saddrll.sll_halen = ETH_ALEN;

  memcpy((void*)(saddrll.sll_addr), (void*)dest, ETH_ALEN);

 
Struct sockaddr_ll is defined in <linux/if_packet.h>. It contains roughly half a dozen fields, but we only need to worry about four of them, of which two are gimmes. Just to be safe, we start by zeroing it out. sll_family is simply a repetition that yes, this is in fact a packet socket. sll_halen confirms that Ethernet addresses are ETH_ALEN (i.e., 6) bytes long. Fields sll_ifindex and sll_addr specify the sending interface and destination address, respectively. (I'm not entirely clear why the destination address is both specified here and manually put into the Ethernet frame, but I suspect it is clear in the kernel code.) You'll notice the (void*) typecasting here; often these are not needed, but once in a while, depending on the type given to the struct fields, it gets rid of a compiler warning.

Sending the packet!

Congratulations! You have successfully created a raw socket, looked up properties of a network interface, filled in data structures, and you're all set to fire off your very own, customized Ethernet frame. Only one line of code stands between you and victory! So, let's have it:

  sendto(s, frame.buffer, frame_len, 0,

         (struct sockaddr*)&saddrll, sizeof(saddrll));

 
This is the same as a sendto for UDP or raw IP. Briefly, it takes as arguments the packet socket descriptor, the byte array containing the entire frame (headers included), length of the frame (data_len + ETH_HLEN), flags (if any), a pointer to the sockaddr_ll struct, and the size of the struct. It returns the number of bytes sent, or < 0 if an error occurred.

And that's it! A quick check with a packet analyzer like Wireshark can confirm that frames are making their way out of the operating system. After that, it's all up to the hardware.

Receiving packets is very similar; the socket is created the same way, and recvfrom populates a sockaddr_ll struct and a buffer containing the entire frame. One note: when sending very short frames, don't be surprised when the received frame appears to be longer than the sent frame. Ethernet defines a minimum payload length and will zero-pad the frame if needed. However, the length returned by recvfrom refers only to the legitimate data.

Included below is the full code along with minimal error-checking. Until next time, don't forget that it's all just bits!

The code, front to back (download ethersend.c)

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <sys/socket.h>    /* Must precede if*.h */

#include <linux/if.h>

#include <linux/if_ether.h>

#include <linux/if_packet.h>

#include <sys/ioctl.h>

union ethframe

{

  struct

  {

    struct ethhdr    header;

    unsigned char    data[ETH_DATA_LEN];

  } field;

  unsigned char    buffer[ETH_FRAME_LEN];

};

int main(int argc, char **argv) {

  char *iface = "eth0";

  unsigned char dest[ETH_ALEN]

           = { 0x00, 0x12, 0x34, 0x56, 0x78, 0x90 };

  unsigned short proto = 0x1234;

  unsigned char *data = "hello world";

  unsigned short data_len = strlen(data);

 

  int s;

  if ((s = socket(AF_PACKET, SOCK_RAW, htons(proto))) < 0) {

    printf("Error: could not open socket\n");

    return -1;

  }

 

  struct ifreq buffer;

  int ifindex;

  memset(&buffer, 0x00, sizeof(buffer));

  strncpy(buffer.ifr_name, iface, IFNAMSIZ);

  if (ioctl(s, SIOCGIFINDEX, &buffer) < 0) {

    printf("Error: could not get interface index\n");

    close(s);

    return -1;

  }

  ifindex = buffer.ifr_ifindex;

 

  unsigned char source[ETH_ALEN];

  if (ioctl(s, SIOCGIFHWADDR, &buffer) < 0) {

    printf("Error: could not get interface address\n");

    close(s);

    return -1;

  }

  memcpy((void*)source, (void*)(buffer.ifr_hwaddr.sa_data),
         ETH_ALEN);

 

  union ethframe frame;

  memcpy(frame.field.header.h_dest, dest, ETH_ALEN);

  memcpy(frame.field.header.h_source, source, ETH_ALEN);

  frame.field.header.h_proto = htons(proto);

  memcpy(frame.field.data, data, data_len);

 

  unsigned int frame_len = data_len + ETH_HLEN;

 

  struct sockaddr_ll saddrll;

  memset((void*)&saddrll, 0, sizeof(saddrll));

  saddrll.sll_family = PF_PACKET;   

  saddrll.sll_ifindex = ifindex;

  saddrll.sll_halen = ETH_ALEN;

  memcpy((void*)(saddrll.sll_addr), (void*)dest, ETH_ALEN);

 

  if (sendto(s, frame.buffer, frame_len, 0,

             (struct sockaddr*)&saddrll, sizeof(saddrll)) > 0)

    printf("Success!\n");

  else

    printf("Error, could not send\n");

 

  close(s);

 

  return 0;

}