Documentation/networking/mac80211-injection.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================================
   4 How to use packet injection with mac80211
   5 =========================================
   6
   7 mac80211 now allows arbitrary packets to be injected down any Monitor Mode
   8 interface from userland.  The packet you inject needs to be composed in the
   9 following format::
  10
  11  [ radiotap header  ]
  12  [ ieee80211 header ]
  13  [ payload ]
  14
  15 The radiotap format is discussed in
  16 ./Documentation/networking/radiotap-headers.rst.
  17
  18 Despite many radiotap parameters being currently defined, most only make sense
  19 to appear on received packets.  The following information is parsed from the
  20 radiotap 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
  70 The injection code can also skip all other currently defined radiotap fields
  71 facilitating replay of captured radiotap headers directly.
  72
  73 Here 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
  82 The ieee80211 header follows immediately afterwards, looking for example like
  83 this::
  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
  91 Then lastly there is the payload.
  92
  93 After composing the packet contents, it is sent by send()-ing it to a logical
  94 mac80211 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
  96 interface), along the following lines:::
  97
  98         ppcap = pcap_open_live(szInterfaceName, 800, 1, 20, szErrbuf);
  99         ...
 100         r = pcap_inject(ppcap, u8aSendBuffer, nLength);
 101
 102 You can also find a link to a complete inject application here:
 103
 104 https://wireless.wiki.kernel.org/en/users/Documentation/packetspammer
 105
 106 Andy Green <andy@warmcat.com>