]>
Commit | Line | Data |
---|---|---|
8682f384 AVEM |
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) |