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) 161
