Signaturen und AAD
Ed25519-Signaturen und zusätzliche authentifizierte AEAD-Daten: Endpunkte, Byteformate, Gründe und konkrete Beispiele.
API-Signaturen
Diese Einträge verwenden Ed25519-Signaturen. Das erste Element jedes signierten Arrays ist der jeweilige SignaturePurpose-Wert. Er trennt Nachweise verschiedener Operationen und ist kein separates Übertragungsfeld.
Verschlüsselte HTTP-Anfragen an /graphql und /guest_graphql sowie WSS-Frames an /graphql verwenden AEAD-Tags der Sitzung ohne Ed25519-Signatur. API-Token-Anfragen an /graphql verwenden Bearer-Authentifizierung. Die folgenden Einträge zeigen, welche Anfrage, Antwort oder innere Nutzlast eine Signatur trägt.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Grund für die Signatur
- Bindet die Geräteidentität, die Client-ID und beide Handshake-Nachrichten. Der Browser prüft das signierte ServerHello, bevor er den Schlüssel des passwortlosen Bestätigungskanals ableitet.
- Signieren und Prüfen
- Das Gerät signiert ServerHello; der verbindende Browser oder Client prüft die Signatur mit dem öffentlichen Identitätsschlüssel des Geräts.
- Signiertes JSON-Array
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Grund für die Signatur
- Authentifiziert neben der Verschlüsselung die Identität des sendenden Geräts. Bindet die ursprüngliche GraphQL-Anfrage und ihren Kanalkontext, damit der Nachweis nicht in einen anderen Kanal verschoben werden kann. Die UUIDv7-Zeit wird separat geprüft.
- Signieren und Prüfen
- Das sendende Gerät signiert die Anfrage; das empfangende Gerät prüft mit dem gespeicherten öffentlichen Identitätsschlüssel des Senders.
- Signiertes JSON-Array
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId ist das zweite Arrayelement: leer bei direkten Geräteanfragen, andernfalls exakt die Kanal-ID aus c-cid. Für die Signatur alle Objektschlüssel in variables rekursiv sortieren.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Grund für die Signatur
- Bindet anfragende Identität, vorgesehenen Empfänger, Gerätedetails und öffentlichen ECDH-Schlüssel. Der Empfänger erkennt Änderungen vor der Schlüsselableitung; beim QR-Scannen wird die angezeigte Einladung mit demselben Zweck geprüft.
- Signieren und Prüfen
- Das anfragende Gerät signiert; das empfangende Gerät oder der QR-Scanner prüft mit signaturePublicKey aus der Einladung. Benutzerbestätigung oder Abgleich mit einer vertrauenswürdigen Identität bleibt erforderlich.
- Signiertes JSON-Array
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Grund für die Signatur
- Bindet den öffentlichen ECDH-Schlüssel und die Verbindungsdaten des annehmenden Geräts an eine requestId. Eine fremde oder veränderte Annahme kann die ausstehende Kopplung nicht abschließen.
- Signieren und Prüfen
- Das annehmende Gerät signiert; das anfragende Gerät prüft mit dem erwarteten öffentlichen Identitätsschlüssel des Gegenübers.
- Signiertes JSON-Array
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Grund für die Signatur
- Authentifiziert, wer die ausstehende Anfrage abgelehnt hat. Übertragen werden nur requestId und signature; die Ablehnung erzeugt keinen gemeinsamen Schlüssel.
- Signieren und Prüfen
- Das ablehnende Gerät signiert; das anfragende Gerät prüft mit dem erwarteten öffentlichen Identitätsschlüssel des Gegenübers.
- Signiertes JSON-Array
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Grund für die Signatur
- Bindet Scanneridentität und Annahmedaten an die tatsächlich gescannte Einladung. Die äußere Ed25519-Signatur authentifiziert den Scanner; HMAC bindet die Antwort an request.signature.
- Signieren und Prüfen
- Das scannende Gerät signiert. Das Gerät mit dem angezeigten QR-Code prüft mit signaturePublicKey aus der Antwort und kontrolliert die Bindung an die gescannte Anfrage.
- Signiertes JSON-Array
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
Bei QR-Annahme ist acceptSignedArrayJSON die kompakte JSON-Zeichenfolge des PAIRING_ACCEPT-Arrays einschließlich Identität und Name des Scanners. Der Scanner signiert das äußere QR_PAIR_ACCEPT-Array, nicht direkt das innere Array. Der HMAC-Schlüssel ist die UTF-8-Zeichenfolge request.signature, nicht deren Base64-dekodierte Bytes.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Grund für die Signatur
- Authentifiziert den Abbruch und bindet ihn an die ursprüngliche requestSignature und beide Geräte. Verhindert den Abbruch eines anderen Kopplungsversuchs.
- Signieren und Prüfen
- Das abbrechende Gerät signiert; der Empfänger prüft die Identität und den Bezug zur ausstehenden Anfrage.
- Signiertes JSON-Array
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Grund für die Signatur
- Authentifiziert das verbindende Gerät und bindet dessen Nachweis an die vollständigen verschlüsselten init- und ack-Frames dieser Verbindung. Verhindert die Wiederverwendung in anderen Verbindungen.
- Signieren und Prüfen
- Das verbindende Gerät signiert den Clientnachweis; der Statusserver prüft mit dessen gespeichertem öffentlichem Identitätsschlüssel.
- Signiertes JSON-Array
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Grund für die Signatur
- Überträgt zusätzlich zur äußeren Geräteanfragesignatur einen prüfbaren Mitgliedschaftsnachweis innerhalb der Systemnachricht. Bindet Kanal, Version, Aktion und Ziel; der Empfänger prüft Eigentümer- und Mitgliederberechtigungen separat.
- Signieren und Prüfen
- Je nach Aktion signiert der Eigentümer oder das handelnde Mitglied. Das empfangende Mitglied prüft die zugehörige Identität und Berechtigung.
- Signiertes JSON-Array
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Grund für die Signatur
- Bindet den veröffentlichten SHA-256-Fingerabdruck des TLS-Zertifikats an die Geräteidentität. Ein Proxy für verwaltete Geräte prüft diesen Nachweis, bevor er dem Fingerabdruck vertraut.
- Signieren und Prüfen
- Das Gerät signiert tlsCertificateSignature in der /init-Antwort. Der verbindende Verwaltungsproxy prüft mit dem erwarteten öffentlichen Geräteidentitätsschlüssel.
- Signiertes JSON-Array
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose ist der Wert im Eintragstitel. Das gezeigte Array als kompaktes JSON serialisieren, als UTF-8 kodieren und mit dem Ed25519-Identitätsschlüssel des Senders signieren; signature ist Base64. Feldreihenfolge, Typen und ursprüngliche JSON-Zeichenfolgen unverändert lassen. Die Signatur weist die Identität nach; Aktualität und Berechtigungen werden separat geprüft.
AAD-Referenz
AAD wird zusammen mit dem Geheimtext authentifiziert, aber weder verschlüsselt noch als eigenes Feld an den Frame angehängt. Beide Seiten bilden dieselben Bytes; jede Abweichung lässt die tag-Prüfung scheitern. Die Beispiele verwenden die synthetischen Authentifizierungs- und WebSocket-Frames dieser Dokumentation.
Der doppelte senkrechte Strich in Formeln bedeutet Byte-Verkettung. 0x00 ist ein Nullbyte. fields(x₁, …, xₙ) verkettet für jeden Wert uint32be(byteLength(xᵢ)) und anschließend xᵢ. SHA256 liefert 32 Rohbytes; hex dient nur der Anzeige. JSON.stringify bezeichnet kompaktes JSON in der angegebenen Feldreihenfolge. Jede WebSocket-Richtung beginnt ihre eigene Sequenz bei 1.
WSS /auth · Anmeldung mit Passwort
AUTH_REQUEST / AUTH_RESPONSEBindet verschlüsselte Clientinformationen und das Bestätigungsergebnis an diese Client- und Serveridentität und trennt Anfrage- und Antwortrichtung.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestDas OPAQUE-Anmeldeergebnis aus Rust/WASM liefert requestAad und responseAad. Direkt verwenden, ohne den internen Kontext selbst aufzubauen. digest ist der 32 Byte lange Hashanteil, kein zusätzliches Anfragefeld. LOGIN_PASSWORD ist in der Anmeldebibliothek festgelegt; Aufrufer übergeben keinen purpose-Parameter.
Konkrete Eingaben und AAD-Bytes
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · Anmeldung ohne Passwort
AUTH_REQUEST / AUTH_RESPONSEBindet verschlüsselte Bestätigungsnachrichten an diesen Handshake, einschließlich beider temporärer öffentlicher Schlüssel und der signierten Serverantwort.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestDie Handshake-Bibliothek verwaltet AAD intern. encryptRequest und decryptResponse verwenden, ohne den internen Kontext selbst aufzubauen. digest ist der 32 Byte lange Hashanteil, kein zusätzliches Anfragefeld. LOGIN_NO_PASSWORD ist in der Anmeldebibliothek festgelegt; Aufrufer übergeben keinen purpose-Parameter.
Konkrete Eingaben und AAD-Bytes
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 44 B
415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafdirection = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 45 B
415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafWSS /graphql, /screen, /image_editor, /status · init
WS_INITBindet die Registrierung an den WebSocket-Pfad und die Clientidentität.
fields(WS_INIT, path, cid)path ist der logische Pfad ohne Schema, Host oder Abfrageparameter. cid ist die ursprüngliche Client-ID vor der URL-Kodierung. Das Beispiel verwendet /graphql.
Konkrete Eingaben und AAD-Bytes
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKBindet die Bestätigung an den exakten verschlüsselten init-Frame, den Pfad und die Clientidentität.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame besteht vollständig aus den Binärdaten nonce + ciphertext + tag, nicht aus dem entschlüsselten init-JSON. SHA256(initFrame) geht als 32 Rohbytes ein.
Konkrete Eingaben und AAD-Bytes
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · verschlüsselte Frames
WS_FRAMEBindet jeden Frame an den Verbindungshandshake, die Senderichtung und die Sequenznummer. Verhindert die Wiederverwendung in einer anderen Verbindung oder Richtung.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame und ackFrame sind vollständige verschlüsselte Binärframes. direction ist je nach Sender client oder server. sequence wird als acht Big-Endian-Bytes kodiert; das Beispiel zeigt 1 für beide unabhängigen Richtungen, einschließlich des leeren Bestätigungsframes.
Konkrete Eingaben und AAD-Bytes
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 · verschlüsselte Anfragen
HTTP_REQUESTBindet verschlüsselte Daten an die logische HTTP-Methode und den Endpunkt und verhindert die Wiederverwendung an einem anderen REST-Endpunkt.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload und /upload_chunk verwenden HTTP_REQUEST. Bei Multipart-Uploads wird die verschlüsselte info-Metadatenstruktur gebunden. Die Weiterleitung über Proxy/BLE/Aware verwendet den logischen Zielpfad, nicht die Proxy-URL.
Verschlüsselte Antworten prüfen das tag mit leerem AAD. Ihr Klartext lautet 0x00 + SHA256(ursprüngliche verschlüsselte Anfrage) + Antwort-JSON; Clients prüfen nach dem Entschlüsseln den Anfrage-Hash.
Konkrete Eingaben und AAD-Bytes
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
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6bRessourcen-URLs · /fs, /zip/* und /proxy/*
FS / ZIP_FILESBindet verschlüsselte URL-Nutzdaten an ihren Zweck, ihren Sitzungs- oder Freigabebereich und dessen Eigentümer.
{purpose}.{mode}.{owner}FS gilt für Dateivorschauen, Verzeichnisdownloads, Proxy-Ressourcen und Anhangsverweise; ZIP_FILES für die Dateiauswahl zum Archivieren. mode ist c für eine Sitzung oder s für eine Freigabe; owner ist die Client-ID der Sitzung oder die Freigabe-ID.
Konkrete Eingaben und AAD-Bytes
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