RESTful 接口安全性设计规范

列表请求通用字段描述

返回数据通用字段描述

示例

单条数据

{
    "code": "0",
    "desc": "登录成功",
    "data": {
    }
}

多条数据

{
    "code": "0",
    "desc": "登录成功",
    "data": {
        "total": 0,
        "rows":[]
     }
}

接口安全性

敏感数据加密

使用AES加解密，AES/CBC/PKCS5Padding，密钥长度128，向量默认16个0。

密钥生成步骤：

1. 终端随机生成128位长度AES密钥，记为KEY1（byte[]）；
2. 终端使用预埋的RSA公钥加密第1步生成的KEY1，发送给服务端（Base64）；
3. 服务端使用RSA私钥，解密得到KEY1；
4. 服务端随机生成128位长度AES密钥，记为KEY2（byte[]）；
5. 服务端使用KEY1 AES加密第4步得到的KEY2，返回给终端（Base64）；
6. 终端使用KEY1，解密得到KEY2；
7. 经过以上几步，终端和服务端都同时拥有了KEY1和KEY2，使用同样的算法生成KEY3；
8. KEY3作为AES加解密的秘钥。

注意事项：

1. AES 加密后的数据需要 Base64 后传输；
2. 需要URL编码的参数如果是 Base64 后的，需要将“+”替换为%2B后，再进行URL编码传输，否则“+”在服务端会被解码成空格。

数据防篡改、防重放攻击

全局请求头

URL签名 - sign

公式：sign=SHA-256(prefix/head/query)

sign生成步骤

1. 对URL的各个参数名做字典排序。如foo=1, bar=2, baz=3 排序后为bar=2, baz=3, foo=1，拼成字符串bar=2&baz=3&foo=1，记为query；
2. 对请求头做字典排序，记为head；
3. 比如请求地址为 https://api.easyx.com/v1/users/{Id}， 则拼成字符串为/v1/users/{Id}/KEY3，其中 KEY3 为 AES 秘钥，结果记为prefix（不需要 KEY3 时，需要保留最后一个“/”）；
4. 使用SHA-256算法对 prefix/head/query 做哈希，生成sign值。

机构与系统鉴权机制

机构鉴权系统

通过“授权码”来识别是否来自系统的合法请求，系统与每一个机构之间的“授权码”都不同。

机构鉴权用户

机构需要鉴权是否来自系统合法用户的请求，步骤如下：
1. 用户携带 accessToken、userType ** 与 **orgId 访问机构 API；
2. 机构 API 通过 accessToken ** 、 **userType、orgId ** 以及“授权码”来向系统获取用户的 **手机号、用户类型、expiredTime 等；
3. 通过 手机号 以及 用户类型 来识别是否是本机构的用户；
4. 如果是本机构用户，则向机构表 authorization 插入相关数据；
5. 后续的请求，如果 authorization 表的 accessToken + userType 存在且有效，则认为是合法请求；
6. 如果不存在，继续 1- 4 步，最后更新或者插入 authorization 表数据；
7. 当然，如果 accessToken + userType 过期了，则拒绝服务，用户需要向系统更换令牌后再次访问机构 API。

错误码参考