PlainApp
Referência da API

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_RESPONSE

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

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

O 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

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

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

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · início de sessão sem palavra-passe
AUTH_REQUEST / AUTH_RESPONSE

Vincular as mensagens de aprovação cifradas a esta negociação, incluindo ambas as chaves públicas efémeras e a resposta assinada do servidor.

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

A 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

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 o registo ao caminho WebSocket e à identidade do cliente.

text
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

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

AAD · hex · 63 B

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

Vincular a confirmação à trama init cifrada exata, ao caminho e à identidade do cliente.

text
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

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

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · quadros criptografados
WS_FRAME

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

text
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

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 · requisições criptografadas
HTTP_REQUEST

Vincular os dados cifrados ao método HTTP lógico e ao endpoint, impedindo a reutilização noutro endpoint REST.

text
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

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/* e /proxy/*
FS / ZIP_FILES

Vincula os dados criptografados da URL à sua finalidade, ao escopo da sessão ou do compartilhamento e ao respectivo proprietário.

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

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