签名与 AAD
Ed25519 签名与 AEAD 附加认证数据:使用入口、字节格式、理由和具体示例。
API 签名
以下入口使用 Ed25519 签名。被签数组的第一项是对应的 SignaturePurpose 值,用于区分操作,防止同一份证明被用于其他用途;它不是单独传输的字段。
HTTP /graphql、/guest_graphql 的加密请求和 WSS /graphql 帧使用会话 AEAD tag,不附带 Ed25519 签名。/graphql 的 API token 请求使用 Bearer 认证。下列条目分别说明签名位于请求、响应还是内层数据。
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- 为什么需要签名
- 绑定设备身份、客户端 ID 和双方握手消息。浏览器先验证 ServerHello,再派生无密码确认通道的密钥。
- 谁签名、谁验签
- 设备签名 ServerHello;连接的浏览器或客户端使用设备身份公钥验签。
- 被签 JSON 数组
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- 为什么需要签名
- 加密之外还要确认发送设备的身份。签名绑定原始 GraphQL 请求和频道上下文,防止将证明移到另一频道;请求 UUIDv7 的时效另行校验。
- 谁签名、谁验签
- 发送设备签名请求;接收设备使用已保存的发送方身份公钥验签。
- 被签 JSON 数组
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
第二项是 channelId:设备直连时为空字符串;频道请求时必须与 c-cid 完全一致。计算签名时,对 variables 内各层对象的键排序。
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- 为什么需要签名
- 绑定发起方身份、目标设备、设备信息和 ECDH 公钥。接收方在派生共享密钥前检查数据是否被篡改;扫描二维码时也用此用途验证展示的邀请。
- 谁签名、谁验签
- 发起设备签名;接收设备或扫码方使用邀请中的 signaturePublicKey 验签。仍需用户确认或匹配可信身份。
- 被签 JSON 数组
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- 为什么需要签名
- 将同意方的 ECDH 公钥和连接信息绑定到指定 requestId,防止无关或被篡改的同意消息完成当前配对。
- 谁签名、谁验签
- 同意设备签名;发起设备使用预期对端的身份公钥验签。
- 被签 JSON 数组
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- 为什么需要签名
- 确认拒绝消息来自预期设备。传输数据只有 requestId 和 signature;拒绝不建立共享密钥。
- 谁签名、谁验签
- 拒绝设备签名;发起设备使用预期对端的身份公钥验签。
- 被签 JSON 数组
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- 为什么需要签名
- 将扫码方身份和同意数据绑定到本次扫描的邀请。外层 Ed25519 签名证明扫码方身份,HMAC 将回复与 request.signature 绑定。
- 谁签名、谁验签
- 扫码设备签名;展示二维码的设备使用回复中的扫码方 signaturePublicKey 验签,并检查与原邀请的绑定。
- 被签 JSON 数组
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
二维码接受流程中,acceptSignedArrayJSON 是 PAIRING_ACCEPT 数组的紧凑 JSON 字符串,包含扫码方身份和名称。扫码方签名的是外层 QR_PAIR_ACCEPT 数组,不直接签内层数组。HMAC 的密钥是 request.signature 字符串的 UTF-8 字节,不是 Base64 解码后的字节。
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- 为什么需要签名
- 确认取消方身份,并绑定原始 requestSignature 和双方设备,防止取消其他配对尝试。
- 谁签名、谁验签
- 取消设备签名;接收设备验签并匹配当前待处理请求。
- 被签 JSON 数组
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- 为什么需要签名
- 确认连接方身份,并将证明绑定到本次连接的完整加密 init、ack 帧,防止跨连接复用。
- 谁签名、谁验签
- 连接设备签名客户端证明;状态服务端使用已保存的对端身份公钥验签。
- 被签 JSON 数组
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- 为什么需要签名
- 在外层 peer 请求签名之外,系统消息内还携带可验证的成员操作证明。签名绑定频道、版本、动作和目标;接收方另行检查所有者或成员权限。
- 谁签名、谁验签
- 按动作由频道所有者或操作成员签名;接收成员验证对应身份和权限。
- 被签 JSON 数组
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- 为什么需要签名
- 将公布的 TLS 证书 SHA-256 指纹绑定到设备身份。受管设备代理连接时,先验证此证明再信任该证书指纹。
- 谁签名、谁验签
- 设备在 /init 响应中签名 tlsCertificateSignature;建立连接的受管代理使用预期设备身份公钥验签。
- 被签 JSON 数组
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose 表示条目标题中的用途值。将数组序列化为紧凑 JSON,按 UTF-8 编码后,用签名方的 Ed25519 身份私钥签名;signature 使用 Base64。必须保持字段顺序、类型和原始 JSON 字符串。签名证明身份;时效和权限另行校验。
AAD 一览
AAD 与密文一起参与认证,但不被加密,也不作为独立字段附加在帧内。双方各自构造相同字节;不一致就无法通过 tag 校验。以下复用文档中的认证和 WebSocket 合成帧,展示实际输入与完整 AAD。
公式中的双竖线表示字节拼接。0x00 表示一个零字节。fields(x₁, …, xₙ) 为每项拼接 uint32be(该项字节数),然后接该项字节。SHA256 返回 32 字节原始摘要;hex 仅用于展示。JSON.stringify 表示按指定字段顺序生成的紧凑 JSON。WebSocket 双向序号各自从 1 开始。
WSS /auth · 密码登录
AUTH_REQUEST / AUTH_RESPONSE将加密的客户端信息和确认结果绑定到本次客户端与服务端身份,并区分请求、响应方向。
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest完整 AAD 由 OPAQUE Rust/WASM 登录结果返回;调用方直接使用 requestAad、responseAad,无需构造内部上下文。digest 是其中的 32 字节摘要部分,不是额外请求字段。 LOGIN_PASSWORD 是登录库内部固定的用途标识,调用方不传入此参数。
具体输入与 AAD 字节
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · 无密码登录
AUTH_REQUEST / AUTH_RESPONSE将加密确认消息绑定到本次握手,包括双方临时公钥和已签名的服务端回复。
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest握手库内部维护 AAD;调用方使用 encryptRequest、decryptResponse,无需构造内部上下文。digest 是其中的 32 字节摘要部分,不是额外请求字段。 LOGIN_NO_PASSWORD 是登录库内部固定的用途标识,调用方不传入此参数。
具体输入与 AAD 字节
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 44 B
415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafdirection = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 45 B
415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafWSS /graphql、/screen、/image_editor、/status · init
WS_INIT将注册帧绑定到 WebSocket 路径和客户端身份。
fields(WS_INIT, path, cid)path 是逻辑路径,不含协议、主机和查询参数。cid 使用 URL 编码前的原始客户端 ID。示例采用 /graphql。
具体输入与 AAD 字节
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql、/screen、/image_editor、/status · ack
WS_ACK将确认帧绑定到收到的那条加密 init 帧、路径和客户端身份。
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame 是完整二进制 nonce + ciphertext + tag,不是解密后的 init JSON。SHA256(initFrame) 以 32 字节原始摘要参与拼接。
具体输入与 AAD 字节
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql、/screen、/image_editor、/status · 加密消息帧
WS_FRAME将每帧绑定到本连接握手、发送方向和序号,防止跨连接或跨方向复用。
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame、ackFrame 均为完整加密二进制帧。direction 按发送方取 client 或 server。sequence 是 8 字节大端整数;示例分别展示两个方向独立的序号 1,也适用于空确认帧。
具体输入与 AAD 字节
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = client
sequence = 1AAD · hex · 122 B
0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006636c69656e74000000080000000000000001path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = server
sequence = 1AAD · hex · 122 B
0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006736572766572000000080000000000000001HTTP · 加密请求
HTTP_REQUEST将加密数据绑定到逻辑 HTTP 方法和路径,防止跨 REST 入口复用。
HTTP_REQUEST.{method}.{endpoint}POST /graphql、/guest_graphql、/peer_graphql、/init、/upload 和 /upload_chunk 均使用 HTTP_REQUEST。多段表单上传会绑定加密的 info 元数据。Proxy/BLE/Aware 转发使用逻辑目标路径,而非代理 URL。
加密响应仍校验 tag;明文为 0x00 + SHA256(原始加密请求) + 响应 JSON,AAD 参数为空。客户端解密后核对请求摘要。
具体输入与 AAD 字节
method = POST
endpoint = /graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./graphql"AAD · hex · 26 B
485454505f524551554553542e504f53542e2f6772617068716cmethod = POST
endpoint = /guest_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./guest_graphql"AAD · hex · 32 B
485454505f524551554553542e504f53542e2f67756573745f6772617068716cmethod = POST
endpoint = /peer_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./peer_graphql"AAD · hex · 31 B
485454505f524551554553542e504f53542e2f706565725f6772617068716cmethod = POST
endpoint = /init
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./init"AAD · hex · 23 B
485454505f524551554553542e504f53542e2f696e6974method = POST
endpoint = /upload
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload"AAD · hex · 25 B
485454505f524551554553542e504f53542e2f75706c6f6164method = POST
endpoint = /upload_chunk
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload_chunk"AAD · hex · 31 B
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6b资源链接 · /fs、/zip/*、/proxy/*
FS / ZIP_FILES将 URL 内的加密数据绑定到用途、会话或分享范围及其所有者。
{purpose}.{mode}.{owner}FS 用于文件预览、目录下载、代理资源和附件引用;ZIP_FILES 用于文件选择打包下载。mode 为会话 c 或分享 s,owner 为会话客户端 ID 或分享 ID。
具体输入与 AAD 字节
purpose = FS
mode = c
owner = 706c6169-3b80-8f42-9a61-4e312e54d001
AAD (escaped UTF-8) = "FS.c.706c6169-3b80-8f42-9a61-4e312e54d001"AAD · hex · 41 B
46532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031purpose = FS
mode = s
owner = 01a1cd7b-b900-7331-9331-313131313134
AAD (escaped UTF-8) = "FS.s.01a1cd7b-b900-7331-9331-313131313134"AAD · hex · 41 B
46532e732e30316131636437622d623930302d373333312d393333312d333133313331333133313334purpose = ZIP_FILES
mode = c
owner = 706c6169-3b80-8f42-9a61-4e312e54d001
AAD (escaped UTF-8) = "ZIP_FILES.c.706c6169-3b80-8f42-9a61-4e312e54d001"AAD · hex · 48 B
5a49505f46494c45532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031