Справочник API

Подписи и 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

Привязывает зашифрованные сведения о клиенте и результат одобрения к идентичностям этого клиента и сервера; разделяет направления запроса и ответа.

text
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

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

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

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · вход без пароля
AUTH_REQUEST / AUTH_RESPONSE

Привязывает зашифрованные сообщения одобрения к этому рукопожатию, включая оба временных открытых ключа и подписанный ответ сервера.

text
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

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

Привязывает регистрацию к пути WebSocket и идентичности клиента.

text
fields(WS_INIT, path, cid)

path — логический путь без схемы, хоста и строки запроса. cid — исходный ID клиента до URL-кодирования. В примере используется /graphql.

Конкретные входные данные и байты AAD

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

AAD · hex · 63 B

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

Привязывает подтверждение к конкретному зашифрованному кадру init, пути и идентичности клиента.

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

initFrame — полная бинарная последовательность nonce + ciphertext + tag, а не декодированный JSON init. SHA256(initFrame) включается как 32 необработанных байта.

Конкретные входные данные и байты 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 · зашифрованные кадры
WS_FRAME

Привязывает каждый кадр к рукопожатию его соединения, направлению отправки и порядковому номеру, предотвращая повторное использование в другом соединении или направлении.

text
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

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 · зашифрованные запросы
HTTP_REQUEST

Привязывает зашифрованные данные к логическому HTTP-методу и конечной точке, предотвращая повторное использование в другой конечной точке REST.

text
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

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 ресурсов · /fs, /zip/* и /proxy/*
FS / ZIP_FILES

Привязывает зашифрованное содержимое URL к назначению, области сеанса/общего доступа и владельцу.

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

FS охватывает предпросмотр файлов, скачивание каталогов, ресурсы прокси и ссылки на вложения; ZIP_FILES — выбор элементов архива. mode равен c для сеанса или s для общего доступа; owner — ID клиента сеанса или ID общего доступа.

Конкретные входные данные и байты 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