Riferimento API

Firme e AAD

Firme Ed25519 e dati autenticati aggiuntivi AEAD: punti di ingresso, formati dei byte, motivazioni ed esempi concreti.

Firme API

Queste voci usano firme Ed25519. Il primo elemento di ogni array firmato è il valore SignaturePurpose; separa le prove per operazioni diverse e non è un campo separato trasmesso.

Le richieste HTTP cifrate /graphql e /guest_graphql e i frame WSS /graphql usano tag AEAD di sessione senza firme Ed25519. Le richieste con token API a /graphql usano l’autenticazione Bearer. Le voci seguenti specificano quale richiesta, risposta o payload annidato contiene una firma.

AUTH_SERVER_HELLO · WSS /auth · ServerHello
Perché viene firmato
Vincolare l’identità del dispositivo, l’ID client ed entrambi i messaggi di handshake. Il browser verifica il ServerHello firmato prima di derivare la chiave del canale di approvazione senza password.
Firma e verifica
Il dispositivo firma ServerHello; il browser o client che si connette verifica la firma con la chiave pubblica d’identità del dispositivo.
Array JSON firmato
javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
Perché viene firmato
Autenticare il dispositivo mittente oltre a cifrare la richiesta. Vincolare la richiesta GraphQL originale e il contesto del canale affinché la prova non possa essere spostata in un altro canale. La validità temporale UUIDv7 della richiesta viene verificata separatamente.
Firma e verifica
Il peer mittente firma la richiesta; il peer destinatario la verifica con la chiave pubblica di identità salvata del mittente.
Array JSON firmato
javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]

channelId è il secondo valore dell’array: vuoto per richieste dirette tra peer; altrimenti esattamente l’ID canale c-cid. Per calcolare la firma, ordina ricorsivamente le chiavi degli oggetti in variables.

PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
Perché viene firmato
Vincolare l’identità richiedente, il destinatario previsto, i dettagli del dispositivo e la chiave pubblica ECDH. Il destinatario può rilevare modifiche prima di derivare una chiave condivisa; la scansione QR verifica l’invito visualizzato con lo stesso scopo.
Firma e verifica
Il dispositivo richiedente firma; il dispositivo destinatario o lo scanner QR verifica con signaturePublicKey dell’invito. Restano necessari la conferma dell’utente o il riscontro di un’identità attendibile.
Array JSON firmato
javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
Perché viene firmato
Vincolare la chiave pubblica ECDH e i dettagli di connessione del dispositivo accettante a un requestId. Un’accettazione estranea o alterata non può completare l’associazione in sospeso.
Firma e verifica
Il dispositivo accettante firma; il dispositivo richiedente verifica con la chiave pubblica di identità prevista del peer.
Array JSON firmato
javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
Perché viene firmato
Autenticare chi ha rifiutato la richiesta in sospeso. Vengono trasmessi solo requestId e signature; il rifiuto non stabilisce una chiave condivisa.
Firma e verifica
Il dispositivo che rifiuta firma; il dispositivo richiedente verifica con la chiave pubblica di identità prevista del peer.
Array JSON firmato
javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
Perché viene firmato
Vincolare l’identità dello scanner e i dettagli di accettazione all’esatto invito scansionato. La firma Ed25519 esterna autentica lo scanner; HMAC vincola la risposta a request.signature.
Firma e verifica
Il dispositivo che scansiona firma; il dispositivo che mostra il QR verifica con signaturePublicKey dello scanner nella risposta e controlla il vincolo alla richiesta scansionata.
Array JSON firmato
javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]

Per l’accettazione QR, acceptSignedArrayJSON è la stringa JSON compatta dell’array PAIRING_ACCEPT, con identità e nome dello scanner. Lo scanner firma l’array QR_PAIR_ACCEPT invece di firmare direttamente quell’array interno. La chiave HMAC è la stringa UTF-8 request.signature, non i byte decodificati da Base64.

PAIR_CANCEL · POST /nearby · PAIR_CANCEL
Perché viene firmato
Autenticare l’annullamento e vincolarlo al requestSignature originale e a entrambi i dispositivi, impedendo l’annullamento di un diverso tentativo di associazione.
Firma e verifica
Il dispositivo che annulla firma; il destinatario verifica l’identità e la corrispondenza con la richiesta in sospeso.
Array JSON firmato
javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
Perché viene firmato
Autentica il dispositivo che si connette e vincola la sua prova ai frame init e ack cifrati completi di questa connessione, impedendone il riutilizzo in altre connessioni.
Firma e verifica
Il peer che si connette firma la prova client; il server di stato la verifica con la chiave pubblica di identità salvata del peer.
Array JSON firmato
javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
Perché viene firmato
Includere una prova verificabile di appartenenza nel payload del messaggio di sistema, oltre alla firma esterna della richiesta peer. Vincolare canale, versione, azione e destinazione; i destinatari applicano separatamente le autorizzazioni di proprietario o membro.
Firma e verifica
Firma il proprietario o il membro che agisce, secondo l’azione; il membro destinatario verifica identità e autorizzazioni corrispondenti.
Array JSON firmato
javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
Perché viene firmato
Vincolare l’impronta SHA-256 del certificato TLS annunciato all’identità del dispositivo. Un proxy peer gestito verifica questa prova prima di fidarsi dell’impronta del certificato.
Firma e verifica
Il dispositivo firma tlsCertificateSignature nella risposta /init; il proxy gestito che si collega verifica con la chiave pubblica di identità prevista del dispositivo.
Array JSON firmato
javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]

