From: Andy Green <[email protected]>
diff --git a/Documentation/networking/mac80211-injection.txt b/Documentation/networking/mac80211-injection.txt
new file mode 100644
index 0000000..bee8931
--- /dev/null
+++ b/Documentation/networking/mac80211-injection.txt
@@ -0,0 +1,77 @@
+How to use packet injection with mac80211
+=========================================
+
+mac80211 now allows arbitrary packets to be injected down any Monitor Mode
+interface from userland. The packet you inject needs to be composed in the
+following format:
+
+ [ radiotap header ]
+ [ ieee80211 header ]
+ [ payload ]
+
+Radiotap headers are variable-length and extensible, you can get most of the
+information you need to know on them from:
+
+./include/net/ieee80211_radiotap.h
+
+But note: all fields in the radiotap header are *little endian*.
+
+There is a fixed portion at the start which contains a u32 bitmap that defines
+if the possible argument is present or not. At the moment there are only 13
+possible arguments defined, but in case we run out of space in the u32 it is
+defined that b31 set indicates that there is another u32 bitmap following, and
+the start of the arguments is moved forward 4 bytes each time.
+
+After the fixed part of the header, the arguments follow.
+
+ - the arguments are all little-endian!
+
+ - the arguments must be aligned to a boundary of the argument size using
+ padding. So a u16 argument must start on the next u16 boundary if it isn't
+ already on one, a u32 must start on the next u32 boundary and so on.
+
+Despite 13 radiotap argument types are currently defined, most only make sense
+to appear on received packets. Currently three kinds of argument are used by
+the injection code, although it knows to skip any other arguments that are
+present (facilitating replay of captured radiotap headers directly):
+
+ - IEEE80211_RADIOTAP_RATE - u8 arg in 500kbps units (0x02 --> 1Mbps)
+
+ - IEEE80211_RADIOTAP_ANTENNA - u8 arg, 0x00 = ant1, 0x01 = ant2
+
+ - IEEE80211_RADIOTAP_DBM_TX_POWER - u8 arg, dBm
+
+Here is an example valid radiotap header defining these three parameters
+
+ 0x00, 0x00, // <-- radiotap version
+ 0x0b, 0x00, // <- radiotap header length
+ 0x04, 0x0c, 0x00, 0x00, // <-- bitmap
+ 0x6c, // <-- rate
+ 0x0c, //<-- tx power
+ 0x01 //<-- antenna
+
+The ieee80211 header follows immediately afterwards, looking for example like
+this:
+
+ 0x08, 0x01, 0x00, 0x00,
+ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+ 0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
+ 0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
+ 0x10, 0x86
+
+Then lastly there is the payload.
+
+After composing the packet contents, it is sent by send()-ing it to a logical
+mac80211 interface that is in Monitor mode. Libpcap can also be used,
+(which is easier than doing the work to bind the socket to the right
+interface), along the following lines:
+
+ ppcap = pcap_open_live(szInterfaceName, 800, 1, 20, szErrbuf);
+...
+ r = pcap_inject(ppcap, u8aSendBuffer, nLength);
+
+You can also find sources for a complete inject test applet here:
+
+http://penumbra.warmcat.com/_twk/tiki-index.php?page=packetspammer
+
+Andy Green <[email protected]>
--
On Tue, 2007-03-20 at 10:39 +0000, [email protected] wrote:
> +++ b/Documentation/networking/mac80211-injection.txt
This needs to be for cfg80211.
> +Radiotap headers are variable-length and extensible, you can get most of the
> +information you need to know on them from:
> +
> +./include/net/ieee80211_radiotap.h
> +
> +But note: all fields in the radiotap header are *little endian*.
> +
> +There is a fixed portion at the start which contains a u32 bitmap that defines
> +if the possible argument is present or not. At the moment there are only 13
> +possible arguments defined, but in case we run out of space in the u32 it is
> +defined that b31 set indicates that there is another u32 bitmap following, and
> +the start of the arguments is moved forward 4 bytes each time.
Drop all that, it's generic radiotap description. Put it into another
file if you want.
> +After the fixed part of the header, the arguments follow.
> +
> + - the arguments are all little-endian!
duplicated information.
> +The ieee80211 header follows immediately afterwards, looking for example like
> +this:
> +
> + 0x08, 0x01, 0x00, 0x00,
> + 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
> + 0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
> + 0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
> + 0x10, 0x86
> +
> +Then lastly there is the payload.
Scratch that, somebody who doesn't know how a IEEE 802.11 header looks
like has no business reading that file anyway ;)
> Libpcap can also be used,
> +(which is easier than doing the work to bind the socket to the right
> +interface), along the following lines:
> +
> + ppcap = pcap_open_live(szInterfaceName, 800, 1, 20, szErrbuf);
> +...
> + r = pcap_inject(ppcap, u8aSendBuffer, nLength);
> +
> +You can also find sources for a complete inject test applet here:
> +
> +http://penumbra.warmcat.com/_twk/tiki-index.php?page=packetspammer
Is it big enough to warrant being elsewhere? I don't see how an example
program can be more than a few lines of code and then it could be
included here as a C file.
johannes
On Thu, 2007-03-29 at 12:18 +0100, Andy Green wrote:
> Well, the actual injection action is happening in mac80211. I think
> you're looking at it as a cfg80211 wext-replacing type thing and I am
> looking at it as completely generic mac80211 packet injection from
> userspace.
Yeah. Don't worry about it. We can move it later and define it for
cfg80211 when we introduce the userspace mlme stuff.
> > Drop all that, it's generic radiotap description. Put it into another
> > file if you want.
>
> This kind of description makes documentation useful to the reader, who
> may never have heard of radiotap (it is not very visible in Google right
> now in a useful way).
Maybe just stick it into a radiotap file and refer to that? I'm just a
bit worried that it'll get outdated because somebody looking for
radiotap stuff won't find it here when updating. Not sure it can even
get outdated though.
> It's ~380 lines. It also knows how to conjure up management interfaces.
> I can chop it down and put it in here if you feel it is important.
It's probably easy enough to write from the docs so probably not really
necessary. I think when I wrote this I was offline so couldn't actually
check out the demo program ;)
> I appreciate the comments, but I am 100% sure that some correct
> documentation that may be over-chatty is better than no documentation at
> all. After hesitating and starting to change it I left it as it is, if
> you still feel these things are important comment in that direction
> again on the new patch and I will grit my teeth and change it.
No, don't take me too seriously. I appreciate documentation I may not
agree with in all points much more than the lack thereof :)
johannes
Johannes Berg wrote:
> On Tue, 2007-03-20 at 10:39 +0000, [email protected] wrote:
>
>> +++ b/Documentation/networking/mac80211-injection.txt
>
> This needs to be for cfg80211.
Well, the actual injection action is happening in mac80211. I think
you're looking at it as a cfg80211 wext-replacing type thing and I am
looking at it as completely generic mac80211 packet injection from
userspace.
>> +Radiotap headers are variable-length and extensible, you can get most of the
>> +information you need to know on them from:
>> +
>> +./include/net/ieee80211_radiotap.h
>> +
>> +But note: all fields in the radiotap header are *little endian*.
>> +
>> +There is a fixed portion at the start which contains a u32 bitmap that defines
>> +if the possible argument is present or not. At the moment there are only 13
>> +possible arguments defined, but in case we run out of space in the u32 it is
>> +defined that b31 set indicates that there is another u32 bitmap following, and
>> +the start of the arguments is moved forward 4 bytes each time.
>
> Drop all that, it's generic radiotap description. Put it into another
> file if you want.
This kind of description makes documentation useful to the reader, who
may never have heard of radiotap (it is not very visible in Google right
now in a useful way).
>> +After the fixed part of the header, the arguments follow.
>> +
>> + - the arguments are all little-endian!
>
> duplicated information.
Yes when documenting something, you duplicate critical information, it
is not an error but a static Forward Error Correction technology for
lossy readers.
>> +The ieee80211 header follows immediately afterwards, looking for example like
>> +this:
>> +
>> + 0x08, 0x01, 0x00, 0x00,
>> + 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
>> + 0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
>> + 0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
>> + 0x10, 0x86
>> +
>> +Then lastly there is the payload.
>
> Scratch that, somebody who doesn't know how a IEEE 802.11 header looks
> like has no business reading that file anyway ;)
Everybody has to learn from nothing!
>> Libpcap can also be used,
>> +(which is easier than doing the work to bind the socket to the right
>> +interface), along the following lines:
>> +
>> + ppcap = pcap_open_live(szInterfaceName, 800, 1, 20, szErrbuf);
>> +...
>> + r = pcap_inject(ppcap, u8aSendBuffer, nLength);
>> +
>> +You can also find sources for a complete inject test applet here:
>> +
>> +http://penumbra.warmcat.com/_twk/tiki-index.php?page=packetspammer
>
> Is it big enough to warrant being elsewhere? I don't see how an example
> program can be more than a few lines of code and then it could be
> included here as a C file.
It's ~380 lines. It also knows how to conjure up management interfaces.
I can chop it down and put it in here if you feel it is important.
I appreciate the comments, but I am 100% sure that some correct
documentation that may be over-chatty is better than no documentation at
all. After hesitating and starting to change it I left it as it is, if
you still feel these things are important comment in that direction
again on the new patch and I will grit my teeth and change it.
-Andy