From c38d6740319933becbd437012a9c8e118188839e Mon Sep 17 00:00:00 2001 From: shr3dd3r Date: Tue, 4 Jul 2023 23:22:39 +0300 Subject: [PATCH] Marafon Protocol -> Stadium --- HANDSHAKE.md | 20 ++++-- KLDR RESERVED KEYS.md | 1 + OVERVIEW.md | 72 ++++++++++++------- .../METHOD FORMAT EXAMPLE.md | 6 +- 4 files changed, 65 insertions(+), 34 deletions(-) create mode 100644 KLDR RESERVED KEYS.md rename {moveToAnotherRepo => reserved}/METHOD FORMAT EXAMPLE.md (79%) diff --git a/HANDSHAKE.md b/HANDSHAKE.md index a4ba065..5a238e7 100644 --- a/HANDSHAKE.md +++ b/HANDSHAKE.md @@ -6,7 +6,7 @@ - Магическое число - _Тип:_ `uint64_t` - - Магическое число протокола, по которому определяется совместимость цели с протоколом MFP. См. раздел "Магическое число" для справки. + - Магическое число протокола, по которому определяется совместимость цели с протоколом Stadium. См. раздел "Магическое число" для справки. - Версия протокола - _Тип:_ `uint32_t` - Поддерживаемая запрашивающим версия протокола. @@ -28,6 +28,12 @@ - `0b01`: размер данных это `uint8_t` - `0b10`: размер данных это `uint16_t` - `0b11`: размер данных это `uint64_t` + - Маска `0b00000011`: резерв +- Параметры криптографии + - _Тип:_ `uint16_t` + - Описывает используемые криптографические алгоритмы. + - Если равно нулю, то используются опции данной версии протокола по умолчанию + - Флаги переподключения - _Тип:_ `uint16_t` - Описывает параметры нового подключения: @@ -39,7 +45,9 @@ - `0b0000111111110000`: резерв под расширение - `0b1111000000000000`: резерв под под нужды сторонних реализаций -На что целевой сервер отвечает пакетом либо с согласием, либо ошибкой. Пакет с согласием имеет следующий формат: +На что целевой сервер отвечает пакетом либо с согласием, либо ошибкой. + +Пакет с согласием имеет следующий формат: `[magic number: 8B][0x00][reconnection port: 2B]` @@ -68,6 +76,8 @@ - 0x03: невозможно выделить новый порт для подключения. - 0x04: указанный транспортный протокол не поддерживается. - 0x05: указанная конфигурация размерностей не поддерживается. + - 0x06: недопустимые параметры криптографии. + - 0x07: один из указанных криптографических алгоритмов отключён на сервере. - Описание ошибки - _Тип:_ `uint8_t` - Текстовое описание ошибки. Является строкой в кодировке ASCII, оканчивающейся нулевым байтом. @@ -81,8 +91,8 @@ Магическим числом протокола является следующая последовательность байт: ``` -HEX: 0x4d 0x61 0x72 0x61 0x66 0x6f 0x6e 0x50 -DEC: 77 97 114 97 102 111 110 80 +HEX: 0x53 0x74 0x61 0x64 0x69 0x75 0x6d 0x50 +DEC: 83 116 97 100 105 117 109 80 ``` -Что соответствует строке "MarafonP" в кодировке ASCII. \ No newline at end of file +Что соответствует строке "StadiumP" в кодировке ASCII. \ No newline at end of file diff --git a/KLDR RESERVED KEYS.md b/KLDR RESERVED KEYS.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/KLDR RESERVED KEYS.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/OVERVIEW.md b/OVERVIEW.md index 82dc82c..f04a66e 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -1,8 +1,8 @@ -# Спецификация Marafon Protocol (MFP) v1.0 +# Спецификация протокола Stadium v1.0 -Marafon Protocol это протокол логического уровня общего назначения и работает поверх любого транспортного. Также является базой для одноимённого ("Marafon") полнофункционального мессенджера. +Протокол Stadium это протокол для безопасной коммуникации общего назначения, работающий поверх любого поддерживаемого транспорта. Также является основой для полнофункционального мессенджера Marafon. -_Здесь описана спецификация базового протокола; спецификация версии протокола используемая в мессенджере будет размещена в другом репозитории._ +_Здесь описана спецификация базового протокола; документация касательно версии протокола используемой в мессенджере размещена в другом репозитории._ Основной фокус при работе над сим проектом идёт на: @@ -21,8 +21,7 @@ _Здесь описана спецификация базового прото Сервер **обязан**: -1. Оповещать клиент о всех ошибках, возникших во время его запроса, кроме: - - Связанных с безопасностью +1. Оповещать клиент о всех ошибках, возникших во время его запроса, кроме связанных с безопасностью. 2. Оповещать сервер в федерации о всех ошибках, возникших во время его запроса, кроме: - Связанных с безопасностью - Связанных с внутренними неполадками @@ -52,16 +51,9 @@ _Здесь описана спецификация базового прото Пакеты с событиями всех категорий, кроме явно оговорённых или принадлежащих к надкатегории Server2Client, содержат идентификатор серверной сессии, являющийся четырёхбайтным числом без знака (`uint32_t`). -Пакеты с событиями всех категорий из надкатегории Client2Server, кроме явно оговорённых, содержат хэш полезной нагрузки, зашифрованный с помощью закрытого ключа подписи клиента. +Пакеты с событиями всех категорий из надкатегории Client2Server, кроме явно оговорённых, содержат хэш полезной нагрузки, зашифрованный с помощью закрытого ключа подписи клиента. Этот подписанный хэш гарантирует достоверность полезной нагрузки на уровне прямого подключения ("клиент-сервер" или "сервер-сервер"). -Пакеты с событиями всех категорий, кроме явно оговорённых, содержат формат полезной нагрузки, занимающий ровно 1 байт (`uint8_t`): - -- 0x01: фиксированная схема. -- 0x02: "ячеистая" структура. - -- Остальные значения зарезервированы. - -Данные (AKA "полезная нагрузка") могут быть представлены в формате фиксированной схемы или в виде ячеек, которые являются расположенными последовательно парами "ключ-значение" и могут быть расположены в произвольном порядке относительно друг-друга. Все неизвестные ключи при парсинге игнорируются. Одна пара (AKA "ячейка") имеет следующий вид: +Данные (AKA "полезная нагрузка") могут быть представлены в формате фиксированной схемы или в формате KLDR ("Key-Length-Data-Repeat"), которые являются расположенными последовательно парами "ключ-значение" и могут быть расположены в произвольном порядке относительно друг-друга. Формат целиком зависит от типа события. Все неизвестные ключи при парсинге игнорируются. Одна пара (AKA "ячейка") имеет следующий вид: `[key][data length][data]` @@ -69,13 +61,13 @@ _Здесь описана спецификация базового прото `[cell_1][cell_2][cell_3]...[cell_n]` -Ключ и длинна данных являются шестнадцатеричными числами, размерность которых задаётся на этапе хэндшейка. Полезная нагрузка не может отсутствовать полностью (кроме особо-оговорённых случаев), а ключ не может являться нулём. Если значение конкретной пары пусто, то его длинна должна быть нулём. +Ключ и длинна данных являются шестнадцатеричными числами, размерность которых задаётся на этапе хэндшейка. Полезная нагрузка не может отсутствовать полностью (кроме особо-оговорённых случаев), а ключ не может являться нулём. Если значение конкретной пары пусто, то длинна данных должна быть нулём. Исходя из всего вышеописанного, итоговая примерная структура пакета выглядит следующим образом: -`[category][subcategory][server session: 4B][payload hash: ?B][payload type: 1B][payload: >0B]` +`[category][subcategory][server session: 4B][payload hash: ~B][payload: >0B]` -Размер пакета не нормирован и ответственность за его менеджмент остаётся на транспортном уровне. (Эталонная реализация MFP будет использовать общий универсальный интерфейс, который, в свою очередь, заворачивает все данные в релевантный протокол транспортного уровня) +Размер пакета не нормирован и ответственность за его менеджмент остаётся на транспортном уровне. (Эталонная реализация Stadium будет использовать общий универсальный интерфейс, который, в свою очередь, заворачивать все данные в релевантный протокол транспортного уровня) ### Зарезервированные события @@ -83,25 +75,30 @@ _Здесь описана спецификация базового прото Все из зарезервированных типов помещаются в минимальную размерность типа события (т.е. по одному байту на категорию и подкатегорию). Ниже приведены диапазоны зарезервированных значений. -Зарезервировано для нужд протокола и запрещено к использованию в частных реализациях: +Зарезервировано для нужд протокола и запрещено к использованию в частных реализациях (см. также файлы в директории `reserved/` для конкретных примеров): - Категория `0x01` - Все субкатегории: выделены для событий общей направленности. - Категория `0x11` - Все субкатегории: выделены для событий ошибок и предупреждений протокольного уровня. -Рекомендуется к использованию при определённых случаях: +Рекомендуется к использованию в конкретных ситуациях: - Категории `0x12-0x1F` (включительно) - Все субкатегории: для событий ошибок и предупреждений. - - ### Зарезервированные ключи ячеек -Скоро. +У данных в формате KLDR также существуют зарезервированные ключи, которые аналогичным образом помещаются в минимальную размерность ключа: - +- `0x00` + - Запрещено к использованию. +- `0x01-0x20` (включительно) + - Базовые примитивы. +- `0x21-0x2F` (включительно) + - Для нужд криптографии. + +Подробное описание зарезервированных ключей есть в файле `KLDR RESERVED KEYS.md`. @@ -121,12 +118,35 @@ _Здесь описана спецификация базового прото ### Сессии и подпись +Пример работы подписи; при отправке сообщения клиентом другому клиенту, оно проходит следующую цепочку: + +1. Клиент-отправитель посылает пакет с подписанной полезной нагрузкой (далее - ППН) и подписанными основными данными (как часть содержания ППН), на свой хоумсервер (далее - ХС; место, где клиент аутентифицирован). +2. ХС проверяет подпись ППН на валидность. Допустим, что подпись верна. +3. ХС совершает релевантные действия, исходя из содержания и типа события. +4. ХС переподписывает пакет с использованием свой подписи. +5. ХС отправляет переподписанный пакет целевому серверу (далее - ЦС). +6. ЦС проверяет подпись ППН на валидность. Допустим, что подпись верна. +7. ЦС совершает релевантные действия, исходя из содержания и типа пакета. +8. ЦС переподписывает пакет с использованием своей подписи. +9. ЦС отправляет переподписанный пакет целевому клиенту (далее - ЦК). +10. ЦК проверяет подпись ППН на валидность. Допустим, что подпись верна. +11. ЦК проверяет подпись основных данных, на предмет соответствия подписи клиента-отправителя и совершает релевантные действия. + Каждый принятый сервером пакет, содержащий хэш полезной нагрузки, должен проверяться на соответствие подписи. Если сервер обнаруживает, что подпись неверна - сервер отвечает ошибкой, соединение разрывается, а администратор сервера и владелец учётной записи уведомляются об инциденте. Каждый принятый клиентом пакет, содержащий хэш полезной нагрузки, может быть проверен на соответствие подписи. Если клиент обнаруживает, что подпись неверна - он должен оповестить пользователя. - + -Полезная нагрузка пакета может быть проверена на целостность сервером или клиентом с использованием подписанного хеша, но данная проверка может быть отключена, по усмотрению владельца сервера или пользователя клиента. +Полезная нагрузка пакета может быть проверена на целостность сервером или клиентом с использованием хэша, но данная проверка может быть отключена, по усмотрению владельца сервера или пользователя клиента. -Если при проверке ID серверной сессии обнаруживается несоответствие - сервер отвечает ошибкой, соединение разрывается. \ No newline at end of file +Если при проверке ID серверной сессии обнаруживается несоответствие - сервер отвечает ошибкой, соединение разрывается. + + + +## Список ToDo (To Document) + +- Механизм пользовательский сессий, клиентские подписи и базовая аутентификация +- Механизм синхронизации ключей для сквозного шифрования между юзерами +- Манипуляции с файлами (скачивание/загрузка) +- Стриминг аудио и видео \ No newline at end of file diff --git a/moveToAnotherRepo/METHOD FORMAT EXAMPLE.md b/reserved/METHOD FORMAT EXAMPLE.md similarity index 79% rename from moveToAnotherRepo/METHOD FORMAT EXAMPLE.md rename to reserved/METHOD FORMAT EXAMPLE.md index 7f2604e..f19dc25 100644 --- a/moveToAnotherRepo/METHOD FORMAT EXAMPLE.md +++ b/reserved/METHOD FORMAT EXAMPLE.md @@ -4,14 +4,14 @@ ## Client2Server -Какое-то описание метода. На данный момент, "оффициально" поддерживается два формата, в которых могут быть представлены данные: ячейки (пары "ключ-значение", с указанием длинны значения) и фиксированная схема. Тут представлен пример в формате ячеек. +Какое-то описание метода. На данный момент, "оффициально" поддерживается два формата, в которых могут быть представлены данные: KLDR (расположенные последовательно "ключ-длина-значение") и фиксированная схема. Тут представлен пример в формате KLDR. **Ячейки:** - Код кредитки - _Ключ:_ 0x01 - _Тип:_ `uint16_t` - - CVV-код от кредитной карты разработчика. Может быть представлен 12-ю битами, но данные выровнены по сетке в 8 бит. + - CVV-код от кредитной карты разработчика. Может быть представлен 12-ю битами, но мир несправедлив и поэтому данные выровнены по сетке в 8 бит. - ФИ - _Ключ:_ 0x02 - _Тип:_ `char[]` @@ -38,4 +38,4 @@ ## Server2Server -_Также как и Client2Server._ \ No newline at end of file +_См. Client2Server._ \ No newline at end of file