廣東電信aWiFi平臺(tái)接口規(guī)范標(biāo)準(zhǔn)

1、廣東電信aWiFi平臺(tái)接口規(guī)范日期版本號(hào)修訂說(shuō)明修訂人2016-04-08V1.00新建文檔熊遠(yuǎn)雄2016-04-13V1.02修改登陸和心跳,添加工作流程熊遠(yuǎn)雄目 錄 TOC o 1-3 h z u HYPERLINK l _Toc448390959 廣東電信aWiFi平臺(tái)接口規(guī)范 PAGEREF _Toc448390959 h 1 HYPERLINK l _Toc448390960 第1章 前言 PAGEREF _Toc448390960 h 1 HYPERLINK l _Toc448390961 1.1aWiFi系統(tǒng)概述 PAGEREF _Toc448390961 h 1 HYPERLI

2、NK l _Toc448390962 1.2網(wǎng)絡(luò)架構(gòu) PAGEREF _Toc448390962 h 2 HYPERLINK l _Toc448390963 第2章 aWiFi平臺(tái)認(rèn)證接口規(guī)范 PAGEREF _Toc448390963 h 4 HYPERLINK l _Toc448390964 2.1概述 PAGEREF _Toc448390964 h 4 HYPERLINK l _Toc448390965 2.2WiFi用戶上線 PAGEREF _Toc448390965 h 4 HYPERLINK l _Toc448390966 2.3?；詈拖戮€ PAGEREF _Toc44839096

3、6 h 7 HYPERLINK l _Toc448390967 第3章 aWiFi平臺(tái)云AC接口規(guī)范 PAGEREF _Toc448390967 h 10 HYPERLINK l _Toc448390968 3.1概述 PAGEREF _Toc448390968 h 10 HYPERLINK l _Toc448390969 3.2連接登陸云AC PAGEREF _Toc448390969 h 11 HYPERLINK l _Toc448390970 3.3心跳與斷開(kāi)重連機(jī)制 PAGEREF _Toc448390970 h 12 HYPERLINK l _Toc448390971 3.4執(zhí)行配置

4、管理 PAGEREF _Toc448390971 h 13 HYPERLINK l _Toc448390972 3.4.1測(cè)試連接 PAGEREF _Toc448390972 h 13 HYPERLINK l _Toc448390973 3.4.2設(shè)置SSID PAGEREF _Toc448390973 h 14 HYPERLINK l _Toc448390974 3.4.3重啟 PAGEREF _Toc448390974 h 14 HYPERLINK l _Toc448390975 3.4.4遠(yuǎn)程升級(jí) PAGEREF _Toc448390975 h 14前言本標(biāo)準(zhǔn)是廣東電信aWiFi終端系列

5、企業(yè)標(biāo)準(zhǔn)之一，該系列標(biāo)準(zhǔn)目前包括：廣東電信aWiFi終端規(guī)范-技術(shù)指標(biāo)； 廣東電信aWiFi終端技術(shù)要求-xxx廣東電信aWiFi平臺(tái)接口規(guī)范；廣東電信aWiFi安全審計(jì)平臺(tái)接口規(guī)范本文描述aWiFi系統(tǒng)中，aWiFi終端設(shè)備與aWiFi平臺(tái)的通信協(xié)議流程，包括aWiFi終端設(shè)備與aWiFi平臺(tái)認(rèn)證服務(wù)的接口，aWiFi終端設(shè)備與aWiFi平臺(tái)云AC通信的接口。aWiFi系統(tǒng)概述廣東電信aWiFi系統(tǒng)由WiFi用戶（手機(jī)，平板電腦等）、WiFi網(wǎng)絡(luò)接入設(shè)備、aWiFi管理平臺(tái)和BOSS系統(tǒng)組成。 WiFi網(wǎng)絡(luò)接入設(shè)備分為兩類，一類是集中控制型（AC+瘦AP）設(shè)備，一類是aWiFi終端。aWiF

