Day 23:API Payload 安全管道:顺序、保护等级与密钥

昨天结尾说今天看 value 上的另一半。Encoded 与 Encrypted 在 API payload 上只差一个数字,底下却是三段有先后的处理,而回程走的时候,顺序不只是倒着跑一遍。

一套 ERP 的 API 要回答两个彼此独立的问题:一次调用的内容该处理成什么样子,以及谁有资格决定它可以少处理一点。前者是一条固定的管道,后者是一句写在方法上的声明。两件事分开放,只在访问控制那一站被比在一起。

本篇说明:

  1. 序列化、压缩、加密三段的顺序,以及调换之后会坏在哪里
  2. ApiProtectionLevel 与 PayloadFormat 是两个不同的东西,访问控制怎么把它们比在一起
  3. aes-cbc-hmac 这个名字底下实际做了哪几件事
  4. 密钥从哪里来,以及密码学原语与安全政策为什么分居两层

一、三段的顺序

Encoded 的 value 送出去是一段 Base64。从一个对象走到那段 Base64,中间发生三段处理,每一段各由一个接口承担,也各自可以整个换掉:

段 做什么 现行实现 还能换成什么
序列化 对象变成 bytes messagepack json
压缩 bytes 变短 gzip none
加密 bytes 变成带认证码的 bytes aes-cbc-hmac none

后两个名字写在部署的那份 SystemSettings 里,第一个由调用端逐次声明在 API payload 上,没有声明就是 messagepack,昨天那张「三个组件,两种决定方式」的表讲的就是这件事。可以换掉的是每一段的实现,不是它们的先后。编码那一个(ApiPayloadTransformer)只有两行,源代码把顺序写在行末:

csharp 复制代码
byte[] bytes = serializer.Serialize(payload, type);              // Serialize
return ApiServiceOptions.PayloadCompressor.Compress(bytes);      // Compress

加密不在这两行里。它是外面那一层依格式决定要不要多做的一步,Encoded 停在这里,Encrypted 再多走一段。

压缩之所以排在加密之前,是因为压缩对密文完全无效。一份良好加密的输出在统计上与随机数据没有差别,而压缩算法找的正是重复与偏态。拿案例那份订单的 FormSchema 跑一次就看得出来:

顺序 结果
序列化 → 压缩 → 加密 压完剩下四分之一出头,加密再多加几十个字节
序列化 → 加密 → 压缩 压完比压之前还大,最后的体积是前者的三倍以上

把顺序调换不会让任何一次调用失败,也不会有任何一道检查出声。它只是让压缩那一段从此不做事。

回程的顺序是反过来的三步:解密、解压缩、反序列化。但反向真正的重点不在「倒着跑」,在于每一段只看得到通过上一段的 bytes。认证码的验证发生在解密之前,解密又在解压缩之前,所以那个 gzip 解压器从头到尾拿不到一段没有验过的数据。

解压器是一个吃任意 bytes 的解析器,把一段改过一个比特的密文直接喂给它,它会照样开始解析,然后因为读不出结构丢出异常。这条顺序让它没有机会走到那里。


二、声明的等级,与实际用的格式

PayloadFormat 的三个值昨天讲过。访问控制那一站要看的不是它一个,是它跟另一个 enum 比出来的结果,而那个 enum 有四个值。

回答的问题 几个值 谁决定
PayloadFormat 这一次调用实际做了什么 三个 调用端,写在 API payload 上
ApiProtectionLevel 这一个方法最低接受什么 四个 写这个方法的人,挂在方法或类型上

两个 enum 有两个值同名(Encoded 与 Encrypted),很容易被当成同一件事的两种说法。它们不是:一个记录事实,一个声明要求。

四个等级各要求什么,适合放哪一种方法:

等级 意思 可以用在哪
Public HTTPS 就够了 内容被服务器看到也无妨的调用,例如连通性探测 Ping
Encoded 至少要编码过 不想让人抓包就直接读出来,但不值得付加密成本的
Encrypted 要加密过 内容在服务器里也不该是明文的,例如 API 密钥的管理
LocalOnly 不接受远程调用 只该由主机进程自己发起的,例如写入定义

