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