6、i管理平臺(tái)內(nèi)部又可分為兩部分：云AC平臺(tái)和認(rèn)證服務(wù)平臺(tái)。分別負(fù)責(zé)aWiFi終端設(shè)備管理和廣告推送服務(wù)。為客戶提供aWiFi業(yè)務(wù)。aWiFi系統(tǒng)總體參考模型如圖1所示。圖：aWiFi系統(tǒng)模型aWiFi系統(tǒng)模型說(shuō)明如下：aWiFi終端aWiFi終端包括單AP終端，融合終端和一體終端，aWiFi終端與aWiFi平臺(tái)之間使用統(tǒng)一的接口規(guī)范，aWiFi終端的相關(guān)技術(shù)指標(biāo)和接口在本系列規(guī)范中說(shuō)明。參考點(diǎn)Mg參考點(diǎn)Mg是aWiFi管理平臺(tái)和aWiFi終端之間的接口界面，包括終端設(shè)備管理和認(rèn)證服務(wù)兩部分，實(shí)現(xiàn)aWiFi終端認(rèn)證和業(yè)務(wù)配置管理。該接口界面將在本文中說(shuō)明。參考點(diǎn)Mc參考點(diǎn)Mc是aWiFi管理平臺(tái)和

7、AC+AP型WiFi網(wǎng)絡(luò)接入設(shè)備之間的接口界面，實(shí)現(xiàn)WiFi終端認(rèn)證和業(yè)務(wù)配置管理。網(wǎng)絡(luò)架構(gòu)aWiFi系統(tǒng)的網(wǎng)絡(luò)架構(gòu)如下圖所示：aWiFi業(yè)務(wù)平臺(tái)網(wǎng)絡(luò)架構(gòu)如下圖所示aWiFi平臺(tái)認(rèn)證接口規(guī)范概述aWiFi終端和aWiFi平臺(tái)認(rèn)證服務(wù)的通信協(xié)議是基于wifidog_protocol_V1（/wiki/doc/developer/WiFiDogProtocol_V1），并作出了部分細(xì)節(jié)的修改，其中主要增加了用戶的預(yù)鑒權(quán)流程，實(shí)現(xiàn)免登陸認(rèn)證功能，建議aWiFi終端廠商使用開(kāi)源軟件包wifdog V1.3.0進(jìn)行開(kāi)發(fā)實(shí)現(xiàn)。為方便，本文直接用wifidog來(lái)代指在aWiFi終端中實(shí)現(xiàn)與認(rèn)證平臺(tái)通信的程序

8、。aWiFi認(rèn)證平臺(tái)的信息如下：aWiFi認(rèn)證平臺(tái)主機(jī)(%SERVER)aWiFi認(rèn)證平臺(tái)端口(%PORT)8001WiFi用戶上線WiFi用戶上線流程如下圖所示：首先aWiFi終端通過(guò)iptables更改防火墻，將未認(rèn)證的用戶dnat到wifidog進(jìn)程，當(dāng)WiFi用戶接入終端后訪問(wèn)外網(wǎng)時(shí)，wifidog首先攔截其http報(bào)文，然后詢問(wèn)aWiFi認(rèn)證平臺(tái)該用戶是否準(zhǔn)入，對(duì)應(yīng)上圖中的流程，請(qǐng)求實(shí)例如下： GET /smartwifi/auth/?stage=preauth&ip=39&mac=3c:97:0e:d2:f6:67&token=bcabec2922484678d913cf512fe

9、e6738&incoming=0&outgoing=0&gw_id=D4EE07083302HTTP/1.0User-Agent: WiFiDog 20150427Host: 報(bào)文以GET方法訪問(wèn)aWiFi認(rèn)證平臺(tái)的auth路徑，其中參數(shù)stage=preauth表示當(dāng)前為預(yù)鑒權(quán)階段，ip為用戶ip，mac為用戶MAC，token為用戶MAC的md5值，gw_id為aWiFi終端的MAC。對(duì)于新用戶，aWiFi認(rèn)證平臺(tái)將返回鑒權(quán)失敗的200報(bào)文，對(duì)應(yīng)上圖中的流程，如下所示： HTTP/1.1 200 OKConnection: closeDate: Mon, 31 Aug 2015 11:30

