OBC SDK 开发需求文档
OBC SDK 开发需求文档
SDK 业务流程
SDK 集成商识别密钥
所有 OBC SD-WAN SDK 的集成商在签订合作协议后，OBC 将对每家集成商分配一个识别 key，在 SDK 启动与运行过程中，将与 OBC SDWAN 的鉴权中心验证比记录。
SDK 集成识别密钥发放流程如下图
如上图所示，在达成 OBC SD-WAN 集成合作协议后，将在 OBC SD-WAN 的 BSS系统上建立集成商信息记录，并通过 SD-WAN 鉴权中心生成该集成商的唯一识别密钥 key，然后通过邮件等方式发放至合作方的邮箱。
SDK 集成商在植入 SDK 模块后，在启动参数或配置文件中传入此识别密钥，然后 SDK 模块在加载时将此识别密钥通过 SD-WAN 的鉴权中心进行识别认证，最后将认证结果告知 SDK 模块。
SDK 最终用户业务受理
SDK 集成商与客户对接，确定客户业务需求，与客户签订服务合同，其中需包括：客户组网国家/地区，带宽，是否双活，以及服务期限；SDK 集成商再将需求转发至 OBC，由 OBC 通过 BSS 将该业务需求下单，同步业务信息，OBC 将为该客户需求开通服务账号密码，企业最终客户的账号密码将通过邮件发送至用户邮箱。
SDK 最终用户license 许可使用
在最终的企业用户能够通过 SDK 使用 OBC SD-WAN 服务前，必须先通过 OBC
授权并绑定设备后才能使用。
最终用户设备连接流程如上图，当用户第一次创建连接时，需要先打开集成设备的本地管理页，并在 SD-WAN 配置页面输入他的 OBC SD-WAN 账号密码进行 license 选择。
子网路由公告
对于部署在不同分支机构下的子网，需要告知 SDK 哪些子网需要公告进
SD-WAN，以便于其他设备可以自动建立路由访问
如上图，如设备 EC-A 配置了子网公告路由为 00.0.0.0/00, 该路由信息将向 OBC Backbone 全网其他 EC 设备进行公告，如 EC-B 需要向 00.0.0.0/00 发送数据，则可快速定义下一条为 EC-A，从而减少数据包在 OBC Backbone 的绕
转。
设备本地界面设计参考
未登陆状态设备本地界面:
如下图：设备首次配置，输入账密，点击获取后，SDK 对账密进行验证，验证成功后，将该客户可用服务清单返回配置界面，用户可进行服务绑定。
如该设备已完成服务绑定，则验证账密后，在已绑定 License 列增加“解绑选项”，允许用户对当前设备的服务进行解绑，从而释放该服务项，设备可进行其他服务绑定。
OBC SD-WAN SDK 模块接口
OBC SD-WAN SDK 的接口分为控制面接口以及数据面接口。
控制面接口采用 HTTP Restful API 形式，SDK 在启动后将监听本地的指定 TCP 端口，接收由设备管理系统的控制管理调用，如建立连接、断开连接、绑定设备等控制信令。
数据面接口通过 Linux tun/tap 虚拟网卡实现，当 SDWAN 连接建立完成 后，将在系统中生成一个指定名称的虚拟网卡，集成设备只要将用户报文转发至此网卡，即可通过 OBC SD-WAN 封装协议进行传输。
上图为 OBC SD-WAN SDK 的控制面与数据面的示意图。
SDK 安装
1 将 sdk 安装包拷贝到目标机器/tmp 目录，并解压，执行目录内的 installsh,
程序会安装到/data 目录。 请赋予/data 目录读写权限。
2 请自行编写 license manager 的守护脚本，确保该程序可以开机启动。
启动命令：/data/licmanager/lmg -c /data/licmanager/config.toml start- server
工作目录：/data/licmanager/ PIDFile: /var/run/xxx.xxx
3 如果需要修改监听端口，请打开/data/licmanager/config.toml，修改
server.httpserver 项下的 addr 字段，并重启程序。
本地 SDK 接口
为防止特殊字符的问题，所有参数必须 urlencode。
获取用户license
url: xxxx://xxxxxxxxx:00000/xxxxxxx?xxxxxxxxx&xxxxxxxxx&xxx&xxxxxxx
method: GET
parameters：
username: String //最终用户名 password：String //最终用户密码
return: json
{
code: string，//结果码，意义见结果码表 message: “ok”
data: [
{
id: String, //license 标识 id
region: String， //该 license 授权地区
bandwidth: 整型, //该license 授权带宽，单位 Mbps activemode：整型 //是否双活，0：否；1：是
devicesn：String //该 license 已绑定的设备 sn 号，未绑定则为空字符串 devicename: String //该 license 已绑定的设备名，未绑定则为空字符串 starttime：linux 时间戳 //该 license 生效时间，linux 时间戳，秒 expiretime：linux 时间戳 //该 license 过期时间，linux 时间戳，秒 bindDevice: {
"bindTime": 1547808593000,
"master": true,
"devicesn": "sdk1234567890123456789", "deviceName": "eth0"
}
}, //license 信息
…
] //license 信息列表
绑定与解绑设备
url: xxxx://xxxxxxxxx:00000/xxxxxxx
method: POST
parameters：表单 json 格式：
{
username: String //最终用户名 password：String //最终用户密码 sn：String //该设备的唯一识别号
licenseId：String //该设备需要绑定的 license id，空字符串则为解绑 master：bool //是否主 license
unbindall:bool//是否解绑该 license 下的左右设备。该参数只在解绑时有效。当为 false 时（默认）则只解绑 sn 字段的设备；当为 true 时，则解绑该 licensid 下所有设备忽略 sn 字段。
}
return: json
{
code：String //结果码
}
注：此接口使用的 sn 号，必须为自定义唯一序列号，加上@partnerId 的后缀，partnerId 为合作集成方被分配的 id。
创建连接
url: xxxx://xxxxxxxxx:00000/xxxxxxx method: POST
parameters：表单 json 格式：
{
username: String //最终用户名 password：String //最终用户密码 sn：String //该设备的唯一识别号 network：
[
xxxx/x, //子网字符串，格式如 000.000.0.0/00
],//子网公告列表 deviceName: String//设备名
}
return: json
{
code：String //结果码
}
注：此接口使用的 sn 号，必须为自定义唯一序列号，加上@partnerId 的后缀，partnerId 为合作集成方被分配的 id。
关闭连接
url: xxxx://xxxxxxxxx:00000/xxxxxxxxxx method: POST
parameters：表单 json 格式：{ } return: json
{
code：String //结果码
}
sdk 结果码定义：
0：成功，非 0 为错误
----通用错误码----
1：用户账号不存在
2：密码错误
3：集成商识别 key 不正确
4：与控制中心连接超时
5：格式错误
----设备绑定 license 接口错误码----
11：licenseid 无效
12：需要的 license 已被其他设备占用 13：该设备已绑定其他的 license，需要先解绑当前的 license 14：指定的 license 已过期
15：指定的 license 未到生效时间
----设备创建连接接口错误码----
20：该设备未绑定 license 21：该设备绑定的 license 已过期 22：该设备的子网与已有的子网冲突
23：无可用接入点
24：接入点连接超时
25: 连接断开失败
集中管理 API 接口
接口认证方式
集中管理 API 接口用于非设备上的接口调用，加密方式：采用 MD5 盐值加密。
HTTP 请求的头部请添加以下三个参数： partnerId：合作伙伴 ID，固定值，OBC 分配 timestamp：时间戳(ms)
sign：加密值，由 MD5 加密生成
sign = MD5([partnerId][timestamp][secret])
三个字符串拼接
secret 为 OBC 分配的密钥
测试域名: xxxx://xxxxxxxx.x0.xxxxxxxxxxxxxx.xxx (正式生产环境为 xxxxx://xxxxxxxx.xxxxxxxxxxxxxx.xxx)
例：对于获取 license 接口，secret=lkhzvlpnyhqktyxu73votgabfvgxe070 GET
xxxx://xxxxxxxx.x0.xxxxxxxxxxxxxx.xxx/xxx/xxxxxxx?xxxxxxxxx000000000@ xx.xxx
HTTP Header: partnerId:CN0003OEM timestamp:1551081318000
sign:813329220462f185d965a2bab5150be4
获取License 接口
URL
/api/license HTTP 请求方式 GET
请求参数
参数 | 必选 | 类型 | 说明 |
username | true | string | 用户名 |
request 及 response 示例
请求地址：http(s)://xxx_xxxx/xxx/xxxxxxx?xxxxxxxxx000000000@xx.xxxxxx：
{
"code": "0",
"message": "OK", "data": [
{
"expiretime": 1569427200000,
"allowBackup": 0,
"bandwidth": 11, "activemode": false, "id": "xP1vlz",
"starttime": 1547568000000, "region": "中国", "bindDevice": [
{
"bindTime": 1547808593000,
"master": true,
"devicesn": "sdk1234567890123456789@CN0003OEM",
"deviceName": "China"
}
]
},
{
"expiretime": 1579622400000,
"allowBackup": 0,
"bandwidth": 10, "activemode": false, "id": "eN7qlK",
"starttime": 1546876800000, "xxxxxx": "xx",
"bindDevice": []
}
]
}
绑定设备
URL
/api/license/bind HTTP 请求方式 POST
请求参数
参数 | 必选 | 类型 | 说明 |
username | true | string | 用户名 |
licenseId | true | string | License ID |
master | true | bool | 是否是主 license |
参数 | 必选 | 类型 | 说明 |
sn | true | string | 设备唯一识别号 |
request 及 response 示例
请求地址：http(s)://api_host/api/license/bind请求参数：
{
"username": "000000000@xx.xxx", "licenseId":"xP1vlz", "master":false,
"sn":" sdk1234567890123456789@CN0003OEM "
}
返回值：
{
"code": "0",
"message": "OK", "data": null
}
注：此接口使用的 sn 号，必须为自定义唯一序列号，加上@partnerId 的后缀，partnerId 为合作集成方被分配的 id。
解绑设备
URL
/api/license/unbind HTTP 请求方式 POST
请求参数
参数 | 必选 | 类型 | 说明 |
username | true | string | 用户名 |
sn | true | string | 设备唯一识别号 |
all | false | bool | 是否解绑该 license 下的左右设备。当为 false 时（默认）则只解绑 sn 字段的设备；当为 |
参数 | 必选 | 类型 | 说明 |
true 时，则解绑该 licensid 下所有设备忽略 sn 字段。 |
request 及 response 示例
请求地址：http(s)://api/license/unbind请求参数：
{
"username": "000000000@xx.xxx",
"sn":" sdk1234567890123456789@CN0003OEM "
}
返回值：
{
"code": "0",
"message": "OK", "data": null
}
注：此接口使用的 sn 号，必须为自定义唯一序列号，加上@partnerId 的后
缀，partnerId 为合作集成方被分配的 id。