AES 请求与响应加密¶
协议选择¶
采用标准 JWE Compact Serialization:正文使用 A256GCM(AES-256-GCM),随机请求 AES 密钥通过服务器 RSA-OAEP-256 公钥包装。响应使用客户端本次生成的另一把 AES-256 密钥;这把响应密钥放在加密请求内部传递,双方只在本次处理内存中使用。
- 每次请求重新生成请求和响应 AES 密钥,每条密文使用随机 96 位 IV、128 位认证标签。
- 不在 App、网页或 Git 内保存所有用户共用的固定 AES 密钥,不使用 ECB、固定 IV 或把 Base64 当作加密。
- RSA 私钥只保存在服务器,客户端通过获取加密公钥取得公开 JWK。
- 请求 ID 与时间戳在 GCM 认证保护的上下文中校验;Redis 原子标记已处理请求,阻止同一请求在时间窗内重放。
算法与封装依据:JWE RFC 7516、JWA RFC 7518。
当前覆盖范围¶
| 范围 | 行为 |
|---|---|
/api/v1/ 下的 JSON API |
支持同一业务路径的加密请求与响应,鉴权和业务校验保持原契约 |
GET /api/v1/security/encryption-key |
公钥分发,不使用自己的公钥加密返回值 |
/api/v1/media/* 的媒体GET和业务DELETE |
不进入本协议,沿用认证与TLS;旧App文件POST已移除,前置410为普通HTTP错误,不进入JWE |
/api/v1/media/uploads、/api/v1/media/uploads/{uploadId}、/api/v1/media/uploads/{uploadId}/complete |
直传申请、取消和确认均为JSON,按本协议加密;独立OSS PUT不带本站JWE或Bearer |
后台 /api/v1/admin/users/{userId}/avatars、album-photos 及各自 /{id} |
仅明确的上传、读取及相册暂存丢弃路径不套JWE;仍要求HTTPS、管理员Cookie、公共头、同源和写CSRF,其他后台JSON路径继续强制JWE |
后台 /api/v1/admin/posts/{postId}/photos/{photoId}、files/{fileId}、files/{fileId}/poster,以及 /api/v1/admin/content-reports/{reportId}/evidence/{fileId} |
仅明确GET媒体字节不套JWE;仍要求HTTPS、管理员Cookie、公共头及对应读取权限;审核、列表、详情和处理状态JSON继续强制JWE |
| WebSocket/Actuator/文档页 | 不在本次 JSON 报文协议内,WebSocket 继续使用 WSS 与一次性票据 |
部署启用加密模块后,prod 对以上 JSON API 强制要求密文;dev运行配置默认兼容现有App明文JSON调用,可配置统一要求加密。选择加密的客户端不能接受明文业务响应作为降级。
当前API为https://api.budyoo.cn,可信证书、公网HTTPS入口和HTTPS JWE已通过检查;这是唯一正式部署环境,目前处于上线前阶段,实际运行配置仍为dev;App正式开放及客户端验收仍待完成。原有受控HTTP联调例外不用于正式开放;JWE不能替代TLS对服务端身份、URL及HTTP头的保护。
公共请求头¶
原有客户端元数据和语言头继续发送。加密模式增加或调整:
| 请求头 | 值 | 说明 |
|---|---|---|
X-Budyoo-Encryption |
jwe-v1 |
明确启用当前版本,不支持未知值 |
Accept |
application/jose |
外层响应为 JWE,解密后仍是统一 JSON |
Content-Type |
application/jose |
POST/PUT/PATCH/DELETE 的密文正文;GET 不传正文 |
X-Budyoo-JWE |
compact JWE | 仅 GET 使用,携带空业务正文和本次响应密钥的加密信封 |
X-Request-Id |
每次请求新 UUID | 原子防重放标识,不是业务幂等键 |
X-Request-Timestamp |
13 位 Unix 毫秒 | 与服务端时间偏差最多 120 秒 |
客户端切换加密后,具体接口文档中的业务 JSON 字段不变,由统一网络封装透明处理。不要手动改写 Content-Type 大小写、参数或已绑定的头后再发送同一密文。
请求信封¶
JWE 五段结构为:
protected.encrypted_key.iv.ciphertext.tag
所有段使用 Base64URL、无 = 填充。受保护头:
{
"alg": "RSA-OAEP-256",
"enc": "A256GCM",
"typ": "budyoo.request+jwe",
"cty": "application/json",
"kid": "服务器公钥返回的kid",
"v": 1,
"ctx": "请求上下文的SHA256摘要,Base64URL编码"
}
AES 加密前的内部 JSON:
{
"responseKey": "本次独立32字节AES响应密钥的Base64URL编码",
"body": {"message":"Budyoo 加密测试","number":7}
}
GET 的 body 固定为 null,密文放在 X-Budyoo-JWE 中;没有正文的 POST 也使用 body: null。不要把口令、Token 或其他敏感数据放进查询串。
请求上下文绑定¶
ctx 为下面 UTF-8 文本的 SHA-256 Base64URL 摘要。每行结尾均为 LF,包括最后一行;方法大写,路径和查询保留 URL 原编码及顺序,头名称小写,值按实际发送内容,缺省为空。
budyoo-jwe-v1
HTTP方法
原始路径
原始查询串(不含问号,无查询时为空行)
accept:值
accept-language:值
content-type:值
authorization:值
x-client-type:值
x-platform:值
x-app-version:值
x-app-build:值
x-channel:值
x-device-id:值
x-request-id:值
x-request-timestamp:值
x-os-version:值
x-device-model:值
重复头或换行值拒绝处理。代理不可修改这些值;如果未来需要改变规范化规则,必须升级加密协议版本。
加密响应¶
响应仍保留业务 HTTP 状态;Content-Type: application/jose、X-Budyoo-Encryption: jwe-v1、Cache-Control: no-store。解密后是原 code/message/data/errors,成功和参数/鉴权失败都一致。
响应 JWE 使用 alg: dir、enc: A256GCM,五段结构的第二段为空;GCM 密钥为该请求内的 responseKey。受保护头还包括:
{
"alg":"dir",
"enc":"A256GCM",
"typ":"budyoo.response+jwe",
"cty":"application/json",
"kid":"本次请求使用的kid",
"v":1,
"rid":"本次X-Request-Id",
"ctx":"本次请求ctx",
"status":200
}
客户端必须检查算法白名单、版本、kid、rid、ctx、status 和 GCM 标签,任何一项失败都不得展示为可信业务返回。四语提示在加密前生成,解密后直接展示。
错误处理¶
| HTTP | code | 含义 |
|---|---|---|
| 400 | ENCRYPTION_REQUIRED |
当前环境要求密文,未发送加密标记 |
| 400 | INVALID_ENCRYPTED_REQUEST |
密文、算法、认证标签、内部格式或上下文校验失败 |
| 400 | ENCRYPTION_KEY_EXPIRED |
kid 已不在服务端密钥集合中,重新获取公钥 |
| 400 | ENCRYPTED_REQUEST_EXPIRED |
时间戳超窗,校准设备时间后重新构造请求 |
| 409 | ENCRYPTED_REQUEST_REPLAYED |
请求 ID 已成功通过校验并被占用,不再执行业务 |
| 413 | PAYLOAD_TOO_LARGE |
请求 JSON 超过 256 KiB 或外层密文过大;响应缓存上限1 MiB,超过时返回加密的通用500错误 |
| 426 | HTTPS_REQUIRED |
当前路径或正式环境要求安全传输 |
| 503 | SERVICE_UNAVAILABLE |
防重放 Redis 不可用,不绕过校验放行 |
无法解密、过期或重放的请求尚不能建立可信响应上下文,可能返回不含敏感内容的明文错误。客户端将它报告为加密层失败,不当成已认证的业务结果。无论是否加密,超时都不表示写操作没有执行;不自动重发写入,业务幂等仍需单独实现。
JS 统一封装用 BudyooApiError.kind 区分本地错误:超时为 timeout,主动取消为 cancelled,密文格式、认证标签或响应绑定失败为 encryption。即使中断发生在读取加密响应体期间,也保留超时/取消分类;这些本地错误不使用服务端业务 code。
客户端使用¶
下载 budyoo-encryption.mjs 和 budyoo-client.mjs,由统一请求层注入适配器。浏览器需要 Web Crypto 安全上下文;当前文档站已使用HTTPS;调用方仍须在受信HTTPS页面或具备Web Crypto的Node.js中按权限验证。
import {createJweEncryption} from './budyoo-encryption.mjs';
import {createBudyooClient, createUuid} from './budyoo-client.mjs';
const baseUrl = 'https://api.budyoo.cn';
const deviceId = createUuid(); // 仅测试;正式App使用持久安装ID。
const api = createBudyooClient({
baseUrl,
allowInsecureDevelopment: true, // 仅系统测试,正式必须HTTPS。
getLanguage: () => 'ja-JP',
getClientMetadata: () => ({
clientType:'app', platform:'android', appVersion:'1.0.0',
appBuild:'1', channel:'dev', deviceId,
}),
encryption: createJweEncryption({baseUrl, allowInsecureDevelopment:true}),
});
const result = await api.request({
path:'/api/v1/system/request-test', method:'POST',
body:{message:'Budyoo 加密测试', number:7},
});
console.log(result.passed, result.language);
使用当前HTTPS域名时不需要两个开发HTTP开关。Flutter 当前网络层尚未实现本次 JWE 协议,应按本页在统一 Dio 层接入,不能只加一个加密标记而发送普通 JSON。WebSocket 消息加密不在本次变更内。
已验证结果¶
部署服务器已通过14项真实加密检查:四语成功和校验失败的双向加密、GET响应、密文篡改、头部绑定、时间窗、重复及并发重放。20项Java测试直接覆盖加密层并随完整服务器构建运行;公开JS封装与加密适配器共17项测试通过,包含加密响应读取期间的超时、主动取消和真实验证失败分类。上述历史测试使用合成字段,不代表真实身份或Flutter加密链路已经验收;后续公网HTTPS及HTTPS JWE检查结果见安全状态。
OSS下载控制面¶
POST /api/v1/media/downloads是正常JWE JSON控制接口,申请及含短效签名的响应均须加密,整包16KiB。返回的OSS GET使用独立连接,不携带本站Bearer、公共头、Cookie或JWE;原媒体GET仍为二进制。详见下载授权。
媒体的POST /api/v1/media/credentials属于与下载授权相同的JWE JSON控制面;CDN专用GET /api/v1/media/cdn/authorize仅返回鉴权HTTP状态,不套JWE,也不接收App的八项公共头或本站Bearer。两者职责与认证不同,详见固定媒体地址协议。