API-Referenz

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_RESPONSE

Bindet verschlüsselte Clientinformationen und das Bestätigungsergebnis an diese Client- und Serveridentität und trennt Anfrage- und Antwortrichtung.

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

Das 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

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

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

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · Anmeldung ohne Passwort
AUTH_REQUEST / AUTH_RESPONSE

Bindet verschlüsselte Bestätigungsnachrichten an diesen Handshake, einschließlich beider temporärer öffentlicher Schlüssel und der signierten Serverantwort.

text
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest

Die 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

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

Bindet die Registrierung an den WebSocket-Pfad und die Clientidentität.

text
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

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

AAD · hex · 63 B

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

Bindet die Bestätigung an den exakten verschlüsselten init-Frame, den Pfad und die Clientidentität.

text
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

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

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · verschlüsselte Frames
WS_FRAME

Bindet jeden Frame an den Verbindungshandshake, die Senderichtung und die Sequenznummer. Verhindert die Wiederverwendung in einer anderen Verbindung oder Richtung.

text
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

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 · verschlüsselte Anfragen
HTTP_REQUEST

Bindet verschlüsselte Daten an die logische HTTP-Methode und den Endpunkt und verhindert die Wiederverwendung an einem anderen REST-Endpunkt.

text
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

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
Ressourcen-URLs · /fs, /zip/* und /proxy/*
FS / ZIP_FILES

Bindet verschlüsselte URL-Nutzdaten an ihren Zweck, ihren Sitzungs- oder Freigabebereich und dessen Eigentümer.

text
{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

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