mirror of
https://github.com/openwrt/openwrt.git
synced 2024-12-29 10:08:59 +00:00
2e0f41e73a
Cherry-pick Multi-AP commits from uptream: 9c06f0f6a hostapd: Add Multi-AP protocol support 5abc7823b wpa_supplicant: Add Multi-AP backhaul STA support a1debd338 tests: Refactor test_multi_ap bfcdac1c8 Multi-AP: Don't reject backhaul STA on fronthaul BSS cb3c156e7 tests: Update multi_ap_fronthaul_on_ap to match implementation 56a2d788f WPS: Add multi_ap_subelem to wps_build_wfa_ext() 83ebf5586 wpa_supplicant: Support Multi-AP backhaul STA onboarding with WPS 66819b07b hostapd: Support Multi-AP backhaul STA onboarding with WPS 8682f384c hostapd: Add README-MULTI-AP b1daf498a tests: Multi-AP WPS provisioning Add support for Multi-AP to the UCI configuration. Every wifi-iface gets an option 'multi_ap'. For APs, its value can be 0 (multi-AP support disabled), 1 (backhaul AP), 2 (fronthaul AP), or 3 (fronthaul + backhaul AP). For STAs, it can be 0 (not a backhaul STA) or 1 (backhaul STA, can only associate with backhaul AP). Also add new optional parameter to wps_start ubus call of wpa_supplicant to indicate that a Multi-AP backhaul link is required. Signed-off-by: Daniel Golle <daniel@makrotopia.org> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
182 lines
8.8 KiB
Diff
182 lines
8.8 KiB
Diff
From bd733055a22c8ca3bcd7648bf716da2713b3d9f1 Mon Sep 17 00:00:00 2001
|
|
From: "Arnout Vandecappelle (Essensium/Mind)" <arnout@mind.be>
|
|
Date: Mon, 21 Jan 2019 16:44:06 +0100
|
|
Subject: [PATCH] hostapd: add README-MULTI-AP
|
|
|
|
Document what hostapd and wpa_supplicant do for Multi-AP.
|
|
|
|
This is only included in hostapd, since a Multi-AP device is always an
|
|
access point so it should have hostapd.
|
|
|
|
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
|
|
---
|
|
v4: wps_pbc has multi_ap as a parameter instead of config option.
|
|
---
|
|
hostapd/README-MULTI-AP | 160 ++++++++++++++++++++++++++++++++++++++++
|
|
1 file changed, 160 insertions(+)
|
|
create mode 100644 hostapd/README-MULTI-AP
|
|
|
|
--- /dev/null
|
|
+++ b/hostapd/README-MULTI-AP
|
|
@@ -0,0 +1,160 @@
|
|
+hostapd, wpa_supplicant and the Multi-AP Specification
|
|
+======================================================
|
|
+
|
|
+This document describes how hostapd and wpa_supplicant can be configured to
|
|
+support the Multi-AP Specification.
|
|
+
|
|
+Introduction to Multi-AP
|
|
+------------------------
|
|
+
|
|
+The Wi-Fi Alliance Multi-AP Specification is the technical specification for
|
|
+Wi-Fi CERTIFIED EasyMesh(TM) [1], the Wi-Fi Alliance® certification program for
|
|
+Multi-AP. It defines control protocols between Wi-Fi® access points (APs) to
|
|
+join them into a network with centralized control and operation. It is targeted
|
|
+only at routers (repeaters, gateways, ...), not at clients. Clients are not
|
|
+involved at all in the protocols.
|
|
+
|
|
+Most of the Multi-AP specification falls outside of the scope of
|
|
+hostapd/wpa_supplicant. hostapd/wpa_supplicant is only involved for the items
|
|
+summarized below. The rest of the protocol must be implemented by a separate
|
|
+daemon, e.g. prplMesh [2]. That daemon also needs to communicate with hostapd,
|
|
+e.g. to get a list of associated clients, but this can be done using the normal
|
|
+hostapd interfaces.
|
|
+
|
|
+hostapd/wpa_supplicant needs to be configured specifically to support:
|
|
+- the WPS onboarding process;
|
|
+- configuring backhaul links.
|
|
+
|
|
+The text below refers to "Multi-AP Specification v1.0" [3].
|
|
+
|
|
+
|
|
+Fronthaul and backhaul links
|
|
+----------------------------
|
|
+
|
|
+In a Multi-AP network, the central controller can configure the SSIDs on the
|
|
+devices that are joined into the network. These are called fronthaul SSIDs.
|
|
+From the point of view of hostapd, there is nothing special about these
|
|
+fronthaul SSIDs.
|
|
+
|
|
+In addition to fronthaul SSIDs, the controller can also configure backhaul
|
|
+links. A backhaul link is a link between two access point devices, giving
|
|
+internet access to access point devices that don't have a wired link. The
|
|
+Multi-AP specification doesn't dictate this, but typically the backhaul link
|
|
+will be bridged into a LAN together with (one of) the fronthaul SSID(s) and the
|
|
+wired Ethernet ports.
|
|
+
|
|
+A backhaul link must be treated specially by hostapd and wpa_supplicant. One
|
|
+side of the backhaul link is configured through the Multi-AP protocol as the
|
|
+"backhaul STA", i.e. the client side of the link. A backhaul STA is like any
|
|
+station and is handled appropriately by wpa_supplicant, but two additional
|
|
+features are required. It must send an additional information element in each
|
|
+(Re-)Association Request ([3], section 5.2, paragraph 4). In addition, it must
|
|
+use 4-address mode for all frames sent over this link ([3], section 14).
|
|
+Therefore, wpa_supplicant must be configured explicitly as the backhaul STA
|
|
+role, by setting 'multi_ap_backhaul_sta=1' in the network configuration block
|
|
+or when configuring the SSID through the client socket. When
|
|
+'multi_ap_backhaul_sta=1', wpa_supplicant includes the Multi-AP IE in
|
|
+(Re-)Association Request messages and verifies that it is included in the
|
|
+(Re-)Association Response. If it is not, association fails. If it is,
|
|
+wpa_supplicant sets 4-address mode for this interface through a driver
|
|
+callback.
|
|
+
|
|
+The AP side of the backhaul link is called a "backhaul SSID". Such an SSID must
|
|
+be handled specially by hostapd, because it must add an additional information
|
|
+element in each (Re-)Association Response, but only to stations that have
|
|
+identified themselves as backhaul stations ([3], section 5.2, paragraph 5-6).
|
|
+This is important because it is possible to use the same BSS and SSID for
|
|
+fronthaul and backhaul at the same time. The additional information element must
|
|
+only be used for frames sent to a backhaul STA, not to a normal STA. Also,
|
|
+frames sent to a backhaul STA must use 4-address mode, while frames sent to a
|
|
+normal STA (fronthaul, when it's a fronthaul and backhaul SSID) must use
|
|
+3-address mode.
|
|
+
|
|
+An SSID is configured in Multi-AP mode in hostapd by setting the 'multi_ap'
|
|
+configuration option to 1 (backhaul SSID), 2 (fronthaul SSID) or 3
|
|
+(simultaneous backhaul and fronthaul SSID). If this option is set, hostapd
|
|
+parses the Multi-AP information element in the Association Request. If the
|
|
+station is a backhaul STA and the SSID is configured as a backhaul SSID,
|
|
+hostapd sets up 4-address mode. Since there may be multiple stations connected
|
|
+simultaneously, and each of them has a different RA (receiver address), a VLAN
|
|
+is created for each backhaul STA and it is automatically added to a bridge.
|
|
+This is the same behavior as for WDS, and the relevant option ('bridge' or
|
|
+'wds_bridge') applies here as well.
|
|
+
|
|
+If 'multi_ap' is 1 (backhaul SSID only), any station that tries to associate
|
|
+without the Multi-AP information element will be denied.
|
|
+
|
|
+If 'multi_ap' is 2 (fronthaul SSID only), any station that tries to associate
|
|
+with the Multi-AP information element will be denied. That is also the only
|
|
+difference with 'multi_ap' set to 0: in the latter case, the Multi-AP
|
|
+information element is simply ignored.
|
|
+
|
|
+In summary, this is the end-to-end behaviour for a backhaul BSS (i.e.,
|
|
+multi_ap_backhaul_sta=1 in wpa_supplicant on STA, and multi_ap=1 or 3 in
|
|
+hostapd on AP). Note that point 1 means that hostapd must not be configured
|
|
+with WPS support on the backhaul BSS (multi_ap=1). hostapd does not check for
|
|
+that.
|
|
+
|
|
+1. Backhaul BSS beacons do not advertise WPS support (other than that, nothing
|
|
+ multi-ap specific).
|
|
+2. STA sends authentication req (nothing multi-ap specific).
|
|
+3. AP sends authentication resp (nothing multi-ap specific).
|
|
+4. STA sends association req with Multi-AP IE.
|
|
+5. AP send association resp with Multi-AP IE.
|
|
+6. STA and AP both use 4-address mode for data.
|
|
+
|
|
+
|
|
+WPS support
|
|
+-----------
|
|
+
|
|
+WPS requires more special handling. WPS must only be advertised on fronthaul
|
|
+SSIDs, not on backhaul SSIDs, so WPS should not be enabled on a backhaul-only
|
|
+SSID in hostapd.conf. The WPS configuration purely works on the fronthaul SSID.
|
|
+When a WPS M1 message has an additional subelement that indicates a request for
|
|
+a multi-AP backhaul link, hostapd must not respond with the normal fronthaul
|
|
+SSID credentials; instead, it should respond with the (potentially different)
|
|
+backhaul SSID credentials.
|
|
+
|
|
+To support this, hostapd has the 'multi_ap_backhaul_ssid',
|
|
+'multi_ap_backhaul_wpa_psk' and 'multi_ap_backhaul_wpa_passphrase' options.
|
|
+When these are set on an SSID with WPS, they are used instead of the normal
|
|
+credentials when hostapd receives a WPS M1 message with the Multi-AP IE. Only
|
|
+WPA2 Personal is supported in the Multi-AP specification, so there is no need
|
|
+to specify authentication or encryption options. For the backhaul credentials,
|
|
+per-device PSK is not supported.
|
|
+
|
|
+If the SSID is a simultaneous backhaul and fronthaul SSID, there is no need to
|
|
+specify the backhaul credentials, since the backhaul and fronthaul credentials
|
|
+are identical.
|
|
+
|
|
+To enable the Multi-AP backhaul STA feature when it performs WPS, a new
|
|
+parameter has been introduced to the WPS_PBC control interface call.
|
|
+When this option is set, it adds the multi-AP backhaul subelement to
|
|
+the association and M1 messages. It then configures the new SSID with
|
|
+'multi_ap_backhaul_sta=1'. Note that this means that if the AP does not
|
|
+follow the Multi-AP specification, wpa_supplicant will fail to
|
|
+associate.
|
|
+
|
|
+In summary, this is the end-to-end behaviour for WPS of a backhaul link (i.e.,
|
|
+multi_ap=1 option is given in the wps_pbc call on the STA side, and multi_ap=2
|
|
+and multi_ap_backhaul_ssid and either multi_ap_backhaul_wpa_psk or
|
|
+multi_ap_backhaul_wpa_passphrase are set to the credentials of a backhaul SSID
|
|
+in hostapd on registrar AP).
|
|
+
|
|
+1. Fronthaul BSS beacons advertise WPS support (nothing multi-ap specific).
|
|
+2. Enrollee sends authentication req (nothing multi-ap specific).
|
|
+3. AP sends authentication resp (nothing multi-ap specific).
|
|
+4. Enrollee sends association req with Multi-AP IE.
|
|
+5. AP send association resp with Multi-AP IE.
|
|
+6. Enrollee sends M1 with additional Multi-AP subelement
|
|
+7. AP sends M8 with backhaul instead of fronthaul credentials.
|
|
+8. Enrollee sends Deauth.
|
|
+
|
|
+
|
|
+References
|
|
+----------
|
|
+
|
|
+[1] https://www.wi-fi.org/discover-wi-fi/wi-fi-easymesh
|
|
+[2] https://github.com/prplfoundation/prplMesh
|
|
+[3] https://www.wi-fi.org/file/multi-ap-specification-v10
|
|
+ (requires registration)
|