署名と AAD
Ed25519 署名と AEAD の追加認証データ:入口、バイト形式、理由、具体例。
API 署名
これらの項目は Ed25519 署名を使用します。各署名対象配列の先頭要素は SignaturePurpose 値です。異なる操作の証明を区別するもので、独立した通信フィールドではありません。
暗号化された HTTP /graphql、/guest_graphql リクエストと WSS /graphql フレームは、Ed25519 署名なしでセッション AEAD タグを使用します。/graphql への API トークンリクエストは Bearer 認証を使用します。以下の項目で、どのリクエスト、レスポンス、ネストしたペイロードに署名を含めるかを示します。
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- 署名する理由
- デバイス ID、クライアント ID、両方のハンドシェイクメッセージを結び付けます。ブラウザーは、パスワードなしの承認チャネルキーを導出する前に、署名済み ServerHello を確認します。
- 署名と検証の担当
- デバイスが ServerHello に署名し、接続するブラウザーまたはクライアントがデバイスの ID 公開鍵で検証します。
- 署名対象の JSON 配列
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- 署名する理由
- リクエストの暗号化に加え、送信デバイスを認証します。元の GraphQL リクエストとそのチャネルコンテキストを結び付け、証明を別のチャネルへ移せないようにします。リクエスト UUIDv7 の鮮度は別途確認します。
- 署名と検証の担当
- 送信ピアがリクエストに署名し、受信ピアが保存済みの送信者 ID 公開鍵で検証します。
- 署名対象の JSON 配列
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId は配列の第 2 要素です。ピアへの直接リクエストでは空、それ以外では c-cid チャネル ID と完全一致します。署名を計算するときは、variables 内のオブジェクトのキーを再帰的に並べ替えます。
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- 署名する理由
- 要求元の ID、意図した受信者、デバイス詳細、ECDH 公開鍵を結び付けます。受信者は共有キーの導出前に変更を検出できます。QR スキャンでも同じ purpose で表示された招待を検証します。
- 署名と検証の担当
- 要求元デバイスが署名し、受信デバイスまたは QR スキャナーが招待の signaturePublicKey で検証します。ユーザー確認または信頼済み ID との照合は引き続き必要です。
- 署名対象の JSON 配列
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- 署名する理由
- 承認デバイスの ECDH 公開鍵と接続詳細を、1 つの requestId に結び付けます。無関係または改ざんされた承認では、保留中のペアリングを完了できません。
- 署名と検証の担当
- 承認デバイスが署名し、要求元デバイスが期待するピアの ID 公開鍵で検証します。
- 署名対象の JSON 配列
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- 署名する理由
- 保留中のリクエストを拒否した相手を認証します。送信するのは requestId と signature のみで、拒否によって共有キーは確立されません。
- 署名と検証の担当
- 拒否デバイスが署名し、要求元デバイスが期待するピアの ID 公開鍵で検証します。
- 署名対象の JSON 配列
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- 署名する理由
- スキャナーの ID と承認詳細を、正確にそのスキャン済み招待に結び付けます。外側の 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 はスキャナーの ID と名前を含む PAIRING_ACCEPT 配列のコンパクトな JSON 文字列です。スキャナーは内側の配列に直接署名せず、QR_PAIR_ACCEPT 配列に署名します。HMAC キーは request.signature の UTF-8 文字列であり、その Base64 デコード結果のバイト列ではありません。
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- 署名する理由
- キャンセルを認証し、元の requestSignature と両デバイスに結び付け、別のペアリング試行をキャンセルできないようにします。
- 署名と検証の担当
- キャンセルするデバイスが署名し、受信デバイスが ID を検証して保留中のリクエストと照合します。
- 署名対象の JSON 配列
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- 署名する理由
- 接続するピアを認証し、その証明をこの接続の完全な暗号化済み init および ack フレームに結び付け、接続間の再利用を防ぎます。
- 署名と検証の担当
- 接続するピアがクライアントの証明に署名し、ステータスサーバーが保存済みピア ID 公開鍵で検証します。
- 署名対象の JSON 配列
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- 署名する理由
- 外側のピアリクエスト署名に加え、システムメッセージのペイロード内に検証可能なメンバー資格の証明を含めます。チャネル、バージョン、操作、対象を結び付け、受信者は所有者・メンバー権限を別途適用します。
- 署名と検証の担当
- 操作に応じて所有者または操作するメンバーが署名し、受信メンバーが対応する ID と権限を検証します。
- 署名対象の JSON 配列
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- 署名する理由
- 通知された TLS 証明書の SHA-256 フィンガープリントを、デバイス ID に結び付けます。管理対象のピアプロキシは、その証明書フィンガープリントを信頼する前にこの証明を検証します。
- 署名と検証の担当
- デバイスが /init レスポンスの tlsCertificateSignature に署名し、接続する管理対象プロキシが期待するデバイス ID 公開鍵で検証します。
- 署名対象の JSON 配列
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose は項目見出しの値を意味します。示された配列をコンパクトな JSON にシリアライズし、UTF-8 でエンコードしてから、送信者の Ed25519 ID 鍵で署名します。signature は Base64 です。フィールド順、型、元の JSON 文字列を変更しないでください。署名は署名者を識別し、鮮度と権限は別途確認されます。
AAD リファレンス
AAD は暗号文とともに認証されますが、暗号化されず、独立したフレームフィールドとして追加もされません。両側で同じバイト列を再構成し、不一致があるとタグ検証に失敗します。例では、このドキュメントの合成認証データと WebSocket フレームを再利用します。
式中の二重縦線はバイト列の連結を示します。0x00 は 1 個のゼロバイトです。fields(x₁, …, xₙ) は、それぞれの uint32be(byteLength(xᵢ)) とその後の xᵢ を連結します。SHA256 は生の 32 バイトを返し、hex は表示専用です。JSON.stringify は、指定されたフィールド順のコンパクトな JSON を意味します。WebSocket の各方向は、それぞれシーケンス 1 から開始します。
WSS /auth · パスワードログイン
AUTH_REQUEST / AUTH_RESPONSE暗号化されたクライアント情報と承認結果を、このクライアントおよびサーバーの ID に結び付け、リクエストとレスポンスの方向を区別します。
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 のパスとクライアント ID に結び付けます。
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 フレーム、パス、クライアント ID に結び付けます。
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 でタグを検証します。平文は 0x00 + SHA256(original encrypted request) + response 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リソース URL · /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