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_RESPONSEVincolare le informazioni client cifrate e il risultato dell’approvazione all’identità di questo client e server; separare le direzioni di richiesta e risposta.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestIl 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
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · accesso senza password
AUTH_REQUEST / AUTH_RESPONSEVincolare i messaggi di approvazione cifrati a questo handshake, incluse entrambe le chiavi pubbliche effimere e la risposta firmata del server.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestLa 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
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 44 B
415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafdirection = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 45 B
415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafWSS /graphql, /screen, /image_editor, /status · init
WS_INITVincolare la registrazione al percorso WebSocket e all’identità del client.
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
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKVincolare la conferma all’esatto frame init cifrato, al percorso e all’identità del client.
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
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · frame cifrati
WS_FRAMEVincolare ogni frame all’handshake della sua connessione, alla direzione di invio e alla sequenza, impedendone il riutilizzo in un’altra connessione o direzione.
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
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 · richieste cifrate
HTTP_REQUESTVincolare i dati cifrati al metodo HTTP logico e all’endpoint, impedendone il riutilizzo in un altro endpoint REST.
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
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
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6bURL delle risorse · /fs, /zip/* e /proxy/*
FS / ZIP_FILESVincola i dati cifrati dell’URL al loro scopo, all’ambito di sessione o condivisione e al relativo proprietario.
{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
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