purpose indica il valore nel titolo della voce. Serializzare l’array mostrato come JSON compatto, codificarlo in UTF-8, quindi firmarlo con la chiave di identità Ed25519 del mittente; signature è Base64. Mantenere invariati ordine dei campi, tipi e stringhe JSON originali. Una firma identifica il firmatario; validità temporale e autorizzazione vengono verificate separatamente.

Riferimento AAD

AAD viene autenticato insieme al testo cifrato, ma non viene cifrato né aggiunto come campo separato del frame. Entrambi i lati ricostruiscono gli stessi byte; qualsiasi differenza causa il fallimento della verifica del tag. Gli esempi riutilizzano i frame sintetici di autenticazione e WebSocket di questa documentazione.

La doppia barra verticale nelle formule indica la concatenazione di byte. 0x00 è un byte zero. fields(x₁, …, xₙ) concatena ogni uint32be(byteLength(xᵢ)) seguito da xᵢ. SHA256 restituisce 32 byte grezzi; hex è solo per la visualizzazione. JSON.stringify indica JSON compatto con l’ordine dei campi specificato. Ogni direzione WebSocket avvia la propria sequenza da 1.

WSS /auth · accesso con password
AUTH_REQUEST / AUTH_RESPONSE

Vincolare le informazioni client cifrate e il risultato dell’approvazione all’identità di questo client e server; separare le direzioni di richiesta e risposta.

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

Il risultato del login OPAQUE Rust/WASM restituisce requestAad e responseAad. Usali direttamente, senza costruire il contesto interno. digest è la parte del digest di 32 byte, non un campo aggiuntivo della richiesta. LOGIN_PASSWORD è fissato nella libreria di login; il chiamante non passa un parametro purpose.

Input concreti e byte 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 · accesso senza password
AUTH_REQUEST / AUTH_RESPONSE

Vincolare i messaggi di approvazione cifrati a questo handshake, incluse entrambe le chiavi pubbliche effimere e la risposta firmata del server.

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

La libreria di handshake gestisce AAD internamente. Usa encryptRequest e decryptResponse senza costruire il contesto interno. digest è la parte del digest di 32 byte, non un campo aggiuntivo della richiesta. LOGIN_NO_PASSWORD è fissato nella libreria di login; il chiamante non passa un parametro purpose.

Input concreti e byte 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

Vincolare la registrazione al percorso WebSocket e all’identità del client.

text
fields(WS_INIT, path, cid)

path è il percorso logico, senza schema, host o query. cid è l’ID client originale prima della codifica URL. L’esempio usa /graphql.

Input concreti e byte AAD

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

AAD · hex · 63 B

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

Vincolare la conferma all’esatto frame init cifrato, al percorso e all’identità del client.

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

initFrame è il binario completo nonce + ciphertext + tag, non il JSON init decodificato. SHA256(initFrame) è incluso come 32 byte grezzi.

Input concreti e byte 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 · frame cifrati
WS_FRAME

Vincolare ogni frame all’handshake della sua connessione, alla direzione di invio e alla sequenza, impedendone il riutilizzo in un’altra connessione o direzione.

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

initFrame e ackFrame sono frame binari cifrati completi. direction è client o server secondo il mittente. sequence è codificato in otto byte big-endian; l’esempio mostra 1 in entrambe le direzioni indipendenti, incluso il frame di conferma vuoto.

Input concreti e byte 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 · richieste cifrate
HTTP_REQUEST

Vincolare i dati cifrati al metodo HTTP logico e all’endpoint, impedendone il riutilizzo in un altro endpoint REST.

text
HTTP_REQUEST.{method}.{endpoint}

POST /graphql, /guest_graphql, /peer_graphql, /init, /upload e /upload_chunk usano HTTP_REQUEST. I caricamenti multipart vincolano i metadati info cifrati. L’inoltro tramite proxy/BLE/Aware usa il percorso logico di destinazione, non l’URL del proxy.

Le risposte cifrate verificano il tag con AAD vuoto. Il testo in chiaro è 0x00 + SHA256(richiesta cifrata originale) + JSON della risposta; il client controlla il digest della richiesta dopo la decifratura.

Input concreti e byte 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 delle risorse · /fs, /zip/* e /proxy/*
FS / ZIP_FILES

Vincola i dati cifrati dell’URL al loro scopo, all’ambito di sessione o condivisione e al relativo proprietario.

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

FS copre anteprime di file, download di directory, risorse proxy e riferimenti agli allegati; ZIP_FILES copre le selezioni da archiviare. mode è c per una sessione o s per una condivisione; owner è l’ID del client della sessione o l’ID della condivisione.

Input concreti e byte 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