10、:28 GMTContent-Length: 7X-Powered-By: Servlet/2.5 JSP/2.1Auth: 0當(dāng)aWiFi認(rèn)證平臺(tái)返回Auth：1則表示鑒權(quán)成功，wifidog隨即放通用戶，并把當(dāng)前web請(qǐng)求重定向回原先訪問(wèn)頁(yè)面，實(shí)現(xiàn)免登陸認(rèn)證的接入上網(wǎng)；當(dāng)aWiFi認(rèn)證平臺(tái)返回Auth：0則表示需要該用戶鑒權(quán)失敗，需要登陸認(rèn)證才能上網(wǎng)，此時(shí)wifidog則通過(guò)307報(bào)文將用戶重定向到aWiFi認(rèn)證平臺(tái)的認(rèn)證頁(yè)面，對(duì)應(yīng)上圖中的流程。重定向請(qǐng)求實(shí)例如下：GET /smartwifi/login/?gw_address=&gw_port=2060&gw_id=D4EE070833

11、02&mac=3c:97:0e:d2:f6:67&url=http%3A/rgeoc/%3Flnglat%3D113.182954%2C23.105509%26referer%3Dpcqq_clientHTTP/1.0User-Agent: WiFiDog 20150427Host: 報(bào)文以GET方法訪問(wèn)aWiFi認(rèn)證平臺(tái)的login路徑，表示當(dāng)前已經(jīng)進(jìn)入認(rèn)證階段，gw_address為aWiFi終端本地網(wǎng)關(guān)ip，gw_port設(shè)定為2060，mac為用戶MAC，gw_id為aWiFi終端的MAC，url為用戶原本希望訪問(wèn)的頁(yè)面鏈接。WiFi用戶在登錄頁(yè)面，輸入用戶名密碼，發(fā)送認(rèn)證請(qǐng)求。認(rèn)證成

12、功的話aWiFi認(rèn)證平臺(tái)發(fā)送302報(bào)文，攜帶token信息重定向到wifidog頁(yè)面。認(rèn)證失敗的話返回失敗頁(yè)面。用戶攜帶token信息向wifidog發(fā)起認(rèn)證請(qǐng)求，wifidog再向aWiFi認(rèn)證平臺(tái)發(fā)起請(qǐng)求，對(duì)應(yīng)上圖中的流程，請(qǐng)求實(shí)例如下： GET /smartwifi/auth/?stage=login&ip=39&mac=3c:97:0e:d2:f6:67&token=bcabec2922484678d913cf512fee6738&incoming=0&outgoing=0&gw_id=D4EE07083302 HTTP/1.0User-Agent: WiFiDog 20150427H

13、ost: 報(bào)文以GET方法訪問(wèn)aWiFi認(rèn)證平臺(tái)的auth路徑，其中參數(shù)stage=login表示當(dāng)前為登錄鑒權(quán)階段，ip為用戶ip，mac為用戶MAC，token為用戶MAC的md5值，gw_id為aWiFi終端的MAC。認(rèn)證成功后授權(quán)，aWiFi認(rèn)證平臺(tái)返回200包給wifidog，對(duì)應(yīng)上圖中的流程，如下所示： HTTP/1.1 200 OKConnection: closeDate: Tue, 01 Sep 2015 06:40:44 GMTContent-Length: 7X-Powered-By: Servlet/2.5 JSP/2.1Auth: 1wifidog檢測(cè)到Auth: 1

14、，用307報(bào)文將用戶重定向到成功登錄頁(yè)面，對(duì)應(yīng)上圖中的流程，如下所示。GET/smartwifi/portal/?gw_id=D4EE07083302HTTP/1.0User-Agent: WiFiDog 20150427Host: 報(bào)文以GET方法訪問(wèn)aWiFi認(rèn)證平臺(tái)的portal路徑，其中參數(shù)gw_id為aWiFi終端的MAC。aWiFi認(rèn)證平臺(tái)根據(jù)此參數(shù)推送對(duì)應(yīng)商家的成功頁(yè)面。?；詈拖戮€aWiFi終端會(huì)定時(shí)向aWiFi認(rèn)證平臺(tái)發(fā)送?；钕ⅰ１；钕╝WiFi終端自身?；詈徒尤隺WiFi終端的所有WiFi用戶設(shè)備保活兩部分。其中aWiFi終端自身?；钍侵竌WiFi終端和aWiFi認(rèn)證

