广东电信aWiFi平台接口规范标准

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的网络连接是否正常测试连接