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。两者职责与认证不同,详见固定媒体地址协议。