簽章與 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 頻道 ID 完全一致。計算簽章時,對 variables 內各層物件的鍵排序。
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- 為何需要簽章
- 綁定發起方身分、預定接收方、裝置資訊與 ECDH 公開金鑰。接收方能在衍生共用金鑰前偵測變更;掃描 QR 碼時也以相同 purpose 驗證顯示的邀請。
- 簽署與驗證
- 發起裝置簽署;接收裝置或 QR 掃描方以邀請中的 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。
- 簽署與驗證
- 掃描裝置簽署;顯示 QR 碼的裝置以回應中掃描方的 signaturePublicKey 驗證,並檢查與原邀請的綁定。
- 簽署的 JSON 陣列
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
接受 QR 邀請時,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
- 為何需要簽章
- 除了外層對端請求簽章,也在系統訊息內容中攜帶可驗證的成員資格證明。綁定頻道、版本、動作與目標;接收方另行執行擁有者及成員權限檢查。
- 簽署與驗證
- 依動作由擁有者或操作成員簽署;接收成員驗證對應身分與權限。
- 簽署的 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 訊框。
公式中的雙豎線表示位元組串接。0x00 表示一個零值位元組。fields(x₁, …, xₙ) 為每項串接 uint32be(byteLength(xᵢ)),接著串接 xᵢ。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 || digestOPAQUE Rust/WASM 登入結果會回傳 requestAad 與 responseAad。呼叫端直接使用,無須建構內部脈絡。digest 是其中的 32 位元組摘要部分,不是額外的請求欄位。LOGIN_PASSWORD 固定於登入函式庫內部;呼叫端不提供 purpose 參數。
具體輸入與 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 固定於登入函式庫內部;呼叫端不提供 purpose 參數。
具體輸入與 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。
加密回應以空白 AAD 驗證 tag。明文為 0x00 + SHA256(原始加密請求) + 回應 JSON;用戶端解密後會核對請求摘要。
具體輸入與 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