Signatures et AAD
Signatures Ed25519 et données authentifiées supplémentaires AEAD : points d’entrée, formats des octets, raisons et exemples concrets.
Signatures d’API
Ces entrées utilisent des signatures Ed25519. Le premier élément de chaque tableau signé est sa valeur SignaturePurpose ; il sépare les preuves des différentes opérations et n’est pas un champ distinct transmis.
Les requêtes HTTP chiffrées /graphql et /guest_graphql et les trames WSS /graphql utilisent des étiquettes AEAD de session sans signature Ed25519. Les requêtes avec jeton d’API vers /graphql utilisent l’authentification Bearer. Les entrées ci-dessous précisent quelle requête, réponse ou charge imbriquée porte une signature.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Pourquoi signer
- Lier l’identité de l’appareil, l’ID client et les deux messages de négociation. Le navigateur vérifie le ServerHello signé avant de dériver la clé du canal d’approbation sans mot de passe.
- Signature et vérification
- L’appareil signe ServerHello ; le navigateur ou client qui se connecte vérifie la signature avec la clé publique d’identité de l’appareil.
- Tableau JSON signé
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Pourquoi signer
- Authentifier l’appareil émetteur en plus de chiffrer la requête. Lier la requête GraphQL originale à son contexte de canal pour empêcher le déplacement de la preuve vers un autre canal. La fraîcheur du UUIDv7 de la requête est vérifiée séparément.
- Signature et vérification
- Le pair émetteur signe la requête ; le pair destinataire la vérifie avec la clé publique d’identité enregistrée de l’émetteur.
- Tableau JSON signé
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId est la deuxième valeur du tableau : vide pour les requêtes directes entre pairs ; sinon, exactement l’ID de canal c-cid. Pour calculer la signature, triez récursivement les clés des objets dans variables.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Pourquoi signer
- Lier l’identité demandeuse, le destinataire prévu, les détails de l’appareil et la clé publique ECDH. Le destinataire peut détecter les changements avant de dériver une clé partagée ; la lecture QR vérifie l’invitation affichée avec la même finalité.
- Signature et vérification
- L’appareil demandeur signe ; le destinataire ou le scanner QR vérifie avec signaturePublicKey de l’invitation. Une confirmation utilisateur ou une correspondance d’identité de confiance reste nécessaire.
- Tableau JSON signé
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Pourquoi signer
- Lier la clé publique ECDH et les détails de connexion de l’appareil acceptant à un requestId. Une acceptation sans rapport ou altérée ne peut pas terminer l’association en attente.
- Signature et vérification
- L’appareil acceptant signe ; l’appareil demandeur vérifie avec la clé publique d’identité attendue du pair.
- Tableau JSON signé
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Pourquoi signer
- Authentifier l’auteur du refus de la demande en attente. Seuls requestId et signature sont transmis ; le refus n’établit pas de clé partagée.
- Signature et vérification
- L’appareil refusant signe ; l’appareil demandeur vérifie avec la clé publique d’identité attendue du pair.
- Tableau JSON signé
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Pourquoi signer
- Lier l’identité du scanner et les détails d’acceptation à l’invitation exacte lue. La signature Ed25519 externe authentifie le scanner ; HMAC lie la réponse à request.signature.
- Signature et vérification
- L’appareil scanner signe ; l’appareil affichant le QR vérifie avec signaturePublicKey du scanner dans la réponse et contrôle le lien avec la demande lue.
- Tableau JSON signé
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
Pour l’acceptation QR, acceptSignedArrayJSON est la chaîne JSON compacte du tableau PAIRING_ACCEPT, avec l’identité et le nom du scanner. Le scanner signe le tableau QR_PAIR_ACCEPT au lieu de signer directement ce tableau interne. La clé HMAC est la chaîne UTF-8 request.signature, pas ses octets décodés depuis Base64.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Pourquoi signer
- Authentifier l’annulation et la lier au requestSignature original et aux deux appareils, pour empêcher l’annulation d’une autre tentative d’association.
- Signature et vérification
- L’appareil annulant signe ; l’appareil destinataire vérifie l’identité et la correspondance avec la demande en attente.
- Tableau JSON signé
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Pourquoi signer
- Authentifie l’appareil qui se connecte et lie sa preuve aux trames init et ack chiffrées complètes de cette connexion, empêchant leur réutilisation sur une autre connexion.
- Signature et vérification
- Le pair se connectant signe la preuve client ; le serveur d’état la vérifie avec la clé publique d’identité enregistrée du pair.
- Tableau JSON signé
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Pourquoi signer
- Inclure une preuve d’appartenance vérifiable dans la charge du message système, en plus de la signature externe de la requête entre pairs. Lier canal, version, action et cible ; les destinataires appliquent séparément les permissions du propriétaire ou du membre.
- Signature et vérification
- Le propriétaire ou le membre agissant signe, selon l’action ; le membre destinataire vérifie l’identité et les permissions correspondantes.
- Tableau JSON signé
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Pourquoi signer
- Lier l’empreinte SHA-256 du certificat TLS annoncé à l’identité de l’appareil. Un proxy de pair géré vérifie cette preuve avant de faire confiance à cette empreinte de certificat.
- Signature et vérification
- L’appareil signe tlsCertificateSignature dans la réponse /init ; le proxy géré qui se rattache vérifie avec la clé publique d’identité attendue de l’appareil.
- Tableau JSON signé
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose désigne la valeur dans le titre de l’entrée. Sérialiser le tableau affiché en JSON compact, l’encoder en UTF-8, puis le signer avec la clé d’identité Ed25519 de l’émetteur ; signature est en Base64. Conserver l’ordre des champs, les types et les chaînes JSON originales. Une signature identifie le signataire ; la fraîcheur et l’autorisation sont vérifiées séparément.
Référence AAD
Les AAD sont authentifiées avec le texte chiffré, mais ne sont ni chiffrées ni ajoutées comme champ distinct de la trame. Les deux côtés reconstruisent les mêmes octets ; toute différence fait échouer la vérification de l’étiquette. Les exemples réutilisent les trames synthétiques d’authentification et WebSocket de cette documentation.
La double barre verticale dans les formules désigne la concaténation d’octets. 0x00 est un octet nul. fields(x₁, …, xₙ) concatène chaque uint32be(byteLength(xᵢ)) suivi de xᵢ. SHA256 renvoie 32 octets bruts ; hex sert uniquement à l’affichage. JSON.stringify désigne un JSON compact avec l’ordre des champs indiqué. Chaque direction WebSocket commence sa propre séquence à 1.
WSS /auth · connexion avec mot de passe
AUTH_REQUEST / AUTH_RESPONSELier les informations client chiffrées et le résultat d’approbation à l’identité de ce client et de ce serveur ; séparer les directions de requête et de réponse.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestLe résultat de connexion OPAQUE Rust/WASM fournit requestAad et responseAad. Utilisez-les directement, sans construire le contexte interne. digest est la partie empreinte de 32 octets, pas un champ supplémentaire de la requête. LOGIN_PASSWORD est fixé dans la bibliothèque de connexion ; l’appelant ne fournit aucun paramètre purpose.
Entrées concrètes et octets AAD
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · connexion sans mot de passe
AUTH_REQUEST / AUTH_RESPONSELier les messages d’approbation chiffrés à cette négociation, y compris les deux clés publiques éphémères et la réponse signée du serveur.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestLa bibliothèque de négociation gère AAD en interne. Utilisez encryptRequest et decryptResponse sans construire le contexte interne. digest est la partie empreinte de 32 octets, pas un champ supplémentaire de la requête. LOGIN_NO_PASSWORD est fixé dans la bibliothèque de connexion ; l’appelant ne fournit aucun paramètre purpose.
Entrées concrètes et octets 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_INITLier l’enregistrement au chemin WebSocket et à l’identité du client.
fields(WS_INIT, path, cid)path est le chemin logique, sans schéma, hôte ni requête. cid est l’ID client original avant l’encodage URL. L’exemple utilise /graphql.
Entrées concrètes et octets AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKLier l’accusé de réception à la trame init chiffrée exacte, au chemin et à l’identité du client.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame est le binaire complet nonce + ciphertext + tag, pas le JSON init décodé. SHA256(initFrame) est inclus sous forme de 32 octets bruts.
Entrées concrètes et octets AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · trames chiffrées
WS_FRAMELier chaque trame à la négociation de sa connexion, à la direction d’envoi et à la séquence, pour empêcher sa réutilisation sur une autre connexion ou dans une autre direction.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame et ackFrame sont des trames binaires chiffrées complètes. direction vaut client ou server selon l’émetteur. sequence est encodé sur huit octets big-endian ; l’exemple montre 1 dans les deux directions indépendantes, y compris la trame de confirmation vide.
Entrées concrètes et octets 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 · requêtes chiffrées
HTTP_REQUESTLier les données chiffrées à leur méthode HTTP logique et à leur point de terminaison, pour empêcher leur réutilisation sur un autre point REST.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload et /upload_chunk utilisent HTTP_REQUEST. Les envois multipart lient les métadonnées info chiffrées. Le transfert par proxy/BLE/Aware utilise le chemin logique de destination, pas l’URL du proxy.
Les réponses chiffrées vérifient le tag avec un AAD vide. Leur texte en clair est 0x00 + SHA256(requête chiffrée d’origine) + JSON de réponse ; le client vérifie l’empreinte de la requête après déchiffrement.
Entrées concrètes et octets 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 de ressources · /fs, /zip/* et /proxy/*
FS / ZIP_FILESLie les données chiffrées de l’URL à leur usage, à leur portée de session ou de partage et à son propriétaire.
{purpose}.{mode}.{owner}FS couvre les aperçus de fichiers, les téléchargements de répertoires, les ressources du proxy et les références aux pièces jointes ; ZIP_FILES couvre les sélections à archiver. mode vaut c pour une session ou s pour un partage ; owner est l’ID client de la session ou l’ID du partage.
Entrées concrètes et octets 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