《广东电信aWiFi平台接口规范.docx》由会员分享，可在线阅读，更多相关《广东电信aWiFi平台接口规范.docx（9页珍藏版）》请在三一文库上搜索。
1、广东电信aWiFi平台接口规范日期版本号修订说明修订人2016-04-08V1.00新建文档熊远雄2016-04-13V1.02修改登陆和心跳，添加工作流程熊远雄广东电信aWiFi平台接口规范 错误!未指定书签。第 1 章 前言 错误!未指定书签o1.1 aWiFi系统概述 错误！未指定书签。1.2 网络架构 错误！未指定书签。第2章aWiFi平台认证接口规范 错误!未指定书签。2.1 概述 错误！未指定书签。2.2 WiFi用户上线 错误！未指定书签。2.3 保活和下线 错误！未指定书签。第3章aWiFi平台云AC接口规范 错误！未指定书签。3.1 概述错误！未指定书签。3.2 连接登陆云
2、AC 错误！未指定书签。3.3 心跳与断开重连机制 错误！未指定书签。3.4 执行配置管理 错误！未指定书签。3.4.1 测试连接错误！未指定书签。342设置SSID 错误！未指定书签。3.4.3 重启 错误！未指定书签。3.4.4 远程升级 错误！未指定书签。第 1章 前言本标准是广东电信aWiFi 终端系列企业标准之一，该系列标准目前包括：1) 广东电信aWiFi 终端规范-技术指标；2) 广东电信aWiFi终端技术要求-xxx3) 广东电信aWiFi平台接口规范；4) 广东电信aWiFi安全审计平台接口规范本文描述aWiFi 系统中，aWiFi 终端设备与aWiFi 平台的通信协议流程，
3、包括aWiFi 终端设备与aWiFi 平台认证服务的接口，aWiFi 终端设备与aWiFi 平台云 AC 通信的接口。1.1 aWiFi 系统概述广东电信aWiFi 系统由 WiFi 用户(手机，平板电脑等)、 WiFi 网络接入设备、aWiFi管理平台和BOSS 系统组成。WiFi 网络接入设备分为两类，一类是集中控制型(AC+ 瘦AP )设备，一类是aWiFi 终端。 aWiFi 管理平台内部又可分为两部分：云AC 平台和认证服务平台。分别负责aWiFi 终端设备管理和广告推送服务。为客户提供aWiFi 业务。aWiFi 系统总体参考模型如图1 所示。图1 ： aWiFi系统模型aWiFi
4、 系统模型说明如下：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 业
5、务平台网络架构如下图所示第2章aWiFi平台认证接口规范2.1 概述aWiFi终端和aWiFi平台认证服务的通信协议是基于 wifidog_protocol_V1 （）,并作出了部 分细节的修改，其中主要增加了用户的预鉴权流程，实现免登陆认证功能， 建议aWiFi终端厂商使用开源软件包 wifdog V1.3.0进行开发实现。为方便，本文直接用 wifidog来代指在aWiFi终端中实现与认证平台通信的程序。aWiFi认证平台的信息如下：aWiFi认证平台主机（SERVER）aWiFi认证平台端口（PORT）80012.2 WiFi用户上线WiFi用户上线流程如下图所示：1. 首先aWiFi终
6、端通过iptables更改防火墙，将未认证的用户 dnat到wifidog进程，当WiFi 用户接入终端后访问外网时，wifidog首先拦截其http报文，然后询问aWiFi认证平台该用户是否准入，对应上图中的流程，请求实例如下：HTTP/1.0报文以GET方法访问aWiFi认证平台的auth路径,其中参数stage=preauth表示当前为预鉴 权阶段，ip为用户ip, mac为用户 MAC , token为用户 MAC的md5值，gw_id为aWiFi终 端的MAC。2. 对于新用户，aWiFi认证平台将返回鉴权失败的200报文，对应上图中的流程，如下所示：HTTP/1.1 200 OKC
7、onnection: 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认证平台的认证页面，对应上图中的流程。重定向请求实例如下：GETHTTP/1
8、.0报文以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认证平台发起请求，对应上图中的流程？，请求实例如下
9、：HTTP/1.0报文以GET方法访问aWiFi认证平台的auth路径,其中参数stage=login表示当前为登录鉴 权阶段，ip为用户ip, mac为用户 MAC , token为用户 MAC的md5值，gw_id为aWiFi终 端的MAC。6. 认证成功后授权，aWiFi认证平台返回200包名w 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:
10、17. wifidog检测到Auth: 1，用307报文将用户重定向到成功登录页面，对应上图中的流程？,如下所示。GET/smartwifi/portal/?gw_id=D4EE07083302HTTP/1.0报文以GET方法访问aWiFi认证平台的portal路径，其中参数gw_id为aWiFi终端的MAC。 aWiFi认证平台根据此参数推送对应商家的成功页面。2.3 保活和下线1 . aWiFi终端会定时向aWiFi认证平台发送保活消息。保活消息包括 aWiFi终端自身保活 和接入aWiFi终端的所有WiFi用户设备保活两部分。2 .其中aWiFi终端自身保活是指aWiFi终端和aWiFi
11、认证平台链路检查。如下图所示：请求实例如下所示：GET/smartwifi/ping/?gw_id=D4EE07083302&sys_uptime=7977811&sys_memfree=86908&sys_load=0.00&wifidog_uptime=362 HTTP/1.0报文以GET方法访问aWiFi认证平台的ping路径，其中参数 gw_id为aWiFi终端的 MAC。随后几项参数包含 aWiFi终端及wifidog进程相关健康状况信息。收到aWiFi终端发出的ping请求后，aWiFi认证平台用200包的文本Pong来回应，如下所示：HTTP/1.
12、1 200 OKConnection: closeDate: Tue, 01 Sep 2015 06:51:46 GMTContent-Length: 4X-Powered-By: Servlet/2.5 JSP/2.1Pong3 .接入aWiFi终端的所有 WiFi用户设备保活是指aWiFi终端向aWiFi认证平台分别上报每个用户的状态，如果用户已经离线则上报用户离线消息，否则等待 aWiFi认证平台回应当前用户的权限，aWiFi终端以此为根据决定继续放通该用户正常上网还是需要重新认证，当aWiFi认证平台返回 Auth : 1则表示继续允许，Auth : 0则表示需要重新认证。aWiFi终
13、端会每隔十分钟给接入的所有WiFi用户设备保活，首先WiFi用户设备携带设备的参数向aWiFi认证平台发出请求，对应上图中的，请求实例如下所示：报文以GET方法访问aWiFi认证平台的auth路径，其中参数 stage=counters表示该鉴 权动作是在认证后的保活流程，ip为用户ip, mac为用户设备 MAC , token为用户MAC的md5值，gw_id为aWiFi终端的MAC。随后几项参数包含 aWiFi终端及wifidog进程相关健 康状况信息。正常情况下aWiFi认证平台通过 200包文本返回Auth : 1表示该用户鉴权成功，允许其继续上网，对应上图中的，如下所示：HTTP/
14、1.1 200 OKConnection: closeDate: Mon, 31 Aug 2015 11:30:28 GMTContent-Length: 7X-Powered-By: Servlet/2.5 JSP/2.1Auth: 14 .当用户主动请求下线后，aWiFi认证平台会记录用户下线请求，同时把用户的请求重定向回wifidog。 wifidog随即携带用户信息，向 aWiFi认证平台发生下线请求，对应上图 的，请求实例如下图所示：HTTP/1.0因为aWiFi认证平台此时已经有用户的下线记录，aWiFi认证平台通过200包文本返回Auth: 0表示该用户鉴权失败，不允许其继续上网
15、，对应上图中的 ，如下所示： HTTP/1.1 200 OK Connection: close Date: Mon, 31 Aug 2015 11:30:28 GMT Content-Length: 7X-Powered-By: Servlet/2.5 JSP/2.1Auth: 0收到报文后，wifidog随即更改防火墙将用户下线，然后把用户重定向到下线页面，下线页 面的完整地址为：第3章aWiFi平台云AC接口规范本章描述aWiFi终端与aWiFi平台的云AC （以下简称云 AC）通信的协议规范。3.1 概述aWiFi终端与云AC之间的通信采用TCP长连接方式，数据以 ASCII字符串方式
16、传输。aWiFi平台白云AC的主机信息如下：云AC主机地址云AC端口8081整个工作流程如下图所示：3.2 连接登陆云ACaWiFi终端启动后，即开始连接云AC的流程，如下图所示：aWiFi终端尝试通过TCP连接云AC,如果连接成功，即完成连接流程，开始发送登陆数 据包，如果不成功，检查重试连接的次数，如果重试次数不大于3次，则等待10秒重新连接，如果超过3次则等待10分钟后再重新开始本连接流程。连接成功后，要向服务器发送登陆数据包，发送内容定义如下：格式：hi-%MAC-%VER-%SSID-%DEV-%MACaWiFi终端的MAC地址-%VERaWiFi终端的固件版本号-%SSIDaWiF
17、i终端的SSID%DEVaWiFi终端的型号样例：hi- 64:D9:54:EE:31:32-1.43-aWiFi_Test-ESHORE EAIW-001-3.3 心跳与断开重连机制aWiFi终端连接云AC并发送登陆包后，当aWiFi终端10分钟内没有收到任何数据时， 开始 向服务器发送心跳信息， 发送完后如果1分钟内没有收到云 AC发回的任何数据，重试发送 心跳信息，重试 3次依然没有收到数据，则关闭连接，重新进入连接流程。如下图当终端10分钟时间内没有接收到任何数据时，需要重新执行一次心跳流程。心跳信息发送和服务器回复定义如下：发送内容：*回复内容：*3.4 执行配置管理配置管理命令是由
18、云 AC下发的一串字符串，由aWiFi终端接收识别后，将执行结果信息按 指定的格式发回给云 AC。由于云AC随时可能下发指令，因些 aWiFi终端在连接上服务器 后，不能再断开，需要一直保持接收数据状态，接收到数据后，分析辨别是否是云AC发送的配置管理命令。3.4.1 测试连接测试连接命令供云 AC测试aWiFi终端与云AC的网络连接是否正常测试连接命令定义：格式：<echo 'ok'echo '=%SessionID='>%SessionID由云AC生成的标识本次通信的一串随机字符串样例：<echo 'ok'echoaWiFi
19、终端响应的内容定义如下：格式：ok=%SessionID=%SessionID必须与云 AC下发命令中的SessionID相同样例：ok3.4.2 设置 SSID设置SSID命令供云 AC设置aWiFi终端的SSID设置SSID命令定义：格式：<uci set wireless.wifi-iface%INDEX.ssid='%SSID'uci commit;echo '=%SessionID=，%INDEX要设置的无线接口编号，第一个为0,第二个为1,%SSID要设置的新SSID名%SessionID由云AC生成的标识本次通信的一串随机字符串样例：<uci
20、set wireless.wifi-iface0.ssid='aWiFi_Test'uci commit;echoaWiFi终端响应的内容定义如下：格式：=%SessionID=%SessionID必须与云 AC下发命令中的SessionID相同样例：3.4.3 重启重启命令供云 AC重启aWiFi终端设备 重启命令定义：格式：<echo 'disconnection-sys_reboot_ready'reboot;echo '=%SessionID='>%SessionID由云AC生成的标识本次通信的一串随机字符串样例：<ec
21、ho 'disconnection-sys_reboot_ready'reboot;echoaWiFi终端发回以下定义内容，再重启:格式：disconnection-sys_reboot_ready=%SessionID=%SessionID必须与云 AC下发命令中的SessionID相同样例：disconnection-sys_reboot_ready=3.4.4 远程升级远程升级命令供云 AC远程升级aWiFi终端设备的固件 远程升级命令定义：格式：<echo 'sys_rom_update_ready'/etc_ro/mysh/rom_update.sh;echo '=%SessionID='>%SessionID由云AC生成的标识本次通信的一串随机字符串样例：<echo 'sys_rom_update_ready'/etc_ro/mysh/rom_update.sh;echoaWiFi终端发回以下定义内容，并升级固件再重启:格式：sys_rom_update_ready=%SessionID=%SessionID必须与云 AC下发命令中的SessionID相同样例：sys_rom_update_ready=