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

2、NK l _Toc448390962 1.2網絡架構 PAGEREF _Toc448390962 h 2 HYPERLINK l _Toc448390963 第2章 aWiFi平臺認證接口規范 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平臺云AC接口規范 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心跳與斷開重連機制 PAGEREF _Toc448390970 h 12 HYPERLINK l _Toc448390971 3.4執行配置

4、管理 PAGEREF _Toc448390971 h 13 HYPERLINK l _Toc448390972 3.4.1測試連接 PAGEREF _Toc448390972 h 13 HYPERLINK l _Toc448390973 3.4.2設置SSID PAGEREF _Toc448390973 h 14 HYPERLINK l _Toc448390974 3.4.3重啟 PAGEREF _Toc448390974 h 14 HYPERLINK l _Toc448390975 3.4.4遠程升級 PAGEREF _Toc448390975 h 14前言本標準是廣東電信aWiFi終端系列

5、企業標準之一，該系列標準目前包括：廣東電信aWiFi終端規范-技術指標； 廣東電信aWiFi終端技術要求-xxx廣東電信aWiFi平臺接口規范；廣東電信aWiFi安全審計平臺接口規范本文描述aWiFi系統中，aWiFi終端設備與aWiFi平臺的通信協議流程，包括aWiFi終端設備與aWiFi平臺認證服務的接口，aWiFi終端設備與aWiFi平臺云AC通信的接口。aWiFi系統概述廣東電信aWiFi系統由WiFi用戶（手機，平板電腦等）、WiFi網絡接入設備、aWiFi管理平臺和BOSS系統組成。 WiFi網絡接入設備分為兩類，一類是集中控制型（AC+瘦AP）設備，一類是aWiFi終端。aWiF

6、i管理平臺內部又可分為兩部分：云AC平臺和認證服務平臺。分別負責aWiFi終端設備管理和廣告推送服務。為客戶提供aWiFi業務。aWiFi系統總體參考模型如圖1所示。圖：aWiFi系統模型aWiFi系統模型說明如下：aWiFi終端aWiFi終端包括單AP終端，融合終端和一體終端，aWiFi終端與aWiFi平臺之間使用統一的接口規范，aWiFi終端的相關技術指標和接口在本系列規范中說明。參考點Mg參考點Mg是aWiFi管理平臺和aWiFi終端之間的接口界面，包括終端設備管理和認證服務兩部分，實現aWiFi終端認證和業務配置管理。該接口界面將在本文中說明。參考點Mc參考點Mc是aWiFi管理平臺和

7、AC+AP型WiFi網絡接入設備之間的接口界面，實現WiFi終端認證和業務配置管理。網絡架構aWiFi系統的網絡架構如下圖所示：aWiFi業務平臺網絡架構如下圖所示aWiFi平臺認證接口規范概述aWiFi終端和aWiFi平臺認證服務的通信協議是基于wifidog_protocol_V1（/wiki/doc/developer/WiFiDogProtocol_V1），并作出了部分細節的修改，其中主要增加了用戶的預鑒權流程，實現免登陸認證功能，建議aWiFi終端廠商使用開源軟件包wifdog V1.3.0進行開發實現。為方便，本文直接用wifidog來代指在aWiFi終端中實現與認證平臺通信的程序

8、。aWiFi認證平臺的信息如下：aWiFi認證平臺主機(%SERVER)aWiFi認證平臺端口(%PORT)8001WiFi用戶上線WiFi用戶上線流程如下圖所示：首先aWiFi終端通過iptables更改防火墻，將未認證的用戶dnat到wifidog進程，當WiFi用戶接入終端后訪問外網時，wifidog首先攔截其http報文，然后詢問aWiFi認證平臺該用戶是否準入，對應上圖中的流程，請求實例如下： 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: 報文以GET方法訪問aWiFi認證平臺的auth路徑，其中參數stage=preauth表示當前為預鑒權階段，ip為用戶ip，mac為用戶MAC，token為用戶MAC的md5值，gw_id為aWiFi終端的MAC。對于新用戶，aWiFi認證平臺將返回鑒權失敗的200報文，對應上圖中的流程，如下所示： 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當aWiFi認證平臺返回Auth：1則表示鑒權成功，wifidog隨即放通用戶，并把當前web請求重定向回原先訪問頁面，實現免登陸認證的接入上網；當aWiFi認證平臺返回Auth：0則表示需要該用戶鑒權失敗，需要登陸認證才能上網，此時wifidog則通過307報文將用戶重定向到aWiFi認證平臺的認證頁面，對應上圖中的流程。重定向請求實例如下：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: 報文以GET方法訪問aWiFi認證平臺的login路徑，表示當前已經進入認證階段，gw_address為aWiFi終端本地網關ip，gw_port設定為2060，mac為用戶MAC，gw_id為aWiFi終端的MAC，url為用戶原本希望訪問的頁面鏈接。WiFi用戶在登錄頁面，輸入用戶名密碼，發送認證請求。認證成

