Referencia de la API

Firmas y AAD

Firmas Ed25519 y datos autenticados adicionales de AEAD: puntos de entrada, formatos de bytes, motivos y ejemplos concretos.

Firmas de API

Estas entradas usan firmas Ed25519. El primer elemento de cada array firmado es su valor SignaturePurpose; separa las pruebas de distintas operaciones y no es un campo independiente transmitido.

Las solicitudes HTTP cifradas a /graphql y /guest_graphql y las tramas WSS /graphql usan etiquetas AEAD de sesión sin firmas Ed25519. Las solicitudes con token de API a /graphql usan autenticación Bearer. Las entradas siguientes indican qué solicitud, respuesta o carga anidada lleva una firma.

AUTH_SERVER_HELLO · WSS /auth · ServerHello
Por qué se firma
Vincular la identidad del dispositivo, el ID del cliente y ambos mensajes de negociación. El navegador comprueba el ServerHello firmado antes de derivar la clave del canal de aprobación sin contraseña.
Firma y verificación
El dispositivo firma ServerHello; el navegador o cliente que se conecta verifica la firma con la clave pública de identidad del dispositivo.
Array JSON firmado
javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
Por qué se firma
Autenticar el dispositivo emisor además de cifrar la solicitud. Vincular la solicitud GraphQL original y su contexto de canal para que la prueba no pueda trasladarse a otro canal. La vigencia de UUIDv7 de la solicitud se comprueba por separado.
Firma y verificación
El par emisor firma la solicitud; el par receptor la verifica con la clave pública de identidad guardada del emisor.
Array JSON firmado
javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]

channelId es el segundo valor del array: vacío para solicitudes directas entre pares; de lo contrario, exactamente el ID de canal c-cid. Para calcular la firma, ordena de forma recursiva las claves de los objetos en variables.

PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
Por qué se firma
Vincular la identidad solicitante, el destinatario previsto, los detalles del dispositivo y la clave pública ECDH. El receptor puede detectar cambios antes de derivar una clave compartida; el escaneo QR verifica la invitación mostrada con la misma finalidad.
Firma y verificación
El dispositivo solicitante firma; el receptor o escáner QR verifica con signaturePublicKey de la invitación. Sigue siendo necesaria la confirmación del usuario o una coincidencia de identidad de confianza.
Array JSON firmado
javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
Por qué se firma
Vincular la clave pública ECDH y los detalles de conexión del dispositivo que acepta a un requestId. Una aceptación ajena o alterada no puede completar la vinculación pendiente.
Firma y verificación
El dispositivo que acepta firma; el solicitante verifica con la clave pública de identidad esperada del par.
Array JSON firmado
javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
Por qué se firma
Autenticar quién rechazó la solicitud pendiente. Solo se transmiten requestId y signature; el rechazo no establece una clave compartida.
Firma y verificación
El dispositivo que rechaza firma; el solicitante verifica con la clave pública de identidad esperada del par.
Array JSON firmado
javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
Por qué se firma
Vincular la identidad del escáner y los detalles de aceptación a la invitación exacta escaneada. La firma Ed25519 externa autentica al escáner; HMAC vincula la respuesta a request.signature.
Firma y verificación
El dispositivo escáner firma; el que muestra el QR verifica con signaturePublicKey del escáner en la respuesta y comprueba la vinculación con la solicitud escaneada.
Array JSON firmado
javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]

Para la aceptación QR, acceptSignedArrayJSON es la cadena JSON compacta del array PAIRING_ACCEPT, con la identidad y nombre del escáner. El escáner firma el array QR_PAIR_ACCEPT en lugar de firmar directamente ese array interno. La clave HMAC es la cadena UTF-8 request.signature, no sus bytes decodificados de Base64.

PAIR_CANCEL · POST /nearby · PAIR_CANCEL
Por qué se firma
Autenticar la cancelación y vincularla al requestSignature original y a ambos dispositivos, impidiendo cancelar otro intento de vinculación.
Firma y verificación
El dispositivo que cancela firma; el receptor verifica la identidad y la correspondencia con la solicitud pendiente.
Array JSON firmado
javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
Por qué se firma
Autentica al dispositivo que se conecta y vincula su prueba con las tramas init y ack cifradas completas de esta conexión, para evitar su reutilización en otras conexiones.
Firma y verificación
El par que conecta firma la prueba del cliente; el servidor de estado la verifica con la clave pública de identidad guardada del par.
Array JSON firmado
javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
Por qué se firma
Incluir una prueba verificable de pertenencia en la carga del mensaje de sistema, además de la firma externa de la solicitud entre pares. Vincular canal, versión, acción y destino; los receptores aplican por separado los permisos de propietario o miembro.
Firma y verificación
Firma el propietario o el miembro que actúa, según la acción; el miembro receptor verifica la identidad y los permisos correspondientes.
Array JSON firmado
javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
Por qué se firma
Vincular la huella SHA-256 del certificado TLS anunciado a la identidad del dispositivo. Un proxy de pares gestionado verifica esta prueba antes de confiar en esa huella de certificado.
Firma y verificación
El dispositivo firma tlsCertificateSignature en la respuesta /init; el proxy gestionado que se conecta verifica con la clave pública de identidad esperada del dispositivo.
Array JSON firmado
javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]

