API リファレンス

署名と 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 に結び付け、リクエストとレスポンスの方向を区別します。

text
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest

OPAQUE Rust/WASM のログイン結果は requestAad と responseAad を返します。内部コンテキストを組み立てず、そのまま使用してください。digest は 32 バイトのダイジェスト部分であり、追加のリクエストフィールドではありません。LOGIN_PASSWORD はログインライブラリ内部で固定されており、呼び出し元が purpose パラメーターを指定することはありません。

具体的な入力と AAD バイト列

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
text
direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · パスワードなしのログイン
AUTH_REQUEST / AUTH_RESPONSE

暗号化された承認メッセージを、両側の一時公開鍵および署名済みサーバーレスポンスを含む、このハンドシェイクに結び付けます。

text
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 バイト列

text
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf

AAD · hex · 44 B

415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf
text
direction = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf

AAD · hex · 45 B

415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf
WSS /graphql, /screen, /image_editor, /status · init
WS_INIT

登録を WebSocket のパスとクライアント ID に結び付けます。

text
fields(WS_INIT, path, cid)

path はスキーム、ホスト、クエリを含まない論理パスです。cid は URL エンコード前の元のクライアント ID です。例では /graphql を使用します。

具体的な入力と AAD バイト列

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001

AAD · hex · 63 B

0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031
WSS /graphql, /screen, /image_editor, /status · ack
WS_ACK

確認応答を、正確な暗号化済み init フレーム、パス、クライアント ID に結び付けます。

text
fields(WS_ACK, path, cid, SHA256(initFrame))

initFrame は nonce + ciphertext + tag からなる完全なバイナリであり、デコード済みの init JSON ではありません。SHA256(initFrame) は生の 32 バイトとして含まれます。

具体的な入力と AAD バイト列

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · 暗号化フレーム
WS_FRAME

各フレームを、その接続のハンドシェイク、送信方向、シーケンスに結び付け、別の接続や方向での再利用を防ぎます。

text
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))

initFrame と ackFrame は完全な暗号化バイナリフレームです。direction は送信者に応じて client または server です。sequence はビッグエンディアンの 8 バイトでエンコードします。例では、空の確認フレームも含め、独立した両方向に 1 を示しています。

具体的な入力と AAD バイト列

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = client
sequence = 1

AAD · hex · 122 B

0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006636c69656e74000000080000000000000001
text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = server
sequence = 1

AAD · hex · 122 B

0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006736572766572000000080000000000000001
HTTP · 暗号化リクエスト
HTTP_REQUEST

暗号化データを、その論理 HTTP メソッドおよびエンドポイントに結び付け、別の REST エンドポイントでの再利用を防ぎます。

text
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 バイト列

text
method = POST
endpoint = /graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./graphql"

AAD · hex · 26 B

485454505f524551554553542e504f53542e2f6772617068716c
text
method = POST
endpoint = /guest_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./guest_graphql"

AAD · hex · 32 B

485454505f524551554553542e504f53542e2f67756573745f6772617068716c
text
method = POST
endpoint = /peer_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./peer_graphql"

AAD · hex · 31 B

485454505f524551554553542e504f53542e2f706565725f6772617068716c
text
method = POST
endpoint = /init
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./init"

AAD · hex · 23 B

485454505f524551554553542e504f53542e2f696e6974
text
method = POST
endpoint = /upload
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload"

AAD · hex · 25 B

485454505f524551554553542e504f53542e2f75706c6f6164
text
method = 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 ペイロードを、その用途、セッションまたは共有のスコープ、所有者に結び付けます。

text
{purpose}.{mode}.{owner}

FS はファイルプレビュー、ディレクトリダウンロード、プロキシリソース、添付参照に対応し、ZIP_FILES はアーカイブ対象の選択に対応します。mode はセッションの場合 c、共有の場合 s です。owner はセッションのクライアント ID または共有 ID です。

具体的な入力と AAD バイト列

text
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

46532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031
text
purpose = FS
mode = s
owner = 01a1cd7b-b900-7331-9331-313131313134
AAD (escaped UTF-8) = "FS.s.01a1cd7b-b900-7331-9331-313131313134"

AAD · hex · 41 B

46532e732e30316131636437622d623930302d373333312d393333312d333133313331333133313334
text
purpose = 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