PlainApp
API-referentie

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_RESPONSE

De versleutelde clientinformatie en het goedkeuringsresultaat aan de identiteit van deze client en server binden; aanvraag- en antwoordrichting scheiden.

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

Het 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

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

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

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · inloggen zonder wachtwoord
AUTH_REQUEST / AUTH_RESPONSE

Versleutelde goedkeuringsberichten aan deze handshake binden, inclusief beide tijdelijke openbare sleutels en het ondertekende serverantwoord.

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

De 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

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

De registratie aan het WebSocket-pad en de clientidentiteit binden.

text
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

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

AAD · hex · 63 B

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

De bevestiging aan het exacte versleutelde init-frame, het pad en de clientidentiteit binden.

text
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

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

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · versleutelde frames
WS_FRAME

Elk frame aan de handshake van de verbinding, de verzendrichting en de reeks binden, om hergebruik in een andere verbinding of richting te voorkomen.

text
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

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 · versleutelde aanvragen
HTTP_REQUEST

Versleutelde gegevens aan hun logische HTTP-methode en eindpunt binden, om hergebruik bij een ander REST-eindpunt te voorkomen.

text
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

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
Bron-URL’s · /fs, /zip/* en /proxy/*
FS / ZIP_FILES

Versleutelde URL-inhoud aan het doel, de sessie- of deelcontext en de eigenaar binden.

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

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