purpose significa el valor del encabezado de la entrada. Serializar el array mostrado como JSON compacto, codificarlo en UTF-8 y firmarlo con la clave de identidad Ed25519 del emisor; signature es Base64. Mantener el orden de campos, tipos y cadenas JSON originales. Una firma identifica al firmante; la vigencia y la autorización se comprueban por separado.

Referencia de AAD

AAD se autentica junto con el texto cifrado, pero no se cifra ni se añade como campo independiente de la trama. Ambos lados reconstruyen los mismos bytes; cualquier discrepancia hace fallar la verificación de la etiqueta. Los ejemplos reutilizan las tramas sintéticas de autenticación y WebSocket de esta documentación.

La doble barra vertical en las fórmulas indica concatenación de bytes. 0x00 es un byte cero. fields(x₁, …, xₙ) concatena cada uint32be(byteLength(xᵢ)) seguido de xᵢ. SHA256 devuelve 32 bytes sin procesar; hex es solo para visualización. JSON.stringify significa JSON compacto con el orden de campos indicado. Cada dirección de WebSocket inicia su propia secuencia en 1.

WSS /auth · inicio de sesión con contraseña
AUTH_REQUEST / AUTH_RESPONSE

Vincular la información cifrada del cliente y el resultado de aprobación a la identidad de este cliente y servidor; separar las direcciones de solicitud y respuesta.

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

El resultado de inicio de sesión OPAQUE de Rust/WASM devuelve requestAad y responseAad. Úsalos directamente, sin construir el contexto interno. digest es la parte del resumen de 32 bytes, no un campo adicional de la solicitud. LOGIN_PASSWORD está fijado dentro de la biblioteca de inicio de sesión; el llamador no pasa un parámetro purpose.

Entradas concretas y bytes 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 · inicio de sesión sin contraseña
AUTH_REQUEST / AUTH_RESPONSE

Vincular los mensajes de aprobación cifrados a este intercambio inicial, incluidas ambas claves públicas efímeras y la respuesta firmada del servidor.

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

La biblioteca de negociación gestiona AAD internamente. Usa encryptRequest y decryptResponse sin construir el contexto interno. digest es la parte del resumen de 32 bytes, no un campo adicional de la solicitud. LOGIN_NO_PASSWORD está fijado dentro de la biblioteca de inicio de sesión; el llamador no pasa un parámetro purpose.

Entradas concretas y bytes 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

Vincular el registro a la ruta WebSocket y a la identidad del cliente.

text
fields(WS_INIT, path, cid)

path es la ruta lógica, sin esquema, host ni consulta. cid es el ID de cliente original antes de codificar la URL. El ejemplo usa /graphql.

Entradas concretas y bytes AAD

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

AAD · hex · 63 B

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

Vincular el acuse de recibo a la trama init cifrada exacta, la ruta y la identidad del cliente.

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

initFrame es el binario completo nonce + ciphertext + tag, no el JSON init decodificado. SHA256(initFrame) se incluye como 32 bytes sin procesar.

Entradas concretas y bytes 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 · tramas cifradas
WS_FRAME

Vincular cada trama al intercambio inicial de su conexión, la dirección de envío y la secuencia, impidiendo su reutilización en otra conexión o dirección.

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

initFrame y ackFrame son tramas binarias cifradas completas. direction es client o server según el emisor. sequence se codifica como ocho bytes big-endian; el ejemplo muestra 1 en ambas direcciones independientes, incluida la trama de confirmación vacía.

Entradas concretas y bytes 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 · solicitudes cifradas
HTTP_REQUEST

Vincular los datos cifrados a su método HTTP lógico y endpoint, impidiendo su reutilización en otro endpoint REST.

text
HTTP_REQUEST.{method}.{endpoint}

POST /graphql, /guest_graphql, /peer_graphql, /init, /upload y /upload_chunk usan HTTP_REQUEST. Las cargas multipart vinculan los metadatos info cifrados. El reenvío por proxy/BLE/Aware usa la ruta lógica de destino, no la URL del proxy.

Las respuestas cifradas verifican el tag con AAD vacío. Su texto plano es 0x00 + SHA256(solicitud cifrada original) + JSON de respuesta; el cliente comprueba el resumen de la solicitud después de descifrar.

Entradas concretas y bytes 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 recursos · /fs, /zip/* y /proxy/*
FS / ZIP_FILES

Vincula los datos cifrados de la URL con su propósito, el ámbito de sesión o de uso compartido y su propietario.

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

FS cubre las vistas previas de archivos, las descargas de directorios, los recursos del proxy y las referencias a adjuntos; ZIP_FILES cubre las selecciones para crear archivos comprimidos. mode es c para una sesión o s para un recurso compartido; owner es el ID del cliente de la sesión o el ID del recurso compartido.

Entradas concretas y bytes 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