广东电信aWiFi平台接口规范.docx
20页
广东电信aWiFi平台接口规范———————————————————————————————— 作者：———————————————————————————————— 日期： 2 广东电信aWiFi平台接口规范日期版本号修订说明修订人2016-04-08V1.00新建文档熊远雄2016-04-13V1.02修改登陆和心跳,添加工作流程熊远雄广东号百WiFi运营中心1目 录广东电信aWiFi平台接口规范 1第1章 前言 11.1 aWiFi系统概述 11.2 网络架构 2第2章 aWiFi平台认证接口规范 42.1 概述 42.2 WiFi用户上线 42.3 保活和下线 7第3章 aWiFi平台云AC接口规范 103.1 概述 103.2 连接登陆云AC 113.3 心跳与断开重连机制 123.4 执行配置管理 133.4.1 测试连接 133.4.2 设置SSID 143.4.3 重启 143.4.4 远程升级 14第1章 前言本标准是广东电信aWiFi终端系列企业标准之一，该系列标准目前包括：1) 广东电信aWiFi终端规范--技术指标； 2) 广东电信aWiFi终端技术要求--xxx3) 广东电信aWiFi平台接口规范；4) 广东电信aWiFi安全审计平台接口规范本文描述aWiFi系统中，aWiFi终端设备与aWiFi平台的通信协议流程，包括aWiFi终端设备与aWiFi平台认证服务的接口，aWiFi终端设备与aWiFi平台云AC通信的接口。
1.1 aWiFi系统概述广东电信aWiFi系统由WiFi用户（，平板电脑等）、WiFi网络接入设备、aWiFi管理平台和BOSS系统组成 WiFi网络接入设备分为两类，一类是集中控制型（AC+瘦AP）设备，一类是aWiFi终端aWiFi管理平台内部又可分为两部分：云AC平台和认证服务平台分别负责aWiFi终端设备管理和广告推送服务为客户提供aWiFi业务aWiFi系统总体参考模型如图1所示图１：aWiFi系统模型aWiFi系统模型说明如下：1) aWiFi终端aWiFi终端包括单AP终端，融合终端和一体终端，aWiFi终端与aWiFi平台之间使用统一的接口规范，aWiFi终端的相关技术指标和接口在本系列规范中说明2) 参考点Mg参考点Mg是aWiFi管理平台和aWiFi终端之间的接口界面，包括终端设备管理和认证服务两部分，实现aWiFi终端认证和业务配置管理该接口界面将在本文中说明3) 参考点Mc参考点Mc是aWiFi管理平台和AC+AP型WiFi网络接入设备之间的接口界面，实现WiFi终端认证和业务配置管理1.2 网络架构aWiFi系统的网络架构如下图所示：aWiFi业务平台网络架构如下图所示第2章 aWiFi平台认证接口规范2.1 概述aWiFi终端和aWiFi平台认证服务的通信协议是基于wifidog_protocol_V1（http://dev.wifidog.org/wiki/doc/developer/WiFiDogProtocol_V1），并作出了部分细节的修改，其中主要增加了用户的预鉴权流程，实现免登陆认证功能，建议aWiFi终端厂商使用开源软件包wifdog V1.3.0进行开发实现。
为方便，本文直接用wifidog来代指在aWiFi终端中实现与认证平台通信的程序aWiFi认证平台的信息如下：aWiFi认证平台主机(%SERVER)aWiFi认证平台端口(%PORT)80012.2 WiFi用户上线WiFi用户上线流程如下图所示：1. 首先aWiFi终端通过iptables更改防火墙，将未认证的用户dnat到wifidog进程，当WiFi用户接入终端后访问外网时，wifidog首先拦截其http报文，然后询问aWiFi认证平台该用户是否准入，对应上图中的流程②，请求实例如下： [GET /smartwifi/auth/?stage=preauth&ip=192.168.1.239&mac=3c:97:0e:d2:f6:67&token=bcabec2922484678d913cf512fee6738&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。
2. 对于新用户，aWiFi认证平台将返回鉴权失败的200报文，对应上图中的流程③，如下所示： [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]当aWiFi认证平台返回Auth：1则表示鉴权成功，wifidog随即放通用户，并把当前web请求重定向回原先访问页面，实现免登陆认证的接入上网；当aWiFi认证平台返回Auth：0则表示需要该用户鉴权失败，需要登陆认证才能上网，此时wifidog则通过307报文将用户重定向到aWiFi认证平台的认证页面，对应上图中的流程⑤重定向请求实例如下：[GET /smartwifi/login/?gw_address=192.168.1.1&gw_port=2060&gw_id=D4EE07083302&mac=3c:97:0e:d2:f6:67&url=http%3A// WiFiDog 20150427Host: ]报文以GET方法访问aWiFi认证平台的login路径，表示当前已经进入认证阶段，gw_address为aWiFi终端本地网关ip，gw_port设定为2060，mac为用户MAC，gw_id为aWiFi终端的MAC，url为用户原本希望访问的页面链接。
3. WiFi用户在登录页面，输入用户名密码，发送认证请求4. 认证成功的话aWiFi认证平台发送302报文，携带token信息重定向到wifidog页面认证失败的话返回失败页面5. 用户携带token信息向wifidog发起认证请求，wifidog再向aWiFi认证平台发起请求，对应上图中的流程⑪，请求实例如下： [GET /smartwifi/auth/?stage=login&ip=192.168.1.239&mac=3c:97:0e:d2:f6:67&token=bcabec2922484678d913cf512fee6738&incoming=0&outgoing=0&gw_id=D4EE07083302 HTTP/1.0User-Agent: WiFiDog 20150427Host: ]报文以GET方法访问aWiFi认证平台的auth路径，其中参数stage=login表示当前为登录鉴权阶段，ip为用户ip，mac为用户MAC，token为用户MAC的md5值，gw_id为aWiFi终端的MAC6. 认证成功后授权，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: 1]7. wifidog检测到Auth: 1，用307报文将用户重定向到成功登录页面，对应上图中的流程⑬，如下所示。
[GET/smartwifi/portal/?gw_id=D4EE07083302HTTP/1.0User-Agent: WiFiDog 20150427Host: ]报文以GET方法访问aWiFi认证平台的portal路径，其中参数gw_id为aWiFi终端的MACaWiFi认证平台根据此参数推送对应商家的成功页面2.3 保活和下线1. aWiFi终端会定时向aWiFi认证平台发送保活消息保活消息包括aWiFi终端自身保活和接入aWiFi终端的所有WiFi用户设备保活两部分2. 其中aWiFi终端自身保活是指aWiFi终端和aWiFi认证平台链路检查如下图所示：请求实例如下所示：[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来回应，如下所示：[HTTP/1.1 200 OKConnection: closeDate: Tue, 01 Sep 2015 06:51:46 GMTContent-Length: 4X-Powered-By: Servlet/2.5 JSP/2.1Pong]3. 接入aWiFi终端的所有WiFi用户设备保活是指aWiFi终端向aWiFi认证平台分别上报每个用户的状态，如果用户已经离线则上报用户离线消息，否则等待aWiFi认证平台回应当前用户的权限，aWiFi终端以此为根据决定继续放通该用户正常上网还是需要重新认证，当aWiFi认证平台返回Auth：1则表示继续允许，Auth：0则表示需要重新认证aWiFi终端会每隔十分钟给接入的所有WiFi用户设备保活，首先WiFi用户设备携带设备的参数向aWiFi认证平台发出请求，对应上图中的①，请求实例如下所示：[GET /smartwifi/auth/?stage=counters&ip=192.168.1.239&mac=3c:97:0。
