对接说明

在 Kauth 系统中，公共参数和安全机制是保障 API 通信安全的核心组成部分。本文将详细介绍 Kauth 系统的公共参数规范、数据加密解密流程、签名验签机制以及密钥获取方式，帮助开发者快速理解并正确集成 Kauth API。

接入点

# 主站
1. api.kauth.cn
2. kauth.cn
# 备站
3. api.verifyhub.cn
4. verifyhub.cn

📡 请求头公共参数

参数名	说明	示例
Program-Id	程序ID，用于标识请求来源	`111221222`
ka-nonce	随机数，用于防重放攻击	`7890abcd`
ka-time	时间戳，13位毫秒值	`1620000000000`
ka-sign-type	签名算法类型	`RSA` 或 `ECC`
ka-sign	签名结果，确保请求完整性	`xxxxxxxxxxxxxxxx`
accesstoken	登录成功后返回的令牌,注明要登录的接口必传	`xxxxxxxxxxxxxxxx`

请求头示例：

Program-Id: 111221222
ka-nonce: 7890abcd
ka-time: 1620000000000
ka-sign-type: RSA
ka-sign: xxxxxxxxxxxxxxxx

📡 响应头公共参数

参数名	说明
ka-nonce	随机数，与请求对应
ka-time	时间戳，13位毫秒值
ka-sign-type	签名算法类型
ka-sign	签名结果，确保响应完整性

响应头示例：

ka-nonce: 7890abcd
ka-time: 1620000001000
ka-sign-type: RSA
ka-sign: xxxxxxxxxxxxxxxx

📬 响应公共参数

成功示例

{
  "msg": "操作成功",
  "data": "xxxxxxxxxx",
  "code": 200,
  "traceId": "2pztmipsntqkIzodn",
  "elapse": "11",
  "respTime": "2025-12-03 17:18:07",
  "success": true
}

失败示例

{
  "msg": "缺少程序ID",
  "data": null,
  "code": 403,
  "traceId": "2pztmipsmwlzazo43",
  "elapse": null,
  "respTime": "2025-12-03 17:17:24",
  "success": false
}

参数说明

参数名	说明
msg	服务器响应的提示信息
data	服务器响应的数据，成功时为加密后的 JSON 字符串或者null，失败时为 null
traceId	分布式链路追踪ID，用于问题排查
elapse	服务器处理耗时（毫秒），调试用
respTime	服务器响应时间（比当前时间快一分钟，历史兼容问题），有需要的可以用请求头里的时间那个是准的
success	操作是否成功（code==200时为true），方便开发者快速判断是否成功
code	响应错误码

常见错误码

[200:操作成功]
[1000:参数错误]
[1050:登录已失效，请尝试重新登录]
[500:服务器出现错误，研发小哥哥正在处理~]
[2000:操作失败，请尝试稍后重试]
[404:404]
[2001:暂无操作权限]
[1002:系统繁忙，请尝试稍后重试]

🔒 AES 加密机制

客户端加密流程

所有请求使用 POST 方法
参数采用 JSON 格式
使用 AES 密钥对 JSON 参数字符串加密
将加密结果放入请求体发起 HTTP 请求

服务端解密流程

服务器收到请求后，使用 AES 密钥解密请求体
处理业务逻辑
将结果加密后返回

🔓 AES 解密机制

服务器返回的数据中，仅 data 字段使用 AES 加密，而不是整个响应体。这样设计的好处是：

保留了错误信息的可见性，方便开发者调试
保护了核心业务数据的安全性

解密示例

API 文档描述的返回格式：

{
    "msg": "",
    "data": {
        "config": "{\"theme\":\"dark\",\"language\":\"zh-CN\"}"
    },
    "code": "",
    "traceId": "",
    "elapse": "",
    "respTime": "",
    "success": true
}

实际收到的响应（data字段已加密）：

{
    "msg": "",
    "data": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "code": "",
    "traceId": "",
    "elapse": "",
    "respTime": "",
    "success": true
}

解密data字段后的数据：

{
    "config": "{\"theme\":\"dark\",\"language\":\"zh-CN\"}"
}

✍️ 请求签名机制

为确保请求的完整性和真实性，客户端需要对请求进行签名：

数据拼接：按照指定格式拼接请求参数

body: {"username":"admin","password":""} # 原始JSON参数，非加密
nonce: 1234567890 # 与请求头ka-nonce一致
time: 1620000000000 # 与请求头ka-time一致
url: /api/v1/auth/login # 请求路径

# 拼接格式
String signTemplate = "url:" + url + "\nbody:" + (Objects.isNull(body) ? "" : body) + "\nnonce:" + nonce + "\ntime:" + time;

生成MD5摘要：

String md5Hash = md5(signTemplate);

生成签名：使用签名算法对MD5摘要加密

String kaSign = rsaSign(md5Hash);

添加到请求头：将签名放入 ka-sign 请求头

✅ 响应验签机制

客户端需要验证服务器响应的合法性：

获取响应头参数：

ka-nonce: 7890abcd # 响应头中的随机数
ka-time: 1620000001000 # 响应头中的时间戳
ka-sign: xxxxxxxxxxxxxxxx # 响应头中的签名

数据拼接：

body: {"username":"admin","password":""} # 解密后的data字段
nonce: 7890abcd # 响应头中的ka-nonce
url: /api/v1/auth/login # 请求路径
time: 1620000001000 # 响应头中的ka-time

# 拼接格式
String signTemplate = "url:" + url + "\nbody:" + (Objects.isNull(body) ? "" : body) + "\nnonce:" + nonce + "\ntime:" + time;

生成MD5摘要：

String md5Hash = md5(signTemplate);

验证签名：

# 解密服务器签名
String serverMd5 = rsaDecrypt(ka-sign);

# 比较MD5值
if (serverMd5.equals(md5Hash)) {
    # 签名验证通过，响应合法
} else {
    # 签名验证失败，响应可能被篡改
}

🔑 密钥获取方式

AES 加密解密密钥

登录 Kauth 系统
点击左侧菜单 "程序列表"
在列表中查看对应程序的 AES 密钥
密钥规格：128位（16字节）

签名密钥

Kauth 支持多种签名算法，开发者可根据需求选择：

RSA 公钥密钥 ✅

兼容性最好
密钥长度：1024位
获取路径：系统设置 → 密钥配置

ECC 公钥密钥 ⚡

性能最优，安全性最高
密钥长度：256位
获取路径：系统设置 → 密钥配置

Hmac 密钥 🛡️

兼容性好，但安全性相对较低
密钥长度：256位
用途：仅用于签名
获取路径：系统设置 → 密钥配置

📝 最佳实践

参数处理：
- 确保 JSON 参数无多余空格和换行
- 随机数应足够随机，避免重复
- 时间戳应与服务器时间同步
密钥管理：
- 密钥应妥善保管，避免泄露
- 定期更换密钥，增强安全性
- 不同环境使用不同密钥
错误处理：
- 仔细检查错误码和提示信息
- 遇到签名错误时，检查参数拼接和算法实现
- 网络异常时，实现合理的重试机制