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