密码学与证书 / 系统课时
组织待签名消息内容
组织待签名消息内容
签名只认字节,两个业务上相同的 JSON 对象可能拥有不同字节。本篇为付款消息定义一个窄而明确的编码协议,处理字段顺序、数值范围和额外字段,再说明什么时候应采用成熟的 JSON 规范化方案。
学习目标
- 识别序列化差异怎样导致验签失败或语义歧义。
- 为有限业务结构定义可重复的字节编码。
- 让验证消息与实际执行对象共享同一份解析结果。
不要签一个没有定义的对象
消息签名的输入应该是明确字节或明确编码规则,而不是“一个 JSON”。空白、键顺序、数值表示和 Unicode 都可能变化。直接分别调用各语言默认序列化器,没有理由保证字节完全一致。
可以选择签原始正文,并确保服务器执行对同一原始正文的解析结果;也可以选择规范化结构,让各端按同一规则编码。前者保留传输形式,后者便于等价结构互认。两者的解析、拒绝和转换规则都要写进协议。
为付款定义有限编码
本例仅允许固定四个字段:版本、订单标识、整数分金额和货币。订单标识与货币限定 ASCII,金额限定安全整数,拒绝额外字段。编码使用带域标识的数组,数组位置固定,因此对象键的输入顺序不影响结果。
这是教学用业务编码规则,不是通用 JSON Canonicalization Scheme。复杂对象可以采用 RFC 8785 的 JCS,但仍需遵守其输入约束并使用经验证的实现;自己递归排序键不能覆盖数字和字符串等完整规则。

实现并验证编码规则
以下完整程序保存为 message-encoding.cjs,执行 node message-encoding.cjs。演示的对象是程序内创建的已解析值;网络入口还应使用能够拒绝重复键的 JSON 解析策略,否则重复键在进入此函数前可能已经丢失。
const { generateKeyPairSync, sign, verify } = require('node:crypto');
function encodePayment(value) {
const names = ['version', 'orderId', 'amountCents', 'currency'];
// 额外字段必须拒绝,不能悄悄排除后再让业务读取它。
if (!value || typeof value !== 'object' || Array.isArray(value) ||
Object.keys(value).sort().join(',') !== names.sort().join(',')) {
throw new Error('fields');
}
if (value.version !== 1 || !/^[A-Z0-9-]{1,32}$/.test(value.orderId) ||
typeof value.orderId !== 'string' || typeof value.currency !== 'string' ||
!/^[A-Z]{3}$/.test(value.currency) || !Number.isSafeInteger(value.amountCents) ||
value.amountCents <= 0) throw new Error('values');
// 协议域标识和固定位置消除对象键顺序的影响。
return Buffer.from(JSON.stringify(['payment-v1', value.orderId,
value.amountCents, value.currency]), 'utf8');
}
const a = { version: 1, orderId: 'ORDER-42', amountCents: 1200, currency: 'CNY' };
const b = { currency: 'CNY', amountCents: 1200, orderId: 'ORDER-42', version: 1 };
const pair = generateKeyPairSync('ed25519');
const signature = sign(null, encodePayment(a), pair.privateKey);
console.log('default JSON equal:', JSON.stringify(a) === JSON.stringify(b));
console.log('encoded equal:', encodePayment(a).equals(encodePayment(b)));
console.log('verified:', verify(null, encodePayment(b), pair.publicKey, signature));
try { encodePayment({ ...a, admin: true }); }
catch (error) { console.log('extra field:', error.message); }预期输出:
default JSON equal: false
encoded equal: true
verified: true
extra field: fields代码使用整数分金额,避免跨语言浮点表示差异。可接受的最大金额还应由业务规定;安全整数限制仅防止 JavaScript 精度丢失,不等于一个合理的支付上限。域标识防止同样的结构被其他用途误认。
规范化不能制造业务等价
文本是否允许 Unicode 规范化,应由字段协议决定。NFC 不会解决所有视觉相似字符,也不能替代身份标识规则。对路径、大小写和时区做自动修正,可能改变请求真正指向的资源,应在签发前确定且在两端保持一致。
验证后应把已校验对象交给业务执行,不能另行解析另一份正文或读取未签字段。遇到新字段,应升级协议版本并明确旧端拒绝行为;这样字段扩展不会悄悄改变旧签名的业务含义。
保存协议测试夹具时,同时保存输入对象和最终字节的十六进制表示。跨语言调试先比较这些字节,再比较签名,可以把序列化问题与密码学问题分开,避免在不一致输入上浪费时间追查密钥。