框架自己的方法怎么分布在这四级上,本身是一个决定:把信任界线画在 HTTPS 上,只有写方法的人明确判断「进了服务器之后也不能被看到」的那几个才标 Encrypted。中间那一级现行没有人声明,那是格式那一侧的落点,不是等级这一侧的要求。

画在 HTTPS 上不代表应用层加密没有用。HTTPS 只保护数据在网络上跑的那一段,一进到服务器就解开了,后面经手的每一站看到的都是明文:节点被入侵、记录与监控把内容留了下来、跨网段或 VPN 上被拦下来重放,这些在 ERP 的实际部署里都是真的。

线画在 Public,换到的是没有 .NET 运行环境的前端不必先实现整条加密管道才调用得到第一个方法;代价是走这一级的调用,value 进了服务器之后就看得见,需要那一层的方法得自己标上去。

判准是:实际的格式要大于或等于声明的等级,多做无妨,少做拒绝。下面这张矩阵讲的都是远程调用,而远程调用不管格式做到哪一级,都过不了 LocalOnly:

实际格式 \ 声明等级 Public Encoded Encrypted LocalOnly
Plain 通过 拒绝 拒绝 拒绝
Encoded 通过 通过 拒绝 拒绝
Encrypted 通过 通过 通过 拒绝

对着案例的端点打,三种拒绝各带各的消息:

text 复制代码
Plain   调用 System.ListApiKeys → This API requires encoded or encrypted transmission.
Encoded 调用 System.ListApiKeys → This API requires encrypted transmission.
Plain   调用 System.SaveDefine  → This API is restricted to local calls only.

「多做无妨」那一半同样实测过:拿一个 Encoded 的 API payload 调用 Public 的清单查询,通过,而且回来的也是 Encoded。服务端不动格式,它照着调用端送来的那个值把回应包回去,所以一次往返的两个方向永远是同一个格式。

LocalOnly 不是「更严格的加密」,它问的是另一件事:这个方法根本不从网络进来。既然不在同一条轴上,它就不跟格式比大小,是单独判的。Day 17 说过服务端有几个方法只接受同进程调用,指的就是这一格。它们仍然叫得动,只是不从网络叫。近端调用一进这道检查就被整个放行,连格式都不看,上面那张矩阵管不到它们。

这道检查能排在解密之前,是因为它要比的两个值一开始就拿得到:格式是 API payload 上的一个数字,等级挂在类型上、编译完就固定了。两边都不必拆开 value 看一眼。Day 16 说过访问控制排在还原之前、不替没通过的请求做解密工作,成立的条件就在这里。

没有声明的方法不是「不受限制」,是直接抛异常。找的顺序是方法自己、它重写的那一个、再到声明它的类型。代价是漏掉声明要等有人第一次调用才会发现,所以构建期另有一条规则会把这种方法指出来。


三、aes-cbc-hmac 这个名字底下有几件事

这个名字把三个部分写在一起:一个对称加密算法、一个工作模式、一个消息认证码。实现上是四个决定,加解密的主体是 AesCbcHmacCryptor:

  • 传进去的是一把 64 个字节的密钥,切成两把用:前 32 个当 AES 的密钥、后 32 个当 HMAC 的密钥。同一把密钥不兼两职。
  • 每一次加密现场产生新的 IV,本身以明文写进输出(解密要用它)。实测同一份数据、同一把密钥连续加密两次,出来的 bytes 不一样。
  • 先加密,再对加密的结果盖认证码,不是反过来。换到的是解密端在解密之前就把数据挡掉,反过来做的版本得先解密才验得了,等于让解密器先吃一段来路不明的数据。第一节那条「每一段只看得到通过上一段的 bytes」,起点就在这里。
  • 验证认证码用固定时间的比对,不是 ==。一般的循环会在第一个不同的字节就返回,于是「猜对了几个字节」变成从外面量得出来的事,攻击者可以一个字节一个字节把认证码凑出来。