15、平臺(tái)鏈路檢查。如下圖所示：請(qǐng)求實(shí)例如下所示：GET /smartwifi/ping/?gw_id=D4EE07083302&sys_uptime=7977811&sys_memfree=86908&sys_load=0.00&wifidog_uptime=362 HTTP/1.0User-Agent: WiFiDog 20150427Host: 報(bào)文以GET方法訪問(wèn)aWiFi認(rèn)證平臺(tái)的ping路徑，其中參數(shù)gw_id為aWiFi終端的MAC。隨后幾項(xiàng)參數(shù)包含aWiFi終端及wifidog進(jìn)程相關(guān)健康狀況信息。收到aWiFi終端發(fā)出的ping請(qǐng)求后，aWiFi認(rèn)證平臺(tái)用200包的文本Pong來(lái)回

16、應(yīng)，如下所示：HTTP/1.1 200 OKConnection: closeDate: Tue, 01 Sep 2015 06:51:46 GMTContent-Length: 4X-Powered-By: Servlet/2.5 JSP/2.1Pong接入aWiFi終端的所有WiFi用戶設(shè)備?；钍侵竌WiFi終端向aWiFi認(rèn)證平臺(tái)分別上報(bào)每個(gè)用戶的狀態(tài)，如果用戶已經(jīng)離線則上報(bào)用戶離線消息，否則等待aWiFi認(rèn)證平臺(tái)回應(yīng)當(dāng)前用戶的權(quán)限，aWiFi終端以此為根據(jù)決定繼續(xù)放通該用戶正常上網(wǎng)還是需要重新認(rèn)證，當(dāng)aWiFi認(rèn)證平臺(tái)返回Auth：1則表示繼續(xù)允許，Auth：0則表示需要重新認(rèn)證。aW

17、iFi終端會(huì)每隔十分鐘給接入的所有WiFi用戶設(shè)備保活，首先WiFi用戶設(shè)備攜帶設(shè)備的參數(shù)向aWiFi認(rèn)證平臺(tái)發(fā)出請(qǐng)求，對(duì)應(yīng)上圖中的，請(qǐng)求實(shí)例如下所示：GET /smartwifi/auth/?stage=counters&ip=39&mac=3c:97:0e:d2:f6:67&token=bcabec2922484678d913cf512fee6738&incoming=1236050&outgoing=90741&gw_id=D4EE07083302 HTTP/1.0User-Agent: WiFiDog 20150427Host: 報(bào)文以GET方法訪問(wèn)aWiFi認(rèn)證平臺(tái)的auth路徑，其

18、中參數(shù)stage=counters 表示該鑒權(quán)動(dòng)作是在認(rèn)證后的?；盍鞒?，ip為用戶ip，mac為用戶設(shè)備MAC，token為用戶MAC的md5值，gw_id為aWiFi終端的MAC。隨后幾項(xiàng)參數(shù)包含aWiFi終端及wifidog進(jìn)程相關(guān)健康狀況信息。正常情況下aWiFi認(rèn)證平臺(tái)通過(guò)200包文本返回Auth：1表示該用戶鑒權(quán)成功，允許其繼續(xù)上網(wǎng)，對(duì)應(yīng)上圖中的，如下所示：HTTP/1.1 200 OKConnection: closeDate: Mon, 31 Aug 2015 11:30:28 GMTContent-Length: 7X-Powered-By: Servlet/2.5 JSP/2

19、.1Auth: 1當(dāng)用戶主動(dòng)請(qǐng)求下線后，aWiFi認(rèn)證平臺(tái)會(huì)記錄用戶下線請(qǐng)求，同時(shí)把用戶的請(qǐng)求重定向回wifidog。wifidog隨即攜帶用戶信息，向aWiFi認(rèn)證平臺(tái)發(fā)生下線請(qǐng)求，對(duì)應(yīng)上圖的，請(qǐng)求實(shí)例如下圖所示：GET /smartwifi/auth/?stage=logout&ip=39&mac=3c:97:0e:d2:f6:67&token=bcabec2922484678d913cf512fee6738&incoming=0&outgoing=0&gw_id=D4EE07083302HTTP/1.0User-Agent: WiFiDog 20150427Host: 因?yàn)閍WiFi認(rèn)證

