Handtekeningen en AAD
Ed25519-handtekeningen en aanvullende geauthenticeerde AEAD-gegevens: toegangspunten, byteformaten, redenen en concrete voorbeelden.
API-handtekeningen
Deze vermeldingen gebruiken Ed25519-handtekeningen. Het eerste element van elke ondertekende array is de SignaturePurpose-waarde; die scheidt bewijzen voor verschillende bewerkingen en is geen afzonderlijk overdrachtsveld.
Versleutelde HTTP-aanvragen naar /graphql en /guest_graphql en WSS-frames op /graphql gebruiken AEAD-sessietags zonder Ed25519-handtekeningen. API-tokenaanvragen naar /graphql gebruiken Bearer-authenticatie. Hieronder staat welke aanvraag, welk antwoord of welke geneste inhoud een handtekening bevat.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Waarom dit wordt ondertekend
- De apparaatidentiteit, client-ID en beide handshakeberichten binden. De browser controleert de ondertekende ServerHello voordat de sleutel voor het goedkeuringskanaal zonder wachtwoord wordt afgeleid.
- Ondertekenen en controleren
- Het apparaat ondertekent ServerHello; de verbindende browser/client controleert met de openbare identiteitssleutel van het apparaat.
- Ondertekende JSON-array
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Waarom dit wordt ondertekend
- Het verzendende apparaat authenticeren naast het versleutelen van de aanvraag. De oorspronkelijke GraphQL-aanvraag en de kanaalcontext binden, zodat het bewijs niet naar een ander kanaal kan worden verplaatst. De UUIDv7-geldigheid van de aanvraag wordt afzonderlijk gecontroleerd.
- Ondertekenen en controleren
- De verzendende peer ondertekent de aanvraag; de ontvangende peer controleert met de opgeslagen openbare identiteitssleutel van de afzender.
- Ondertekende JSON-array
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId is de tweede arraywaarde: leeg bij rechtstreekse peeraanvragen; anders exact de kanaal-ID c-cid. Sorteer voor de handtekening de objectsleutels in variables recursief.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Waarom dit wordt ondertekend
- De aanvragende identiteit, beoogde ontvanger, apparaatgegevens en openbare ECDH-sleutel binden. De ontvanger kan wijzigingen vaststellen voordat een gedeelde sleutel wordt afgeleid; QR-scanning controleert de getoonde uitnodiging met hetzelfde doel.
- Ondertekenen en controleren
- Het aanvragende apparaat ondertekent; het ontvangende apparaat of de QR-scanner controleert met signaturePublicKey uit de uitnodiging. Gebruikersbevestiging of overeenstemming met een vertrouwde identiteit blijft nodig.
- Ondertekende JSON-array
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Waarom dit wordt ondertekend
- De openbare ECDH-sleutel en verbindingsgegevens van het accepterende apparaat aan één requestId binden. Een ongerelateerde of gewijzigde acceptatie kan de openstaande koppeling niet voltooien.
- Ondertekenen en controleren
- Het accepterende apparaat ondertekent; het aanvragende apparaat controleert met de verwachte openbare identiteitssleutel van de peer.
- Ondertekende JSON-array
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Waarom dit wordt ondertekend
- Authenticeren wie de openstaande aanvraag heeft geweigerd. Alleen requestId en signature worden verstuurd; weigering brengt geen gedeelde sleutel tot stand.
- Ondertekenen en controleren
- Het weigerende apparaat ondertekent; het aanvragende apparaat controleert met de verwachte openbare identiteitssleutel van de peer.
- Ondertekende JSON-array
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Waarom dit wordt ondertekend
- De scanneridentiteit en acceptatiegegevens aan de exacte gescande uitnodiging binden. De buitenste Ed25519-handtekening authenticeert de scanner; HMAC bindt het antwoord aan request.signature.
- Ondertekenen en controleren
- Het scannende apparaat ondertekent; het apparaat dat de QR toont, controleert met signaturePublicKey van de scanner in het antwoord en controleert de binding met de gescande aanvraag.
- Ondertekende JSON-array
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
Bij QR-acceptatie is acceptSignedArrayJSON de compacte JSON-tekenreeks van de PAIRING_ACCEPT-array, met de identiteit en naam van de scanner. De scanner ondertekent de QR_PAIR_ACCEPT-array in plaats van rechtstreeks die binnenste array. De HMAC-sleutel is de UTF-8-tekenreeks request.signature, niet de uit Base64 gedecodeerde bytes ervan.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Waarom dit wordt ondertekend
- Annulering authenticeren en aan de oorspronkelijke requestSignature en beide apparaten binden, om annulering van een andere koppelingspoging te voorkomen.
- Ondertekenen en controleren
- Het annulerende apparaat ondertekent; het ontvangende apparaat controleert de identiteit en de overeenkomst met de openstaande aanvraag.
- Ondertekende JSON-array
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Waarom dit wordt ondertekend
- De verbindende peer authenticeren en zijn bewijs aan de volledige versleutelde init- en ack-frames van deze verbinding binden, om hergebruik tussen verbindingen te voorkomen.
- Ondertekenen en controleren
- De verbindende peer ondertekent het clientbewijs; de statusserver controleert met de opgeslagen openbare identiteitssleutel van de peer.
- Ondertekende JSON-array
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Waarom dit wordt ondertekend
- Een controleerbaar lidmaatschapsbewijs opnemen in de inhoud van het systeembericht, naast de buitenste handtekening van de peeraanvraag. Kanaal, versie, actie en doel binden; ontvangers handhaven afzonderlijk de eigenaars- en ledenrechten.
- Ondertekenen en controleren
- De eigenaar of het handelende lid ondertekent, afhankelijk van de actie; het ontvangende lid controleert de bijbehorende identiteit en rechten.
- Ondertekende JSON-array
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Waarom dit wordt ondertekend
- De aangekondigde SHA-256-vingerafdruk van het TLS-certificaat aan de apparaatidentiteit binden. Een beheerde peerproxy controleert dit bewijs voordat die certificaatvingerafdruk wordt vertrouwd.
- Ondertekenen en controleren
- Het apparaat ondertekent tlsCertificateSignature in het /init-antwoord; de aansluitende beheerde proxy controleert met de verwachte openbare identiteitssleutel van het apparaat.
- Ondertekende JSON-array
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose betekent de waarde in de titel van de vermelding. Serialiseer de getoonde array als compacte JSON, codeer deze als UTF-8 en onderteken met de Ed25519-identiteitssleutel van de afzender; signature is Base64. Behoud de veldvolgorde, typen en oorspronkelijke JSON-tekenreeksen. Een handtekening identificeert de ondertekenaar; geldigheid en autorisatie worden afzonderlijk gecontroleerd.
AAD-referentie
AAD wordt samen met de versleutelde tekst geauthenticeerd, maar wordt niet versleuteld of als afzonderlijk frameveld toegevoegd. Beide kanten reconstrueren dezelfde bytes; elk verschil laat de tagcontrole mislukken. De voorbeelden hergebruiken de synthetische authenticatie- en WebSocket-frames uit deze documentatie.
De dubbele verticale streep in formules betekent bytesamenvoeging. 0x00 is één nulbyte. fields(x₁, …, xₙ) voegt telkens uint32be(byteLength(xᵢ)) gevolgd door xᵢ samen. SHA256 geeft 32 onbewerkte bytes terug; hex dient alleen voor weergave. JSON.stringify betekent compacte JSON met de aangegeven veldvolgorde. Elke WebSocket-richting begint haar eigen reeks bij 1.
WSS /auth · inloggen met wachtwoord
AUTH_REQUEST / AUTH_RESPONSEDe versleutelde clientinformatie en het goedkeuringsresultaat aan de identiteit van deze client en server binden; aanvraag- en antwoordrichting scheiden.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestHet OPAQUE-inlogresultaat van Rust/WASM geeft requestAad en responseAad terug. Gebruik deze rechtstreeks zonder de interne context op te bouwen. digest is het digestgedeelte van 32 bytes, geen extra aanvraagveld. LOGIN_PASSWORD staat vast in de inlogbibliotheek; aanroepers geven geen purpose-parameter op.
Concrete invoer en AAD-bytes
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · inloggen zonder wachtwoord
AUTH_REQUEST / AUTH_RESPONSEVersleutelde goedkeuringsberichten aan deze handshake binden, inclusief beide tijdelijke openbare sleutels en het ondertekende serverantwoord.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestDe handshakebibliotheek beheert AAD intern. Gebruik encryptRequest en decryptResponse zonder de interne context op te bouwen. digest is het digestgedeelte van 32 bytes, geen extra aanvraagveld. LOGIN_NO_PASSWORD staat vast in de inlogbibliotheek; aanroepers geven geen purpose-parameter op.
Concrete invoer en 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_INITDe registratie aan het WebSocket-pad en de clientidentiteit binden.
fields(WS_INIT, path, cid)path is het logische pad, zonder schema, host of query. cid is de oorspronkelijke client-ID vóór URL-codering. Het voorbeeld gebruikt /graphql.
Concrete invoer en AAD-bytes
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKDe bevestiging aan het exacte versleutelde init-frame, het pad en de clientidentiteit binden.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame is de volledige binaire nonce + ciphertext + tag, niet de gedecodeerde init-JSON. SHA256(initFrame) wordt als 32 onbewerkte bytes opgenomen.
Concrete invoer en AAD-bytes
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · versleutelde frames
WS_FRAMEElk frame aan de handshake van de verbinding, de verzendrichting en de reeks binden, om hergebruik in een andere verbinding of richting te voorkomen.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame en ackFrame zijn volledige versleutelde binaire frames. direction is client of server afhankelijk van de afzender. sequence wordt als acht big-endian bytes gecodeerd; het voorbeeld toont 1 in beide onafhankelijke richtingen, inclusief het lege bevestigingsframe.
Concrete invoer en 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 · versleutelde aanvragen
HTTP_REQUESTVersleutelde gegevens aan hun logische HTTP-methode en eindpunt binden, om hergebruik bij een ander REST-eindpunt te voorkomen.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload en /upload_chunk gebruiken allemaal HTTP_REQUEST. Multipart-uploads binden versleutelde info-metadata. Doorsturen via proxy/BLE/Aware gebruikt het logische bestemmingspad, niet de proxy-URL.
Versleutelde antwoorden controleren de tag met lege AAD. Hun platte tekst is 0x00 + SHA256(oorspronkelijke versleutelde aanvraag) + antwoord-JSON; clients controleren de aanvraagdigest na ontsleuteling.
Concrete invoer en 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
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6bBron-URL’s · /fs, /zip/* en /proxy/*
FS / ZIP_FILESVersleutelde URL-inhoud aan het doel, de sessie- of deelcontext en de eigenaar binden.
{purpose}.{mode}.{owner}FS omvat bestandsvoorbeelden, mapdownloads, proxybronnen en bijlageverwijzingen; ZIP_FILES omvat archiefselecties. mode is c voor een sessie of s voor een gedeelde bron; owner is de client-ID van de sessie of de deel-ID.
Concrete invoer en 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