Подписи и AAD
Подписи Ed25519 и дополнительные аутентифицируемые данные AEAD: точки входа, форматы байтов, причины и конкретные примеры.
Подписи API
Эти записи используют подписи Ed25519. Первый элемент каждого подписываемого массива — его значение SignaturePurpose; оно разделяет доказательства для разных операций и не является отдельным передаваемым полем.
Зашифрованные HTTP-запросы /graphql и /guest_graphql и кадры WSS /graphql используют теги AEAD сеанса без подписей Ed25519. Запросы к /graphql с API-токеном используют аутентификацию Bearer. Ниже указано, какой запрос, ответ или вложенное содержимое несёт подпись.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Зачем нужна подпись
- Привязывает идентичность устройства, ID клиента и оба сообщения рукопожатия. Браузер проверяет подписанный ServerHello до получения ключа канала одобрения входа без пароля.
- Подписание и проверка
- Устройство подписывает ServerHello; подключающийся браузер/клиент проверяет его открытым ключом идентичности устройства.
- Подписываемый массив JSON
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Зачем нужна подпись
- Помимо шифрования запроса аутентифицирует отправляющее устройство. Привязывает исходный запрос GraphQL и контекст его канала, чтобы доказательство нельзя было перенести в другой канал. Давность UUIDv7 запроса проверяется отдельно.
- Подписание и проверка
- Отправляющий узел подписывает запрос; принимающий проверяет его сохранённым открытым ключом идентичности отправителя.
- Подписываемый массив JSON
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId — второе значение массива: пустое для прямых запросов узла; иначе точно совпадает с ID канала c-cid. При вычислении подписи сортируйте ключи объектов в variables на всех уровнях.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Зачем нужна подпись
- Привязывает идентичность запрашивающего, предполагаемого получателя, сведения об устройстве и открытый ключ ECDH. Получатель может обнаружить изменения до получения общего ключа; сканирование QR проверяет показанное приглашение с тем же purpose.
- Подписание и проверка
- Запрашивающее устройство подписывает; принимающее устройство или QR-сканер проверяет через signaturePublicKey приглашения. Подтверждение пользователя или сопоставление доверенной идентичности остаётся необходимым.
- Подписываемый массив JSON
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Зачем нужна подпись
- Привязывает открытый ключ ECDH и параметры соединения принимающего устройства к одному requestId. Несвязанное или изменённое принятие не завершит ожидающее сопряжение.
- Подписание и проверка
- Принимающее устройство подписывает; запрашивающее проверяет ожидаемым открытым ключом идентичности узла.
- Подписываемый массив JSON
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Зачем нужна подпись
- Аутентифицирует сторону, отклонившую ожидающий запрос. Передаются только requestId и signature; отказ не устанавливает общий ключ.
- Подписание и проверка
- Отклоняющее устройство подписывает; запрашивающее проверяет ожидаемым открытым ключом идентичности узла.
- Подписываемый массив JSON
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Зачем нужна подпись
- Привязывает идентичность сканера и сведения о принятии к конкретному отсканированному приглашению. Внешняя подпись Ed25519 аутентифицирует сканер; HMAC привязывает ответ к request.signature.
- Подписание и проверка
- Сканирующее устройство подписывает; устройство с QR проверяет через signaturePublicKey сканера в ответе и проверяет привязку отсканированного запроса.
- Подписываемый массив JSON
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
При принятии QR acceptSignedArrayJSON — компактная строка JSON массива PAIRING_ACCEPT с идентичностью и именем сканирующего устройства. Оно подписывает массив QR_PAIR_ACCEPT вместо прямого подписания внутреннего массива. Ключ HMAC — строка request.signature в UTF-8, а не байты после декодирования Base64.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Зачем нужна подпись
- Аутентифицирует отмену и привязывает её к исходному requestSignature и обоим устройствам, предотвращая отмену другой попытки сопряжения.
- Подписание и проверка
- Отменяющее устройство подписывает; принимающее проверяет идентичность и соответствие ожидающему запросу.
- Подписываемый массив JSON
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Зачем нужна подпись
- Аутентифицирует подключающийся узел и привязывает его доказательство к полным зашифрованным кадрам init и ack этого соединения, предотвращая повторное использование между соединениями.
- Подписание и проверка
- Подключающийся узел подписывает доказательство клиента; сервер статуса проверяет его сохранённым открытым ключом идентичности узла.
- Подписываемый массив JSON
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Зачем нужна подпись
- Передаёт проверяемое доказательство членства внутри содержимого системного сообщения в дополнение к внешней подписи запроса узла. Привязывает канал, версию, действие и цель; получатели отдельно применяют разрешения владельца/участника.
- Подписание и проверка
- В зависимости от действия подписывает владелец или действующий участник; принимающий участник проверяет соответствующую идентичность и разрешения.
- Подписываемый массив JSON
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Зачем нужна подпись
- Привязывает объявленный отпечаток SHA-256 сертификата TLS к идентичности устройства. Управляемый прокси узла проверяет это доказательство, прежде чем доверять отпечатку сертификата.
- Подписание и проверка
- Устройство подписывает tlsCertificateSignature в ответе /init; подключаемый управляемый прокси проверяет ожидаемым открытым ключом идентичности устройства.
- Подписываемый массив JSON
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose означает значение в заголовке записи. Сериализуйте показанный массив в компактный JSON, закодируйте в UTF-8 и подпишите ключом идентичности Ed25519 отправителя; signature имеет формат Base64. Сохраняйте порядок полей, типы и исходные строки JSON. Подпись определяет подписавшего; давность и полномочия проверяются отдельно.
Справочник AAD
AAD аутентифицируется вместе с шифротекстом, но не шифруется и не добавляется отдельным полем кадра. Обе стороны восстанавливают одинаковые байты; любое расхождение приводит к ошибке проверки тега. Примеры используют искусственные кадры аутентификации и WebSocket из этой документации.
Двойная вертикальная черта в формулах обозначает конкатенацию байтов. 0x00 — один нулевой байт. fields(x₁, …, xₙ) объединяет для каждого поля uint32be(byteLength(xᵢ)), за которым следует xᵢ. SHA256 возвращает 32 необработанных байта; hex используется только для отображения. JSON.stringify означает компактный JSON с указанным порядком полей. В каждом направлении WebSocket последовательность начинается с 1.
WSS /auth · вход с паролем
AUTH_REQUEST / AUTH_RESPONSEПривязывает зашифрованные сведения о клиенте и результат одобрения к идентичностям этого клиента и сервера; разделяет направления запроса и ответа.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestРезультат входа OPAQUE Rust/WASM возвращает requestAad и responseAad. Используйте их напрямую, не создавая внутренний контекст. digest — часть с 32-байтовым дайджестом, а не дополнительное поле запроса. LOGIN_PASSWORD зафиксирован в библиотеке входа; вызывающий код не передаёт параметр purpose.
Конкретные входные данные и байты AAD
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · вход без пароля
AUTH_REQUEST / AUTH_RESPONSEПривязывает зашифрованные сообщения одобрения к этому рукопожатию, включая оба временных открытых ключа и подписанный ответ сервера.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestБиблиотека рукопожатия управляет AAD внутри. Используйте encryptRequest и decryptResponse, не создавая внутренний контекст. digest — часть с 32-байтовым дайджестом, а не дополнительное поле запроса. LOGIN_NO_PASSWORD зафиксирован в библиотеке входа; вызывающий код не передаёт параметр purpose.
Конкретные входные данные и байты 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_INITПривязывает регистрацию к пути WebSocket и идентичности клиента.
fields(WS_INIT, path, cid)path — логический путь без схемы, хоста и строки запроса. cid — исходный ID клиента до URL-кодирования. В примере используется /graphql.
Конкретные входные данные и байты AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKПривязывает подтверждение к конкретному зашифрованному кадру init, пути и идентичности клиента.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame — полная бинарная последовательность nonce + ciphertext + tag, а не декодированный JSON init. SHA256(initFrame) включается как 32 необработанных байта.
Конкретные входные данные и байты AAD
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · зашифрованные кадры
WS_FRAMEПривязывает каждый кадр к рукопожатию его соединения, направлению отправки и порядковому номеру, предотвращая повторное использование в другом соединении или направлении.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame и ackFrame — полные зашифрованные бинарные кадры. direction равен client или server в зависимости от отправителя. sequence кодируется восемью байтами в порядке big-endian; пример показывает 1 в обоих независимых направлениях, включая пустой кадр подтверждения.
Конкретные входные данные и байты 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 · зашифрованные запросы
HTTP_REQUESTПривязывает зашифрованные данные к логическому HTTP-методу и конечной точке, предотвращая повторное использование в другой конечной точке REST.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload и /upload_chunk используют HTTP_REQUEST. Составные загрузки привязывают зашифрованные метаданные info. Перенаправление Proxy/BLE/Aware использует логический путь назначения, а не URL прокси.
Зашифрованные ответы проверяют тег с пустым AAD. Их открытый текст: 0x00 + SHA256(исходный зашифрованный запрос) + JSON ответа; после расшифровки клиенты проверяют дайджест запроса.
Конкретные входные данные и байты 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 ресурсов · /fs, /zip/* и /proxy/*
FS / ZIP_FILESПривязывает зашифрованное содержимое URL к назначению, области сеанса/общего доступа и владельцу.
{purpose}.{mode}.{owner}FS охватывает предпросмотр файлов, скачивание каталогов, ресурсы прокси и ссылки на вложения; ZIP_FILES — выбор элементов архива. mode равен c для сеанса или s для общего доступа; owner — ID клиента сеанса или ID общего доступа.
Конкретные входные данные и байты 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