12、功的話aWiFi認證平臺發送302報文，攜帶token信息重定向到wifidog頁面。認證失敗的話返回失敗頁面。用戶攜帶token信息向wifidog發起認證請求，wifidog再向aWiFi認證平臺發起請求，對應上圖中的流程，請求實例如下： 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: 報文以GET方法訪問aWiFi認證平臺的auth路徑，其中參數stage=login表示當前為登錄鑒權階段，ip為用戶ip，mac為用戶MAC，token為用戶MAC的md5值，gw_id為aWiFi終端的MAC。認證成功后授權，aWiFi認證平臺返回200包給wifidog，對應上圖中的流程，如下所示： 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檢測到Auth: 1

14、，用307報文將用戶重定向到成功登錄頁面，對應上圖中的流程，如下所示。GET/smartwifi/portal/?gw_id=D4EE07083302HTTP/1.0User-Agent: WiFiDog 20150427Host: 報文以GET方法訪問aWiFi認證平臺的portal路徑，其中參數gw_id為aWiFi終端的MAC。aWiFi認證平臺根據此參數推送對應商家的成功頁面。保活和下線aWiFi終端會定時向aWiFi認證平臺發送保活消息。保活消息包括aWiFi終端自身保活和接入aWiFi終端的所有WiFi用戶設備保活兩部分。其中aWiFi終端自身保活是指aWiFi終端和aWiFi認證

15、平臺鏈路檢查。如下圖所示：請求實例如下所示：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: 報文以GET方法訪問aWiFi認證平臺的ping路徑，其中參數gw_id為aWiFi終端的MAC。隨后幾項參數包含aWiFi終端及wifidog進程相關健康狀況信息。收到aWiFi終端發出的ping請求后，aWiFi認證平臺用200包的文本Pong來回

16、應，如下所示：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用戶設備保活是指aWiFi終端向aWiFi認證平臺分別上報每個用戶的狀態，如果用戶已經離線則上報用戶離線消息，否則等待aWiFi認證平臺回應當前用戶的權限，aWiFi終端以此為根據決定繼續放通該用戶正常上網還是需要重新認證，當aWiFi認證平臺返回Auth：1則表示繼續允許，Auth：0則表示需要重新認證。aW

17、iFi終端會每隔十分鐘給接入的所有WiFi用戶設備保活，首先WiFi用戶設備攜帶設備的參數向aWiFi認證平臺發出請求，對應上圖中的，請求實例如下所示：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: 報文以GET方法訪問aWiFi認證平臺的auth路徑，其

18、中參數stage=counters 表示該鑒權動作是在認證后的保活流程，ip為用戶ip，mac為用戶設備MAC，token為用戶MAC的md5值，gw_id為aWiFi終端的MAC。隨后幾項參數包含aWiFi終端及wifidog進程相關健康狀況信息。正常情況下aWiFi認證平臺通過200包文本返回Auth：1表示該用戶鑒權成功，允許其繼續上網，對應上圖中的，如下所示：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當用戶主動請求下線后，aWiFi認證平臺會記錄用戶下線請求，同時把用戶的請求重定向回wifidog。wifidog隨即攜帶用戶信息，向aWiFi認證平臺發生下線請求，對應上圖的，請求實例如下圖所示：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: 因為aWiFi認證

20、平臺此時已經有用戶的下線記錄，aWiFi認證平臺通過200包文本返回Auth：0表示該用戶鑒權失敗，不允許其繼續上網，對應上圖中的，如下所示：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收到報文后，wifidog隨即更改防火墻將用戶下線，然后把用戶重定向到下線頁面，下線頁面的完整地址為：:8001/smartwifi/error/?message=logged-outaWiFi平臺云AC接口規

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

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