Assinaturas e AAD
Assinaturas Ed25519 e dados autenticados adicionais de AEAD: pontos de entrada, formatos de bytes, motivos e exemplos concretos.
Assinaturas de API
Estas entradas usam assinaturas Ed25519. O primeiro elemento de cada array assinado é o respetivo valor SignaturePurpose; separa as provas de diferentes operações e não é um campo separado transmitido.
Os pedidos HTTP cifrados /graphql e /guest_graphql e as tramas WSS /graphql usam etiquetas AEAD de sessão sem assinaturas Ed25519. Os pedidos com token de API para /graphql usam autenticação Bearer. As entradas abaixo indicam que pedido, resposta ou conteúdo aninhado contém uma assinatura.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Por que é assinado
- Vincular a identidade do dispositivo, o ID do cliente e ambas as mensagens de negociação. O navegador verifica o ServerHello assinado antes de derivar a chave do canal de aprovação sem palavra-passe.
- Assinatura e verificação
- O dispositivo assina ServerHello; o navegador ou cliente que se conecta verifica a assinatura com a chave pública de identidade do dispositivo.
- Array JSON assinado
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Por que é assinado
- Autenticar o dispositivo emissor além de cifrar o pedido. Vincular o pedido GraphQL original e o respetivo contexto de canal para que a prova não possa ser movida para outro canal. A validade temporal UUIDv7 do pedido é verificada separadamente.
- Assinatura e verificação
- O par emissor assina o pedido; o par destinatário verifica-o com a chave pública de identidade guardada do emissor.
- Array JSON assinado
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId é o segundo valor do array: vazio para pedidos diretos entre pares; caso contrário, exatamente o ID de canal c-cid. Para calcular a assinatura, ordene recursivamente as chaves dos objetos em variables.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Por que é assinado
- Vincular a identidade requerente, o destinatário previsto, os detalhes do dispositivo e a chave pública ECDH. O destinatário pode detetar alterações antes de derivar uma chave partilhada; a leitura QR verifica o convite apresentado com a mesma finalidade.
- Assinatura e verificação
- O dispositivo requerente assina; o destinatário ou leitor QR verifica com signaturePublicKey do convite. Continua a ser necessária a confirmação do utilizador ou a correspondência de uma identidade de confiança.
- Array JSON assinado
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Por que é assinado
- Vincular a chave pública ECDH e os detalhes de ligação do dispositivo que aceita a um requestId. Uma aceitação não relacionada ou alterada não pode concluir a associação pendente.
- Assinatura e verificação
- O dispositivo que aceita assina; o requerente verifica com a chave pública de identidade esperada do par.
- Array JSON assinado
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Por que é assinado
- Autenticar quem recusou o pedido pendente. Só são transmitidos requestId e signature; a recusa não estabelece uma chave partilhada.
- Assinatura e verificação
- O dispositivo que recusa assina; o requerente verifica com a chave pública de identidade esperada do par.
- Array JSON assinado
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Por que é assinado
- Vincular a identidade do leitor e os detalhes de aceitação ao convite exato lido. A assinatura Ed25519 externa autentica o leitor; HMAC vincula a resposta a request.signature.
- Assinatura e verificação
- O dispositivo leitor assina; o dispositivo que apresenta o QR verifica com signaturePublicKey do leitor na resposta e confirma a vinculação ao pedido lido.
- Array JSON assinado
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
Para a aceitação QR, acceptSignedArrayJSON é a cadeia JSON compacta do array PAIRING_ACCEPT, com a identidade e o nome do leitor. O leitor assina o array QR_PAIR_ACCEPT em vez de assinar diretamente esse array interno. A chave HMAC é a cadeia UTF-8 request.signature, não os seus bytes descodificados de Base64.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Por que é assinado
- Autenticar o cancelamento e vinculá-lo ao requestSignature original e a ambos os dispositivos, impedindo o cancelamento de outra tentativa de associação.
- Assinatura e verificação
- O dispositivo que cancela assina; o destinatário verifica a identidade e a correspondência com o pedido pendente.
- Array JSON assinado
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Por que é assinado
- Autentica o dispositivo que se conecta e vincula sua prova aos quadros init e ack criptografados completos desta conexão, impedindo a reutilização em outras conexões.
- Assinatura e verificação
- O par que se liga assina a prova do cliente; o servidor de estado verifica-a com a chave pública de identidade guardada do par.
- Array JSON assinado
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Por que é assinado
- Incluir uma prova de associação verificável no conteúdo da mensagem de sistema, além da assinatura externa do pedido entre pares. Vincular canal, versão, ação e destino; os destinatários aplicam separadamente as permissões de proprietário ou membro.
- Assinatura e verificação
- O proprietário ou o membro que atua assina, conforme a ação; o membro destinatário verifica a identidade e as permissões correspondentes.
- Array JSON assinado
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Por que é assinado
- Vincular a impressão digital SHA-256 do certificado TLS anunciado à identidade do dispositivo. Um proxy de par gerido verifica esta prova antes de confiar nessa impressão digital do certificado.
- Assinatura e verificação
- O dispositivo assina tlsCertificateSignature na resposta /init; o proxy gerido que se liga verifica com a chave pública de identidade esperada do dispositivo.
- Array JSON assinado
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose significa o valor no título da entrada. Serializar o array apresentado como JSON compacto, codificá-lo como UTF-8 e assinar com a chave de identidade Ed25519 do emissor; signature é Base64. Manter a ordem dos campos, os tipos e as cadeias JSON originais. Uma assinatura identifica o signatário; a validade temporal e a autorização são verificadas separadamente.
Referência de AAD
AAD é autenticado juntamente com o texto cifrado, mas não é cifrado nem acrescentado como campo separado da trama. Ambos os lados reconstroem os mesmos bytes; qualquer diferença faz falhar a verificação da etiqueta. Os exemplos reutilizam as tramas sintéticas de autenticação e WebSocket desta documentação.
A barra vertical dupla nas fórmulas indica concatenação de bytes. 0x00 é um byte zero. fields(x₁, …, xₙ) concatena cada uint32be(byteLength(xᵢ)) seguido de xᵢ. SHA256 devolve 32 bytes em bruto; hex é apenas para apresentação. JSON.stringify significa JSON compacto com a ordem de campos indicada. Cada direção WebSocket inicia a sua própria sequência em 1.
WSS /auth · início de sessão com palavra-passe
AUTH_REQUEST / AUTH_RESPONSEVincular as informações cifradas do cliente e o resultado da aprovação à identidade deste cliente e servidor; separar as direções de pedido e resposta.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestO resultado de login OPAQUE em Rust/WASM retorna requestAad e responseAad. Use-os diretamente, sem construir o contexto interno. digest é a parte do resumo de 32 bytes, não um campo adicional da requisição. LOGIN_PASSWORD é fixado na biblioteca de login; quem a chama não passa um parâmetro purpose.
Entradas concretas e bytes AAD
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · início de sessão sem palavra-passe
AUTH_REQUEST / AUTH_RESPONSEVincular as mensagens de aprovação cifradas a esta negociação, incluindo ambas as chaves públicas efémeras e a resposta assinada do servidor.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestA biblioteca de handshake gerencia AAD internamente. Use encryptRequest e decryptResponse sem construir o contexto interno. digest é a parte do resumo de 32 bytes, não um campo adicional da requisição. LOGIN_NO_PASSWORD é fixado na biblioteca de login; quem a chama não passa um parâmetro purpose.
Entradas concretas e bytes 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_INITVincular o registo ao caminho WebSocket e à identidade do cliente.
fields(WS_INIT, path, cid)path é o caminho lógico, sem esquema, anfitrião ou consulta. cid é o ID original do cliente antes da codificação URL. O exemplo usa /graphql.
Entradas concretas e bytes AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKVincular a confirmação à trama init cifrada exata, ao caminho e à identidade do cliente.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame é o binário completo nonce + ciphertext + tag, não o JSON init descodificado. SHA256(initFrame) é incluído como 32 bytes em bruto.
Entradas concretas e bytes AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · quadros criptografados
WS_FRAMEVincular cada trama à negociação da sua ligação, à direção de envio e à sequência, impedindo a reutilização noutra ligação ou direção.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame e ackFrame são tramas binárias cifradas completas. direction é client ou server conforme o emissor. sequence é codificado como oito bytes big-endian; o exemplo mostra 1 em ambas as direções independentes, incluindo a trama de confirmação vazia.
Entradas concretas e bytes 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 · requisições criptografadas
HTTP_REQUESTVincular os dados cifrados ao método HTTP lógico e ao endpoint, impedindo a reutilização noutro endpoint REST.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload e /upload_chunk usam HTTP_REQUEST. Uploads multipart vinculam os metadados info criptografados. O encaminhamento por proxy/BLE/Aware usa o caminho lógico de destino, não a URL do proxy.
Respostas criptografadas verificam o tag com AAD vazio. O texto simples é 0x00 + SHA256(requisição criptografada original) + JSON da resposta; o cliente verifica o resumo da requisição após descriptografar.
Entradas concretas e bytes 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 recursos · /fs, /zip/* e /proxy/*
FS / ZIP_FILESVincula os dados criptografados da URL à sua finalidade, ao escopo da sessão ou do compartilhamento e ao respectivo proprietário.
{purpose}.{mode}.{owner}FS abrange prévias de arquivos, downloads de diretórios, recursos de proxy e referências a anexos; ZIP_FILES abrange seleções para criar arquivos compactados. mode é c para uma sessão ou s para um compartilhamento; owner é o ID do cliente da sessão ou o ID do compartilhamento.
Entradas concretas e bytes 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