固定时间比对那一条在解密那一段就是三行:

csharp 复制代码
byte[] computedHmac = hmac.ComputeHash(dataToVerify);
if (!CryptographicOperations.FixedTimeEquals(hmacBytes, computedHmac))
    throw new CryptographicException("HMAC validation failed.");

消息本身也藏着一个选择。实测三种不同的破坏方式:改一个比特的密文、改一个比特的认证码、换一把完全无关的密钥,回来的都是同一则 HMAC validation failed.。分不出来是对的,能分辨「认证码不对」与「密钥不对」本身就是一个可以拿来试探的信号。


四、密钥从哪里来

上一节那四个决定全部做对,还是没有回答一件事:那把 64 个字节的密钥是谁给的。框架把这件事跟上一节分在两层:

层 位置 放什么 举例
密码学原语 Bee.Base 给定输入算出输出,没有业务语义 AES-CBC-HMAC、RSA、密码哈希、密钥生成器、文件哈希
安全政策 Bee.Definition 密钥从哪里来、谁能访问、怎么验 主密钥来源、密钥的保护、访问令牌验证、第二节那个保护等级

分界只要问一句话:这段程序知不知道它算的是什么?上一节那个加密程序只认得 bytes 与密钥,不知道自己在加密一则 API 调用,所以它住在原语那一层,也因此本篇的 payload 与接下来要谈的密钥保护用的是同一个程序。

主密钥是链条的第一份

Day 4 那条启动依赖链的结论在这里直接沿用:主密钥是链条的第一份,它自己不能加密,所以 SystemSettings 只记它在哪里。框架默认的那一份(SystemSettings.xml)记的是一个环境变量名称:

xml 复制代码
<MasterKeySource>
  <Type>Environment</Type>
  <Value>BEE_MASTER_KEY</Value>
</MasterKeySource>

环境变量是现行的默认,文件是另一个选项。两条路各有各的暴露面,选环境变量不是因为比较安全,是因为容器与 secret 管理工具一律以环境变量注入,走文件要么挂一份 volume、要么把文件烤进镜像。主密钥不直接拿来加密任何一则调用,它的用途是解开配置文件里其他的密钥,那些密钥存的是密文,包住它们的正是 AesCbcHmacCryptor。

传输密钥是逐个 session 一把

Day 13 列过 session 上有哪些属性,其中一个是这条连接的对称密钥,当时就指名了这一篇。它由一个接口提供,而框架给了三种实现:

提供者 一把密钥怎么来 撑不撑得住 session 重建
共用式 整个部署共用一把 撑得住
推导式(默认) 由根密钥与访问令牌推导出来 撑得住
随机式 登录时随机产生,只活在 session 里 撑不住

第三列决定的是 Day 13 那个从数据库 seed 重建 session 能不能成立。接口上有一个属性专门回答它:密钥救不回来的话,重建出来的 session 会让用户看起来还在线,而每一次加密调用都失败。

推导式的根密钥默认由主密钥推出来,配置文件另外指定的话以配置文件为准。选它当默认的代价是同一个访问令牌推出来的永远是同一把密钥,不是每次登录都随机。换到的是这把密钥不必存、每个节点各自算得出来,而令牌本身是一个猜不到的 GUID、根密钥不离开服务器。这一段的顺序因此是反直觉的:令牌必须先产生,密钥才推得出来。

那把密钥怎么交到调用端手上

登录时调用端产生一对 RSA 密钥,公钥写进登录请求;服务端建好 session 之后,用那把公钥把对称密钥包起来,跟访问令牌一起返回。之后每一次要求加密的调用都用它。

Day 17 写过浏览器那一头的异常:那里产不出 RSA 密钥对,于是公钥送的是空字符串,服务端回的也是空字符串。降级发生在调用端而不是服务端,要求 Encrypted 的调用在手上没有密钥时自己退到 Encoded。对照第二节那张矩阵就知道这条退路能走多远:Encoded 这个格式过得了 Public 与 Encoded 两级,过不了标了 Encrypted 的那几个。


