Référence de l'API

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_RESPONSE

Lier 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.

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

Le 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

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

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

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · connexion sans mot de passe
AUTH_REQUEST / AUTH_RESPONSE

Lier 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.

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

La 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

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

Lier l’enregistrement au chemin WebSocket et à l’identité du client.

text
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

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

AAD · hex · 63 B

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

Lier l’accusé de réception à la trame init chiffrée exacte, au chemin et à l’identité du client.

text
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

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

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · trames chiffrées
WS_FRAME

Lier 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.

text
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

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 · requêtes chiffrées
HTTP_REQUEST

Lier 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.

text
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

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 de ressources · /fs, /zip/* et /proxy/*
FS / ZIP_FILES

Lie les données chiffrées de l’URL à leur usage, à leur portée de session ou de partage et à son propriétaire.

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

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