openpencil 公共协作中继协议解析:签名定位符、邀请值与挑战绑定证明 v2
openpencil 公共协作中继协议解析:签名定位符、邀请值与挑战绑定证明 v2
本篇技术指南以 op-collab-relay-protocol crate 为核心,深入讲解 OpenPencil 公共协作中继(relay)的传输无关线协议:opcl1_ 签名定位符与 opc1_ 邀请值的编码规则与安全边界、从解码到 VerifiedRelayRoute 的显式验证流程,以及取代 v1 可重用占有证明的「挑战绑定证明 v2」(Challenge-bound proof v2)的完整密码学推导。读完本文,你将能理解该协议为何把路由元数据与承载能力分离、为何校验和不等于认证,并掌握在客户端与服务端两侧正确验证定位符与挑战证明的工程要点。
协议定位:开放的、传输无关的线类型
op-collab-relay-protocol(Cargo.toml)是 OpenPencil 公共协作中继使用的、开放且传输无关的线协议类型集合。中继本质上是一个会合(rendezvous)与字节转发服务:应用流量始终由既有的端到端 Noise 会话保护,中继本身只负责把两端「接上头」并转发密文,无法读取会话内容。
该 crate 在仓库中的作用从 lib.rs 的模块划分可见一斑:
locator:签名定位符、验证器 trait 与验证后类型;invite:把定位符与承载能力合并为单一可粘贴字符串的邀请值;challenge:服务器挑战与 v2 证明推导;control:501 字节定长 ClientHello、认证模式、拒绝码与服务器状态;reauth:在线重认证控制消息;pairing:人类可输入的短配对码;sensitive:路由 ID、承载能力等敏感类型的封装与零化。
它只依赖 base64、blake3、hkdf、hmac、sha2、zeroize 与可选的 getrandom,把密码学边界内聚在一个 crate 内,供客户端、服务端、控制平面、HSM 定位器等组件共享同一套线格式。
opcl1_ 签名定位符:路由元数据与承载秘密分离
opcl1_ 是一个签名的公共定位符,其核心设计原则是:定位符中故意不包含任何账号主体(account subject)、文档名或协作会话标识符。内部 32 字节的承载路由能力(bearer route capability)始终作为独立秘密保存,绝不进入定位符本身。
固定尺寸规范表示与无填充 base64url
定位符使用单一固定尺寸的规范二进制表示,并以无填充 base64url 对外编码。相关常量定义在 locator.rs:
| 常量 | 值 | 含义 |
|---|---|---|
RELAY_PROTOCOL_VERSION |
1 |
协议版本 |
LOCATOR_PREFIX |
"opcl1_" |
定位符文本前缀 |
RELAY_LOCATOR_BINARY_BYTES |
336 |
定位符二进制总长(含签名与校验和) |
LOCATOR_CANONICAL_SIGNING_BYTES |
268 |
参与签名的规范字节长度 |
MAX_INVITE_CHARS |
512 |
文本编码长度上限 |
MAX_EXPECTED_DISCOVERY_ID_BYTES |
128 |
discovery 标识长度上限 |
MAX_LOCATOR_KEY_ID_BYTES |
64 |
签名密钥 ID 长度上限 |
MAX_PAIRING_LIFETIME_SECS |
60 * 60 |
配对生命周期上限(1 小时) |
校验和只防意外损坏,不提供认证
二进制定位符的最后 4 字节是校验和。从源码看(locator.rs),它由 BLAKE3 derive_key 派生密钥哈希前 4 字节构成,上下文为 openpencil/op-collab-relay-protocol/locator-corruption-checksum/v1:
fn corruption_checksum(bytes: &[u8]) -> [u8; 4] {
let mut hasher = blake3::Hasher::new_derive_key(CHECKSUM_CONTEXT);
hasher.update(bytes);
let digest = hasher.finalize();
let mut checksum = [0_u8; 4];
checksum.copy_from_slice(&digest.as_bytes()[..4]);
checksum
}
它无密钥、攻击者可以轻易重算,因此只用于检测意外损坏,不提供任何认证。真正的认证来自两处:定位符自身的签名,以及独立授权票据(authorization ticket)对 caller_device_dh_pub_x25519 的绑定。
二进制字段布局
encode_claims(locator.rs)给出 268 字节签名区的精确排布:
| 偏移 | 长度 | 字段 |
|---|---|---|
| 0 | 1 | 协议版本(1) |
| 1 | 1 | home region 编码(RelayRegion::Cn = 1,Global = 2) |
| 2–17 | 16 | RouteId |
| 18–25 | 8 | 代次(generation,NonZeroU64 大端) |
| 26–57 | 32 | 所有者 Noise 静态公钥(OwnerNoiseStatic) |
| 58 | 1 | discovery ID 长度 |
| 59–186 | 128 | 期望 discovery ID(定长填充,尾部补零) |
| 187–194 | 8 | not_before_unix |
| 195–202 | 8 | expires_at_unix |
| 203 | 1 | 签名密钥 ID 长度 |
| 204–267 | 64 | 签名密钥 ID(LocatorKeyId,定长填充) |
| 268–331 | 64 | 签名(LocatorSignature,ed25519 类 64 字节) |
| 332–335 | 4 | 损坏校验和 |
解码端(decode_binary)对上述每个字段做严格校验:版本必须为 1、region/role 必须已知、RouteId/OwnerNoiseStatic/generation 不得全零、ASCII 字段必须为非空可打印字符(0x21..=0x7e)且长度受限、定长填充区必须全零(NonZeroReserved)、校验和必须匹配。测试 protocol.rs 中的 locator_rejects_version_region_secrets_expiry_and_corruption 逐字段验证了这些 fail-closed 行为。
文本编码与解码约束
encode/decode(locator.rs)强制执行三条规范约束:
- 必须以
opcl1_开头; - 正文不能含
=填充,只能由A-Za-z0-9-_组成; - 解码后重新编码必须与原文一致(拒绝非规范编码)。
同时总长度不得超过 MAX_INVITE_CHARS(512),超长返回 LocatorTooLong。
opc1_ 邀请值:定位符 + 承载能力 = 一次粘贴
RelayInviteV1(invite.rs)把签名定位符和 32 字节承载能力合并为一个可粘贴的 opc1_ 值,供 UI 一次性分享。其二进制布局为 [version=1][locator:336][capability:32][checksum:4],共 RELAY_INVITE_BINARY_BYTES = 373 字节。
安全约束:完整的邀请值等价于路由访问凭证,绝不能写入日志,也不能放入 URL 的 path 或 query(中间设备会记录它们)。只有产品需要单次分享操作时,才允许放进受保护的 URL fragment(# 之后)。这一点在 RelayInviteV1 的文档注释中写得很明确:
Treat its encoded form as a secret. It is suitable for a protected URL fragment, but never for a URL path or query where intermediaries log it.
注意 RelayInviteV1::from_fragment 同样只解码、不验证;调用方必须显式调用 verify。邀请值的 Debug 实现整体输出 RelayInviteV1(<a href="https://link.gitcode.com/i/4a1bf3ea8bee4be15bfb6f91452ded6a" target="_blank">REDACTED]),RouteCapability 在 Drop 时执行 zeroize([sensitive.rs),从生命周期上防止秘密残留。
显式验证流程:从解码到 VerifiedRelayRoute
协议刻意把「解码」与「验证」拆开:RelayLocatorV1::decode 与 RelayInviteV1::from_fragment 返回的都是未验证数据。调用方必须通过显式验证 API 处理:
// 未验证数据:decode 仅做格式与结构检查
let locator = RelayLocatorV1::decode(&encoded)?;
// 显式验证:校验时间窗口 + 签名
let verified: VerifiedRelayLocator = locator.verify(&verifier, now_unix)?;
// 邀请值同理,返回 VerifiedRelayRoute(定位符 + 承载能力)
let route: VerifiedRelayRoute = invite.verify(&verifier, now_unix)?;
验证器通过 RelayLocatorVerifier trait 注入(locator.rs):
pub trait RelayLocatorVerifier {
fn verify(
&self,
key_id: &LocatorKeyId,
canonical_signing_bytes: &[u8],
signature: &[u8; 64],
) -> bool;
}
verify 内部先校验配对时间窗口,再对 268 字节规范签名区验签(locator.rs)。得到的 VerifiedRelayLocator / VerifiedRelayRoute 类型门控出站 ClientHello 的构造——RelayClientHello::new 只接受 &VerifiedRelayRoute,从类型层面杜绝了用未验证定位符发起连接的可能。
时间窗口校验
validate_pairing_window(locator.rs)是一套非常严格的边界约束:
now < not_before→NotYetValid;expires_at <= now→Expired;- 剩余有效期超过 1 小时 →
ExpiryTooFarFuture; - 声明有效期超过 1 小时 →
ValidityWindowTooLong。
即定位符的生命周期被硬性限制在 1 小时内,服务器端同样受此约束(MAX_PAIRING_LIFETIME_SECS 被 auth.rs 引入)。测试 locator_server_time_window_is_bounded 完整覆盖了这些分支。
服务器侧必须执行的完整检查清单
文档明确要求中继服务器在配对(pairing)之前依次完成:验证定位符签名与时间窗口、验证 bearer 授权票据及其对 caller_device_dh_pub_x25519 的设备绑定、验证任何占有证明(possession proof)、并应用速率与连接限制。服务端实现见 auth.rs 的 RelayAuthenticator 与 RequireRelayChallengeProof。
RelayRegion 的语义:home relay 不等于 peer 所在位置
RelayRegion::Cn 与 RelayRegion::Global 描述定位符的归属中继(home relay),编码为 1 与 2(locator.rs)。它们不约束对端实际运行在哪里:只要策略与网络可达性允许,海外对端同样可以连入中国区中继。
挑战绑定证明 v2(Challenge-bound proof v2)
背景:为什么需要 v2
认证模式 2(RelayHelloAuthMode::ChallengeBoundX25519V2)取代了 v1 的可重用占有证明(reusable possession attestation,模式 1 的 SignedLocatorAndBearerTicketV1)。v1 证明可重放,而 v2 将证明绑定到调用方与中继之间的 X25519 共享秘密与一次性服务器挑战上,每次认证都不可重放。
服务器挑战的线格式
中继在 HTTP 响应头中下发挑战,头名为:
openpencil-relay-challenge
其规范值为 oprc1_ 前缀加上无填充 base64url 编码的以下二进制串:
[challenge_version=1][key_id_length:u8][key_id:1..30 graphic ASCII][nonce:32]
对应源码常量(challenge.rs):
RELAY_CHALLENGE_PREFIX = "oprc1_"MAX_RELAY_CHALLENGE_KEY_ID_BYTES = 30RELAY_CHALLENGE_NONCE_BYTES = 32MAX_RELAY_CHALLENGE_HEADER_BYTES = 92
挑战的 nonce 与 X25519 共享秘密结果都必须非零(全零 nonce 返回 ZeroChallengeNonce,非贡献性共享秘密返回 NonContributoryX25519SharedSecret),防止恶意对端构造退化输入。
v2 证明的 33 字节线格式
一个 v2 证明恰好 33 字节:
[proof_version=2][HMAC-SHA256 tag:32]
即首字节为版本 2,随后是 32 字节 HMAC-SHA256 标签(RELAY_CHALLENGE_PROOF_V2_BYTES = 33)。RelayChallengeProofV2::decode 严格要求恰好 33 字节,多一字节、少一字节、版本不符都会被拒绝。
互操作推导细节
文档给出的权威推导如下:
bearer_hash = SHA256(exact bearer-token bytes)
normalized_hello = fixed 501-byte hello with byte [68] and range [69,165) zeroed
binding = SHA256(
"openpencil/op-collab-relay-protocol/challenge-proof-binding/v2\x00" ||
u16be(challenge_binary_length) ||
challenge_binary ||
bearer_hash ||
normalized_hello
)
info =
"openpencil/op-collab-relay-protocol/challenge-proof-key/v2\x00" ||
0x01 || key_id_length || key_id
okm = HKDF-SHA256(
ikm = X25519_shared_secret,
salt = nonce,
info = info,
length = 32
)
tag = HMAC-SHA256(okm, binding)
源码中的对应实现(challenge.rs)与其一一对应:
PROOF_BINDING_DOMAIN = b"openpencil/op-collab-relay-protocol/challenge-proof-binding/v2\0"与PROOF_KEY_INFO_DOMAIN = b"openpencil/op-collab-relay-protocol/challenge-proof-key/v2\0"提供域分离,杜绝跨用途密钥混淆;bearer_hash用Zeroizing包装的 SHA256(对精确 bearer 字节求哈希,避免把原始票据带入绑定);normalized_hello由RelayClientHello::challenge_proof_binding_bytes()产生(control.rs),它将 proof 长度字节(偏移 68)与 proof 槽(偏移 69..165)清零,其余 501 字节全部保留;- HKDF 以 nonce 为 salt、以 X25519 共享秘密为 IKM,info 中显式编码挑战版本与 key ID,扩展出 32 字节
okm; - 最终标签由
HMAC-SHA256(okm, binding)得出,验证端通过verify_slice以常量时间比较(challenge.rs)。
清零完整 proof 槽:消除循环依赖
一个关键的设计问题是:证明本身存在于 ClientHello 内部,若证明参与自身绑定计算会形成循环依赖。解决方法是把整个 proof 槽清零后再参与绑定——normalized_hello 中偏移 68 的 proof 长度字节与 [69,165) 的 proof 区域全部归零。这样既移除了循环依赖,又完整保留了协议版本、扩展版本、角色(role)、调用方 DH 公钥、路由能力与签名定位符在绑定中的作用。也就是说,证明被绑定到了「除证明自身之外」的整个 hello 上。
测试 challenge.rs 的 proof_binding_normalizes_only_length_and_proof_slot 直接验证了这一点:同一挑战与共享秘密下,无 proof 模板 hello 与携带 proof 的 hello 计算出的绑定摘要完全相同;而 proof_binds_challenge_bearer_and_every_hello_route_field 则证明:只要角色、调用方 DH、路由能力或 route ID 中任何一个字段不同,证明验证必然失败。此外,挑战 key ID、nonce、bearer 字节或共享秘密任一变化都会导致 ChallengeProofVerificationFailed。
服务端如何落地验证
在 auth.rs 中,生产策略 RequireRelayChallengeProof<B> 完整实现了文档要求:通过外部/HSM 能力的 X25519 边界(RelayServerX25519ProofBoundary)选择活动 key ID、要求认证模式必须是 v2、从 hello 中解码 33 字节证明,并将挑战、调用方 DH 公钥、票据与 hello 交给边界验证。挑战对象 RelayUpgradeChallenge 被设计为不可克隆、单次消费(consume_if_fresh 校验过期时间),即使验证失败也会被消费,从状态机上防止挑战重用。
配套协议原语:ClientHello、拒绝码与在线重认证
501 字节定长 ClientHello
RelayClientHello 是固定 RELAY_CLIENT_HELLO_BYTES = 501 字节的消息(control.rs),布局为:协议版本、角色(Owner=1/Guest=2)、认证模式(1/2)、认证扩展版本、32 字节调用方 X25519 DH 公钥、32 字节路由能力、proof 长度字节(偏移 68)、proof 槽([69,165))、签名定位符二进制([165,501))。proof 槽之后的保留区必须全零。服务端拒绝码 RelayRejectCode 覆盖 14 种情况(MalformedHello 到 Internal),RelayServerStatus 以 3 字节编码 Ready/Paired/Rejected(code)。
在线重认证(reauth)
reauth.rs 提供连接建立后的在线重认证控制消息:oprrc1_ 前缀的挑战与 oprrr1_ 前缀的响应。重认证强制要求 hello 使用 v2 模式且携带完整的 33 字节挑战证明(ReauthRequiresChallengeProof),bearer 存储于 Zeroizing<Vec<u8>> 且响应类型不可克隆,MAX_RELAY_BEARER_BYTES 与认证桥的票据上限对齐。
短配对码
pairing.rs 解决了 503 字符邀请无法口头/跨肩传输的问题:10 位 Crockford base32 配对码(首位标识 region,其余 9 位随机,45 位熵),code_id(存储键)与密封密钥由同一规范码的独立 BLAKE3 派生,密封 blob 采用 encrypt-then-MAC 结构。文档同时诚实指出其威胁模型:在线猜测者面对 2^45 空间与服务端 TTL/限流不可行,但持有 blob 的控制平面操作者可以离线暴力破解短码——因此短码对存储操作者不具备机密性与真实性,会话准入仍依赖后续的已认证 guest 与 owner 确认门。
测试与互操作性保障
crate 的测试套件把文档承诺逐条固化为可执行断言:
- protocol.rs:定位符/邀请的固定规范往返、显式验证 fail-closed、时间窗口边界、截断与尾随字节拒绝、region/版本/秘密字段篡改拒绝、非规范文本拒绝、
Debug全量脱敏; - challenge.rs:挑战头规范性与长度上限、v2 证明 33 字节精确性、绑定摘要的固定测试向量、多字段绑定敏感性与非贡献性共享秘密拒绝;
- reauth.rs:重认证控制消息的规范往返与脱敏。
这些测试同时充当跨组件互操作的契约锚点:服务端测试(tests.rs、production_auth_tests.rs)直接复用本 crate 的挑战与证明类型构造真实认证流程,验证了「客户端推导 → 服务端验证」的端到端一致性。
总结与工程启示
回顾整个设计,op-collab-relay-protocol 的核心工程原则可以提炼为三点:
- 元数据与凭证分离:
opcl1_定位符可公开分发,32 字节承载能力单独保管,opc1_邀请值视为机密并受 URL 位置约束; - 解码不等于信任:所有解码 API 返回未验证数据,
VerifiedRelayLocator/VerifiedRelayRoute从类型层面门控后续流程,服务端在配对前执行签名、时间窗、票据绑定、占有证明与限流的完整检查; - 证明不可重放:v2 挑战绑定证明以一次性 nonce 与 X25519 共享秘密为根,通过域分离的 HKDF/HMAC 链绑定到规范化 hello,并用「清零 proof 槽」化解循环依赖。
该协议以 MIT 许可开源(见 LICENSE),实现集中在 lib.rs 及其兄弟模块中,是理解 OpenPencil 协作中继安全边界的最佳切入点。