回到 Northwind

案例跟这一篇有关的应用代码只有启动那几行:环境变量没设就塞一把 demo 主密钥进去,把定义文件里的 payload 选项建成组件,然后在启动框架时允许自动创建。其余全在定义文件里:压缩用 gzip、加密用 aes-cbc-hmac、主密钥来自 BEE_MASTER_KEY;value 那一格案例没有另外声明,走的是默认的 messagepack。

[ApiAccessControl] 在整个案例是零处。订单那个 BO 重写了 GetNewData,重写的方法上没有挂声明,靠的正是第二节那条「找不到就往它重写的那一个找」。

不加密的那个实现只允许在调试模式下建出来,而案例的调试模式是开着的(Day 18 用过同一个旗标,那里决定的是错误消息要不要被屏蔽),于是那道检查在这里形同不存在,案例仍然选了真正的加密。这道检查本身还有一个缺口:它只挡得住依名字建实现的那一条路,直接把组件交进去的那一条绕得过它。

真正让案例的加密不算数的不是那道检查,是那把写在源代码里的 demo 主密钥。它旁边的注释自己就写着 production 必须在启动之前用真正的部署机制注入一把。框架判别不出自己现在跑在哪一种环境,硬要在启动时挡下来会误杀想跑演示数据的测试环境,所以这件事只写在注释里。


小结

一次调用的 value 上有三段处理与一句声明:

  • 三段的顺序是序列化、压缩、加密,回程反过来走,而反过来走的意义是每一段只看得到通过上一段检查的 bytes
  • 保护等级记的是这个方法最低接受什么,格式记的是这次调用实际做了什么,比的是前者小于等于后者;四个等级里有三个在同一条轴上,第四个只是借了那条轴来排队
  • 加密那一段的四个决定都可以逐项验证:两把密钥、每次新的 IV、先加密再盖认证码、固定时间比对

这三件全都验得出来。顺序调换过的管道,压缩率当场就看得出来;等级挡不挡得住,对着端点各打一次就知道;认证码有没有盖在对的位置,改一个比特试一次就有答案。

只有一件不行。那把主密钥是不是真的只有部署的人知道,从框架里面看不出来,也量不出来。前面那三件全部做对之后,整套的强度就等于那个环境变量里放的是什么,而那件事发生在代码之外:真正的防护线是部署的检查清单。

一条安全管道里,做得对不对的部分可以被验证,值不值得信任的部分不能。前者是设计题,写进机制就结案了;后者每一次部署都要重新回答一次。

明天换一条轴。保护等级管的是一次调用的形式,它从头到尾没有问过「这个人可以看到哪些数据」。


本文为 2026 iThome 铁人赛参赛文章,原文为繁体中文。

iThome 原文 | HackMD 版

系列完整目录:ERP 架构师笔记:定义驱动的框架设计

相关推荐
IT规划师1 小时前
Redis 核心机制 | 内存淘汰策略全解:8种策略、近似LRU采样、LFU计数器
redis·.net
Jeff-Tsai1 天前
Day 22:XML、JSON 与 MessagePack 的分工
.net·架构设计·erp·definition-driven
风云2 天前
从 NLite 到 Vane.Container 1.0:压箱十六年的自研 DI 容器开源
.net·di·mini 容器·nlite
Jeff-Tsai2 天前
Day 21:业务逻辑定制与 Plugin 的四个时点
.net·架构设计·erp·definition-driven
IT规划师2 天前
Redis 核心机制 | 键生命周期与 TTL 管理
redis·.net
Jeff-Tsai3 天前
Day 20:多语言定制与资源结构
.net·架构设计·erp·definition-driven
泓度科技3 天前
多租户数据隔离怎么做 单库单表架构方案
架构设计·多租户·缓存策略·数据隔离·权限管控
Jeff-Tsai4 天前
Day 19:定制层的范围与叠加粒度
.net·架构设计·erp·definition-driven