[deliverable/linux.git] / Documentation / networking / mac80211-injection.txt

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 ]

The radiotap format is discussed in
./Documentation/networking/radiotap-headers.txt.

Despite many radiotap parameters being currently defined, most only make sense
to appear on received packets.  The following information is parsed from the
radiotap headers and used to control injection:

 * IEEE80211_RADIOTAP_FLAGS

   IEEE80211_RADIOTAP_F_FCS: FCS will be removed and recalculated
   IEEE80211_RADIOTAP_F_WEP: frame will be encrypted if key available
   IEEE80211_RADIOTAP_F_FRAG: frame will be fragmented if longer than the
			      current fragmentation threshold.

 * IEEE80211_RADIOTAP_TX_FLAGS

   IEEE80211_RADIOTAP_F_TX_NOACK: frame should be sent without waiting for
				  an ACK even if it is a unicast frame

 * IEEE80211_RADIOTAP_RATE

   legacy rate for the transmission (only for devices without own rate control)

 * IEEE80211_RADIOTAP_MCS

   HT rate for the transmission (only for devices without own rate control).
   Also some flags are parsed

   IEEE80211_TX_RC_SHORT_GI: use short guard interval
   IEEE80211_TX_RC_40_MHZ_WIDTH: send in HT40 mode

 * IEEE80211_RADIOTAP_DATA_RETRIES

   number of retries when either IEEE80211_RADIOTAP_RATE or
   IEEE80211_RADIOTAP_MCS was used

The injection code can also skip all other currently defined radiotap fields
facilitating replay of captured radiotap headers directly.

Here is an example valid radiotap header defining some 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 a link to a complete inject application here:

http://wireless.kernel.org/en/users/Documentation/packetspammer

Andy Green <andy@warmcat.com>
Commit	Line	Data
08d1f215 AG	1	How to use packet injection with mac80211
	2	=========================================
	3
	4	mac80211 now allows arbitrary packets to be injected down any Monitor Mode
	5	interface from userland. The packet you inject needs to be composed in the
	6	following format:
	7
	8	[ radiotap header ]
	9	[ ieee80211 header ]
	10	[ payload ]
	11
	12	The radiotap format is discussed in
	13	./Documentation/networking/radiotap-headers.txt.
	14
de2b3e86	15	Despite many radiotap parameters being currently defined, most only make sense
58d4185e JB	16	to appear on received packets. The following information is parsed from the
58d4185e JB	17	radiotap headers and used to control injection:
08d1f215	18
58d4185e JB	19	* IEEE80211_RADIOTAP_FLAGS
	20
	21	IEEE80211_RADIOTAP_F_FCS: FCS will be removed and recalculated
	22	IEEE80211_RADIOTAP_F_WEP: frame will be encrypted if key available
	23	IEEE80211_RADIOTAP_F_FRAG: frame will be fragmented if longer than the
de2b3e86 JB	24	current fragmentation threshold.
de2b3e86 JB	25
d9cd48f9 HS	26	* IEEE80211_RADIOTAP_TX_FLAGS
	27
	28	IEEE80211_RADIOTAP_F_TX_NOACK: frame should be sent without waiting for
	29	an ACK even if it is a unicast frame
58d4185e	30
dfdfc2be SE	31	* IEEE80211_RADIOTAP_RATE
	32
	33	legacy rate for the transmission (only for devices without own rate control)
	34
	35	* IEEE80211_RADIOTAP_MCS
	36
	37	HT rate for the transmission (only for devices without own rate control).
	38	Also some flags are parsed
	39
	40	IEEE80211_TX_RC_SHORT_GI: use short guard interval
	41	IEEE80211_TX_RC_40_MHZ_WIDTH: send in HT40 mode
	42
	43	* IEEE80211_RADIOTAP_DATA_RETRIES
	44
	45	number of retries when either IEEE80211_RADIOTAP_RATE or
	46	IEEE80211_RADIOTAP_MCS was used
	47
58d4185e JB	48	The injection code can also skip all other currently defined radiotap fields
58d4185e JB	49	facilitating replay of captured radiotap headers directly.
08d1f215	50
de2b3e86	51	Here is an example valid radiotap header defining some parameters
08d1f215 AG	52
	53	0x00, 0x00, // <-- radiotap version
	54	0x0b, 0x00, // <- radiotap header length
	55	0x04, 0x0c, 0x00, 0x00, // <-- bitmap
	56	0x6c, // <-- rate
	57	0x0c, //<-- tx power
	58	0x01 //<-- antenna
	59
	60	The ieee80211 header follows immediately afterwards, looking for example like
	61	this:
	62
	63	0x08, 0x01, 0x00, 0x00,
	64	0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
	65	0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
	66	0x13, 0x22, 0x33, 0x44, 0x55, 0x66,
	67	0x10, 0x86
	68
	69	Then lastly there is the payload.
	70
	71	After composing the packet contents, it is sent by send()-ing it to a logical
	72	mac80211 interface that is in Monitor mode. Libpcap can also be used,
	73	(which is easier than doing the work to bind the socket to the right
	74	interface), along the following lines:
	75
	76	ppcap = pcap_open_live(szInterfaceName, 800, 1, 20, szErrbuf);
	77	...
	78	r = pcap_inject(ppcap, u8aSendBuffer, nLength);
	79
de2b3e86	80	You can also find a link to a complete inject application here:
08d1f215	81
de2b3e86	82	http://wireless.kernel.org/en/users/Documentation/packetspammer
08d1f215 AG	83
08d1f215 AG	84	Andy Green <andy@warmcat.com>