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