hostapd/README-MULTI-AP

   1 hostapd, wpa_supplicant and the Multi-AP Specification
   2 ======================================================
   3
   4 This document describes how hostapd and wpa_supplicant can be configured to
   5 support the Multi-AP Specification.
   6
   7 Introduction to Multi-AP
   8 ------------------------
   9
  10 The Wi-Fi Alliance Multi-AP Specification is the technical specification for
  11 Wi-Fi CERTIFIED EasyMesh(TM) [1], the Wi-Fi Alliance® certification program for
  12 Multi-AP. It defines control protocols between Wi-Fi® access points (APs) to
  13 join them into a network with centralized control and operation. It is targeted
  14 only at routers (repeaters, gateways, ...), not at clients. Clients are not
  15 involved at all in the protocols.
  16
  17 Most of the Multi-AP specification falls outside of the scope of
  18 hostapd/wpa_supplicant. hostapd/wpa_supplicant is only involved for the items
  19 summarized below. The rest of the protocol must be implemented by a separate
  20 daemon, e.g., prplMesh [2]. That daemon also needs to communicate with hostapd,
  21 e.g., to get a list of associated clients, but this can be done using the normal
  22 hostapd interfaces.
  23
  24 hostapd/wpa_supplicant needs to be configured specifically to support:
  25 - the WPS onboarding process;
  26 - configuring backhaul links.
  27
  28 The text below refers to "Multi-AP Specification v1.0" [3].
  29
  30
  31 Fronthaul and backhaul links
  32 ----------------------------
  33
  34 In a Multi-AP network, the central controller can configure the BSSs on the
  35 devices that are joined into the network. These are called fronthaul BSSs.
  36 From the point of view of hostapd, there is nothing special about these
  37 fronthaul BSSs.
  38
  39 In addition to fronthaul BSSs, the controller can also configure backhaul
  40 links. A backhaul link is a link between two access point devices, giving
  41 internet access to access point devices that don't have a wired link. The
  42 Multi-AP specification doesn't dictate this, but typically the backhaul link
  43 will be bridged into a LAN together with (one of) the fronthaul BSS(s) and the
  44 wired Ethernet ports.
  45
  46 A backhaul link must be treated specially by hostapd and wpa_supplicant. One
  47 side of the backhaul link is configured through the Multi-AP protocol as the
  48 "backhaul STA", i.e., the client side of the link. A backhaul STA is like any
  49 station and is handled appropriately by wpa_supplicant, but two additional
  50 features are required. It must send an additional information element in each
  51 (Re)Association Request frame ([3], section 5.2, paragraph 4). In addition, it
  52 must use 4-address mode for all frames sent over this link ([3], section 14).
  53 Therefore, wpa_supplicant must be configured explicitly as the backhaul STA
  54 role, by setting 'multi_ap_backhaul_sta=1' in the network configuration block
  55 or when configuring the network profile through the control interface. When
  56 'multi_ap_backhaul_sta=1', wpa_supplicant includes the Multi-AP IE in
  57 (Re)Association Request frame and verifies that it is included in the
  58 (Re)Association Response frame. If it is not, association fails. If it is,
  59 wpa_supplicant sets 4-address mode for this interface through a driver
  60 callback.
  61
  62 The AP side of the backhaul link is called a "backhaul BSS". Such a BSS must
  63 be handled specially by hostapd, because it must add an additional information
  64 element in each (Re)Association Response frame, but only to stations that have
  65 identified themselves as backhaul stations ([3], section 5.2, paragraph 5-6).
  66 This is important because it is possible to use the same BSS and SSID for
  67 fronthaul and backhaul at the same time. The additional information element must
  68 only be used for frames sent to a backhaul STA, not to a normal STA. Also,
  69 frames sent to a backhaul STA must use 4-address mode, while frames sent to a
  70 normal STA (fronthaul, when it's a fronthaul and backhaul BSS) must use
  71 3-address mode.
  72
  73 A BSS is configured in Multi-AP mode in hostapd by setting the 'multi_ap'
  74 configuration option to 1 (backhaul BSS), 2 (fronthaul BSS), or 3
  75 (simultaneous backhaul and fronthaul BSS). If this option is set, hostapd
  76 parses the Multi-AP information element in the Association Request frame. If the
  77 station is a backhaul STA and the BSS is configured as a backhaul BSS,
  78 hostapd sets up 4-address mode. Since there may be multiple stations connected
  79 simultaneously, and each of them has a different RA (receiver address), a VLAN
  80 is created for each backhaul STA and it is automatically added to a bridge.
  81 This is the same behavior as for WDS, and the relevant option ('bridge' or
  82 'wds_bridge') applies here as well.
  83
  84 If 'multi_ap' is 1 (backhaul BSS only), any station that tries to associate
  85 without the Multi-AP information element will be denied.
  86
  87 If 'multi_ap' is 2 (fronthaul BSS only), any station that tries to associate
  88 with the Multi-AP information element will be denied. That is also the only
  89 difference with 'multi_ap' set to 0: in the latter case, the Multi-AP
  90 information element is simply ignored.
  91
  92 In summary, this is the end-to-end behavior for a backhaul BSS (i.e.,
  93 multi_ap_backhaul_sta=1 in wpa_supplicant on STA, and multi_ap=1 or 3 in
  94 hostapd on AP). Note that point 1 means that hostapd must not be configured
  95 with WPS support on the backhaul BSS (multi_ap=1). hostapd does not check for
  96 that.
  97
  98 1. Backhaul BSS beacons do not advertise WPS support (other than that, nothing
  99    Multi-AP specific).
 100 2. STA sends Authentication frame (nothing Multi-AP specific).
 101 3. AP sends Authentication frame (nothing Multi-AP specific).
 102 4. STA sends Association Request frame with Multi-AP IE.
 103 5. AP sends Association Response frame with Multi-AP IE.
 104 6. STA and AP both use 4-address mode for Data frames.
 105
 106
 107 WPS support
 108 -----------
 109
 110 WPS requires more special handling. WPS must only be advertised on fronthaul
 111 BSSs, not on backhaul BSSs, so WPS should not be enabled on a backhaul-only
 112 BSS in hostapd.conf. The WPS configuration purely works on the fronthaul BSS.
 113 When a WPS M1 message has an additional subelement that indicates a request for
 114 a Multi-AP backhaul link, hostapd must not respond with the normal fronthaul
 115 BSS credentials; instead, it should respond with the (potentially different)
 116 backhaul BSS credentials.
 117
 118 To support this, hostapd has the 'multi_ap_backhaul_ssid',
 119 'multi_ap_backhaul_wpa_psk' and 'multi_ap_backhaul_wpa_passphrase' options.
 120 When these are set on an BSS with WPS, they are used instead of the normal
 121 credentials when hostapd receives a WPS M1 message with the Multi-AP IE. Only
 122 WPA2-Personal is supported in the Multi-AP specification, so there is no need
 123 to specify authentication or encryption options. For the backhaul credentials,
 124 per-device PSK is not supported.
 125
 126 If the BSS is a simultaneous backhaul and fronthaul BSS, there is no need to
 127 specify the backhaul credentials, since the backhaul and fronthaul credentials
 128 are identical.
 129
 130 To enable the Multi-AP backhaul STA feature when it performs WPS, a new
 131 parameter has been introduced to the WPS_PBC control interface call. When this
 132 "multi_ap=1" option is set, it adds the Multi-AP backhaul subelement to the
 133 Association Request frame and the M1 message. It then configures the new network
 134 profile with 'multi_ap_backhaul_sta=1'. Note that this means that if the AP does
 135 not follow the Multi-AP specification, wpa_supplicant will fail to associate.
 136
 137 In summary, this is the end-to-end behavior for WPS of a backhaul link (i.e.,
 138 multi_ap=1 option is given in the wps_pbc call on the STA side, and multi_ap=2
 139 and multi_ap_backhaul_ssid and either multi_ap_backhaul_wpa_psk or
 140 multi_ap_backhaul_wpa_passphrase are set to the credentials of a backhaul BSS
 141 in hostapd on Registrar AP).
 142
 143 1. Fronthaul BSS Beacon frames advertise WPS support (nothing Multi-AP
 144    specific).
 145 2. Enrollee sends Authentication frame (nothing Multi-AP specific).
 146 3. AP sends Authentication frame (nothing Multi-AP specific).
 147 4. Enrollee sends Association Request frame with Multi-AP IE.
 148 5. AP sends Association Response frame with Multi-AP IE.
 149 6. Enrollee sends M1 with additional Multi-AP subelement.
 150 7. AP sends M8 with backhaul instead of fronthaul credentials.
 151 8. Enrollee sends Deauthentication frame.
 152
 153
 154 References
 155 ----------
 156
 157 [1] https://www.wi-fi.org/discover-wi-fi/wi-fi-easymesh
 158 [2] https://github.com/prplfoundation/prplMesh
 159 [3] https://www.wi-fi.org/file/multi-ap-specification-v10
 160     (requires registration)