20、平臺(tái)此時(shí)已經(jīng)有用戶的下線記錄，aWiFi認(rèn)證平臺(tái)通過(guò)200包文本返回Auth：0表示該用戶鑒權(quán)失敗，不允許其繼續(xù)上網(wǎng)，對(duì)應(yīng)上圖中的，如下所示：HTTP/1.1 200 OKConnection: closeDate: Mon, 31 Aug 2015 11:30:28 GMTContent-Length: 7X-Powered-By: Servlet/2.5 JSP/2.1Auth: 0收到報(bào)文后，wifidog隨即更改防火墻將用戶下線，然后把用戶重定向到下線頁(yè)面，下線頁(yè)面的完整地址為：:8001/smartwifi/error/?message=logged-outaWiFi平臺(tái)云AC接口規(guī)

21、范本章描述aWiFi終端與aWiFi平臺(tái)的云AC（以下簡(jiǎn)稱云AC）通信的協(xié)議規(guī)范。概述aWiFi終端與云AC之間的通信采用TCP長(zhǎng)連接方式，數(shù)據(jù)以ASCII字符串方式傳輸。aWiFi平臺(tái)的云AC的主機(jī)信息如下：云AC主機(jī)地址云AC端口8081整個(gè)工作流程如下圖所示:連接登陸云AC aWiFi終端啟動(dòng)后，即開(kāi)始連接云AC的流程，如下圖所示：aWiFi終端嘗試通過(guò)TCP連接云AC， 如果連接成功，即完成連接流程，開(kāi)始發(fā)送登陸數(shù)據(jù)包，如果不成功，檢查重試連接的次數(shù)，如果重試次數(shù)不大于3次，則等待10秒重新連接，如果超過(guò)3次則等待10分鐘后再重新開(kāi)始本連接流程。連接成功后，要向服務(wù)器發(fā)送登陸數(shù)據(jù)包，發(fā)

22、送內(nèi)容定義如下：格式：hi-%MAC-%VER-%SSID-%DEV-%MACaWiFi終端的MAC地址-%VERaWiFi終端的固件版本號(hào)-%SSIDaWiFi終端的SSID%DEVaWiFi終端的型號(hào)樣例：hi- 64:D9:54:EE:31:32-1.43-aWiFi_Test-ESHORE EAIW-001-心跳與斷開(kāi)重連機(jī)制aWiFi終端連接云AC并發(fā)送登陸包后，當(dāng)aWiFi終端10分鐘內(nèi)沒(méi)有收到任何數(shù)據(jù)時(shí)，開(kāi)始向服務(wù)器發(fā)送心跳信息，發(fā)送完后如果1分鐘內(nèi)沒(méi)有收到云AC發(fā)回的任何數(shù)據(jù)，重試發(fā)送心跳信息，重試3次依然沒(méi)有收到數(shù)據(jù)，則關(guān)閉連接，重新進(jìn)入連接流程。如下圖當(dāng)終端10分鐘時(shí)間內(nèi)沒(méi)有接收到任何數(shù)據(jù)時(shí)，需要重新執(zhí)行一次心跳流程。心跳信息發(fā)送和服務(wù)器回復(fù)定義如下：發(fā)送內(nèi)容：*回復(fù)內(nèi)容：*執(zhí)行配置管理配置管理命令是由云AC下發(fā)的一串字符串，由aWiFi終端接收識(shí)別后，將執(zhí)行結(jié)果信息按指定的格式發(fā)回給云AC。由于云AC隨時(shí)可能下發(fā)指令，因些aWiFi終端在連接上服務(wù)器后，不能再斷開(kāi)，需要一直保持接收數(shù)據(jù)狀態(tài)，接收到數(shù)據(jù)后，分析辨別是否是云AC發(fā)送的配置管理命令。測(cè)試連接測(cè)試連接命令供云AC測(cè)試aWiFi終端與云AC的網(wǎng)絡(luò)連接是否正常測(cè)試連接