package/network/services/hostapd/patches/558-hostapd-add-README-MULTI-AP.patch

   1 From bd733055a22c8ca3bcd7648bf716da2713b3d9f1 Mon Sep 17 00:00:00 2001
   2 From: "Arnout Vandecappelle (Essensium/Mind)" <arnout@mind.be>
   3 Date: Mon, 21 Jan 2019 16:44:06 +0100
   4 Subject: [PATCH] hostapd: add README-MULTI-AP
   5
   6 Document what hostapd and wpa_supplicant do for Multi-AP.
   7
   8 This is only included in hostapd, since a Multi-AP device is always an
   9 access point so it should have hostapd.
  10
  11 Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
  12 ---
  13 v4: wps_pbc has multi_ap as a parameter instead of config option.
  14 ---
  15  hostapd/README-MULTI-AP | 160 ++++++++++++++++++++++++++++++++++++++++
  16  1 file changed, 160 insertions(+)
  17  create mode 100644 hostapd/README-MULTI-AP
  18
  19 --- /dev/null
  20 +++ b/hostapd/README-MULTI-AP
  21 @@ -0,0 +1,160 @@
  22 +hostapd, wpa_supplicant and the Multi-AP Specification
  23 +======================================================
  24 +
  25 +This document describes how hostapd and wpa_supplicant can be configured to
  26 +support the Multi-AP Specification.
  27 +
  28 +Introduction to Multi-AP
  29 +------------------------
  30 +
  31 +The Wi-Fi Alliance Multi-AP Specification is the technical specification for
  32 +Wi-Fi CERTIFIED EasyMesh(TM) [1], the Wi-Fi Alliance® certification program for
  33 +Multi-AP. It defines control protocols between Wi-Fi® access points (APs) to
  34 +join them into a network with centralized control and operation. It is targeted
  35 +only at routers (repeaters, gateways, ...), not at clients. Clients are not
  36 +involved at all in the protocols.
  37 +
  38 +Most of the Multi-AP specification falls outside of the scope of
  39 +hostapd/wpa_supplicant. hostapd/wpa_supplicant is only involved for the items
  40 +summarized below. The rest of the protocol must be implemented by a separate
  41 +daemon, e.g. prplMesh [2]. That daemon also needs to communicate with hostapd,
  42 +e.g. to get a list of associated clients, but this can be done using the normal
  43 +hostapd interfaces.
  44 +
  45 +hostapd/wpa_supplicant needs to be configured specifically to support:
  46 +- the WPS onboarding process;
  47 +- configuring backhaul links.
  48 +
  49 +The text below refers to "Multi-AP Specification v1.0" [3].
  50 +
  51 +
  52 +Fronthaul and backhaul links
  53 +----------------------------
  54 +
  55 +In a Multi-AP network, the central controller can configure the SSIDs on the
  56 +devices that are joined into the network. These are called fronthaul SSIDs.
  57 +From the point of view of hostapd, there is nothing special about these
  58 +fronthaul SSIDs.
  59 +
  60 +In addition to fronthaul SSIDs, the controller can also configure backhaul
  61 +links. A backhaul link is a link between two access point devices, giving
  62 +internet access to access point devices that don't have a wired link. The
  63 +Multi-AP specification doesn't dictate this, but typically the backhaul link
  64 +will be bridged into a LAN together with (one of) the fronthaul SSID(s) and the
  65 +wired Ethernet ports.
  66 +
  67 +A backhaul link must be treated specially by hostapd and wpa_supplicant. One
  68 +side of the backhaul link is configured through the Multi-AP protocol as the
  69 +"backhaul STA", i.e. the client side of the link. A backhaul STA is like any
  70 +station and is handled appropriately by wpa_supplicant, but two additional
  71 +features are required. It must send an additional information element in each
  72 +(Re-)Association Request ([3], section 5.2, paragraph 4). In addition, it must
  73 +use 4-address mode for all frames sent over this link ([3], section 14).
  74 +Therefore, wpa_supplicant must be configured explicitly as the backhaul STA
  75 +role, by setting 'multi_ap_backhaul_sta=1' in the network configuration block
  76 +or when configuring the SSID through the client socket. When
  77 +'multi_ap_backhaul_sta=1', wpa_supplicant includes the Multi-AP IE in
  78 +(Re-)Association Request messages and verifies that it is included in the
  79 +(Re-)Association Response. If it is not, association fails. If it is,
  80 +wpa_supplicant sets 4-address mode for this interface through a driver
  81 +callback.
  82 +
  83 +The AP side of the backhaul link is called a "backhaul SSID". Such an SSID must
  84 +be handled specially by hostapd, because it must add an additional information
  85 +element in each (Re-)Association Response, but only to stations that have
  86 +identified themselves as backhaul stations ([3], section 5.2, paragraph 5-6).
  87 +This is important because it is possible to use the same BSS and SSID for
  88 +fronthaul and backhaul at the same time. The additional information element must
  89 +only be used for frames sent to a backhaul STA, not to a normal STA. Also,
  90 +frames sent to a backhaul STA must use 4-address mode, while frames sent to a
  91 +normal STA (fronthaul, when it's a fronthaul and backhaul SSID) must use
  92 +3-address mode.
  93 +
  94 +An SSID is configured in Multi-AP mode in hostapd by setting the 'multi_ap'
  95 +configuration option to 1 (backhaul SSID), 2 (fronthaul SSID) or 3
  96 +(simultaneous backhaul and fronthaul SSID). If this option is set, hostapd
  97 +parses the Multi-AP information element in the Association Request. If the
  98 +station is a backhaul STA and the SSID is configured as a backhaul SSID,
  99 +hostapd sets up 4-address mode. Since there may be multiple stations connected
 100 +simultaneously, and each of them has a different RA (receiver address), a VLAN
 101 +is created for each backhaul STA and it is automatically added to a bridge.
 102 +This is the same behavior as for WDS, and the relevant option ('bridge' or
 103 +'wds_bridge') applies here as well.
 104 +
 105 +If 'multi_ap' is 1 (backhaul SSID only), any station that tries to associate
 106 +without the Multi-AP information element will be denied.
 107 +
 108 +If 'multi_ap' is 2 (fronthaul SSID only), any station that tries to associate
 109 +with the Multi-AP information element will be denied. That is also the only
 110 +difference with 'multi_ap' set to 0: in the latter case, the Multi-AP
 111 +information element is simply ignored.
 112 +
 113 +In summary, this is the end-to-end behaviour for a backhaul BSS (i.e.,
 114 +multi_ap_backhaul_sta=1 in wpa_supplicant on STA, and multi_ap=1 or 3 in
 115 +hostapd on AP). Note that point 1 means that hostapd must not be configured
 116 +with WPS support on the backhaul BSS (multi_ap=1). hostapd does not check for
 117 +that.
 118 +
 119 +1. Backhaul BSS beacons do not advertise WPS support (other than that, nothing
 120 +   multi-ap specific).
 121 +2. STA sends authentication req (nothing multi-ap specific).
 122 +3. AP sends authentication resp (nothing multi-ap specific).
 123 +4. STA sends association req with Multi-AP IE.
 124 +5. AP send association resp with Multi-AP IE.
 125 +6. STA and AP both use 4-address mode for data.
 126 +
 127 +
 128 +WPS support
 129 +-----------
 130 +
 131 +WPS requires more special handling. WPS must only be advertised on fronthaul
 132 +SSIDs, not on backhaul SSIDs, so WPS should not be enabled on a backhaul-only
 133 +SSID in hostapd.conf. The WPS configuration purely works on the fronthaul SSID.
 134 +When a WPS M1 message has an additional subelement that indicates a request for
 135 +a multi-AP backhaul link, hostapd must not respond with the normal fronthaul
 136 +SSID credentials; instead, it should respond with the (potentially different)
 137 +backhaul SSID credentials.
 138 +
 139 +To support this, hostapd has the 'multi_ap_backhaul_ssid',
 140 +'multi_ap_backhaul_wpa_psk' and 'multi_ap_backhaul_wpa_passphrase' options.
 141 +When these are set on an SSID with WPS, they are used instead of the normal
 142 +credentials when hostapd receives a WPS M1 message with the Multi-AP IE. Only
 143 +WPA2 Personal is supported in the Multi-AP specification, so there is no need
 144 +to specify authentication or encryption options. For the backhaul credentials,
 145 +per-device PSK is not supported.
 146 +
 147 +If the SSID is a simultaneous backhaul and fronthaul SSID, there is no need to
 148 +specify the backhaul credentials, since the backhaul and fronthaul credentials
 149 +are identical.
 150 +
 151 +To enable the Multi-AP backhaul STA feature when it performs WPS, a new
 152 +parameter has been introduced to the WPS_PBC control interface call.
 153 +When this option is set, it adds the multi-AP backhaul subelement to
 154 +the association and M1 messages. It then configures the new SSID with
 155 +'multi_ap_backhaul_sta=1'. Note that this means that if the AP does not
 156 +follow the Multi-AP specification, wpa_supplicant will fail to
 157 +associate.
 158 +
 159 +In summary, this is the end-to-end behaviour for WPS of a backhaul link (i.e.,
 160 +multi_ap=1 option is given in the wps_pbc call on the STA side, and multi_ap=2
 161 +and multi_ap_backhaul_ssid and either multi_ap_backhaul_wpa_psk or
 162 +multi_ap_backhaul_wpa_passphrase are set to the credentials of a backhaul SSID
 163 +in hostapd on registrar AP).
 164 +
 165 +1. Fronthaul BSS beacons advertise WPS support (nothing multi-ap specific).
 166 +2. Enrollee sends authentication req (nothing multi-ap specific).
 167 +3. AP sends authentication resp (nothing multi-ap specific).
 168 +4. Enrollee sends association req with Multi-AP IE.
 169 +5. AP send association resp with Multi-AP IE.
 170 +6. Enrollee sends M1 with additional Multi-AP subelement
 171 +7. AP sends M8 with backhaul instead of fronthaul credentials.
 172 +8. Enrollee sends Deauth.
 173 +
 174 +
 175 +References
 176 +----------
 177 +
 178 +[1] https://www.wi-fi.org/discover-wi-fi/wi-fi-easymesh
 179 +[2] https://github.com/prplfoundation/prplMesh
 180 +[3] https://www.wi-fi.org/file/multi-ap-specification-v10
 181 +    (requires registration)