From patchwork Wed Dec 5 10:24:02 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Arnout Vandecappelle X-Patchwork-Id: 1008156 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=lists.infradead.org (client-ip=2607:7c80:54:e::133; helo=bombadil.infradead.org; envelope-from=hostap-bounces+incoming=patchwork.ozlabs.org@lists.infradead.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=mind.be Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="e6lEB5gC"; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=mind-be.20150623.gappssmtp.com header.i=@mind-be.20150623.gappssmtp.com header.b="SYQMHSKT"; dkim-atps=neutral Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 438w1b1HsRz9s8F for ; Wed, 5 Dec 2018 21:28:35 +1100 (AEDT) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=CvLkEGd1EAzQ0HL3xYOqhwQaxp1nDrTfWrhcr1m+jWM=; b=e6lEB5gCuB0kZZ gir7/s6t0dnW7D0HoMqUnhiT5xXlEwwG8HURHOFBDabd4+1ATivH/m+MZ6RmBfKT7ube4ihepTvzR ZlumWYHfT/EUcYKOjiJWlqhi28GzMUJoB6poLN+fd3B9nAirAF0fdLqVTTvb/eincpG4ighte8mdn pMKP5oO4fWvF5ac08CQdCJlCXPq16w+Px+Jl0DGABedTEKIl8/JQv6Jec0W4LlJbH7jyLMDOKTscY 7elLz40o7kbCX8WxEuPfntoBB5RRhLWgs2jXCmlp7WUcAFN+mrWWohXAcnTA0Vap0WQehvOFxXv18 LEiqsjmMB6F+y2lNXBVQ==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.90_1 #2 (Red Hat Linux)) id 1gUUPs-0007sE-7C; Wed, 05 Dec 2018 10:28:28 +0000 Received: from mail-ed1-x52e.google.com ([2a00:1450:4864:20::52e]) by bombadil.infradead.org with esmtps (Exim 4.90_1 #2 (Red Hat Linux)) id 1gUUOv-0006dL-Ty for hostap@lists.infradead.org; Wed, 05 Dec 2018 10:27:34 +0000 Received: by mail-ed1-x52e.google.com with SMTP id h50so16570933ede.5 for ; Wed, 05 Dec 2018 02:27:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mind-be.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=LjSxtPP6PhJLjNgUq8UqXqNymaggJwfU8bJeTZtgAQA=; b=SYQMHSKTlSbML/jRBO8ddpYyX+LbHb4XQlyGut0KSyi787dDoXwRupiiZiI9Veq9Q5 P41MnWcn5z9cfpmJxwvKaIccO0hX1R0D/N0T2dDITZESVrsHCFddndaHEoMuXJ+ODypD EQb5MNbfPT3nLQFFo/1B0VOXMSfLjTCXJCOIc77Nb5do6jwRfl8eNXuyj0Yjt4lC4m8h 8ClaiFp36swxY1pm85wVkES3ns/oT5Uvauov4dPGbOp7bVux/frtShmMfDlf4KKCzxu+ HXKRVqby1o6jxXlPk2mcvlSUDk9Y0jE5bAj134gYC66aeWC7EdmZs39xng7lINoQx2ua Vq/w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=LjSxtPP6PhJLjNgUq8UqXqNymaggJwfU8bJeTZtgAQA=; b=p/ndag/zTvGXRNtlTAsEurdsPOYXckyKuCRUl3o4lNgSnPkRvgI1WmGn7Va1PExRPB hBHXhOQUXEgWkECDi4f5/STWQ09l0kYXPm8yZTIkaeW+UExxv+hSGZrWGIpSdX3W1CjE RpIZNyfw+OeQxR//WgLkZU3PIX/uWkJhIygnzFQNMlk2LdmKWIftFdUaYITcbS11ow8/ E3zUoUOHWaXD1HexurrvtmWGoF8zSzgVKwo+AOX5jj2pUgiMz/rruS0gZUuKZyFozxUQ GjGwAGDRX0OgP51duGEJ4Ziya33DBNvigUZgmoKDiBfh+Uru+G4KlGe2oEi7wisXa4mc a+EQ== X-Gm-Message-State: AA+aEWZtLukrPMGlpjUBTaGVCOHKGZV7M9a/BlmEC02chCSfAjd99FJ6 jxIS4N7FWCtUwlCiBH5SVdW38L/Kk8I= X-Google-Smtp-Source: AFSGD/UEOp04iP1WYr+RQ8dYd33jiG2FQac/yZstptkloyKhs1NBjTtFR5lziFv3+HKWNLSuZTEaRQ== X-Received: by 2002:a50:f10b:: with SMTP id w11mr21663071edl.0.1544005637669; Wed, 05 Dec 2018 02:27:17 -0800 (PST) Received: from localhost.localdomain (ip-188-118-3-185.reverse.destiny.be. [188.118.3.185]) by smtp.gmail.com with ESMTPSA id z2sm5438020edd.4.2018.12.05.02.27.16 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 05 Dec 2018 02:27:17 -0800 (PST) From: "Arnout Vandecappelle (Essensium/Mind)" To: hostap@lists.infradead.org Subject: [PATCH v3 12/12] hostapd: add README-MULTI-AP Date: Wed, 5 Dec 2018 11:24:02 +0100 Message-Id: <20181205102401.17810-13-arnout@mind.be> X-Mailer: git-send-email 2.19.2 In-Reply-To: <20181205102401.17810-1-arnout@mind.be> References: <20181205102401.17810-1-arnout@mind.be> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20181205_022730_677021_24DF2017 X-CRM114-Status: GOOD ( 23.91 ) X-Spam-Score: 1.0 (+) X-Spam-Report: SpamAssassin version 3.4.2 on bombadil.infradead.org summary: Content analysis details: (1.0 points) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at http://www.dnswl.org/, no trust [2a00:1450:4864:20:0:0:0:52e listed in] [list.dnswl.org] 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.0 HEADER_FROM_DIFFERENT_DOMAINS From and EnvelopeFrom 2nd level mail domains are different -0.1 DKIM_VALID Message has at least one valid DKIM or DK signature 0.1 DKIM_SIGNED Message has a DKIM or DK signature, not necessarily valid 0.0 DKIMWL_WL_MED DKIMwl.org - Whitelisted Medium sender X-BeenThere: hostap@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Arnout Vandecappelle \(Essensium/Mind\)" Sender: "Hostap" Errors-To: hostap-bounces+incoming=patchwork.ozlabs.org@lists.infradead.org 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) --- hostapd/README-MULTI-AP | 159 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 hostapd/README-MULTI-AP diff --git a/hostapd/README-MULTI-AP b/hostapd/README-MULTI-AP new file mode 100644 index 000000000..a6d0186de --- /dev/null +++ b/hostapd/README-MULTI-AP @@ -0,0 +1,159 @@ +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-)Assocation 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. + +wpa_supplicant has a global multi_ap_backhaul_sta option to enable the Multi-AP +backhaul STA feature when it performs WPS. 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_backhaul_sta=1 in wpa_supplicant on enrollee STA, 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)