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