Marafon Protocol -> Stadium

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`
+	- Описывает используемые криптографические алгоритмы.
+		- Если равно нулю, то используются опции данной версии протокола по умолчанию
+<!-- TODO -->
 - Флаги переподключения
 	- _Тип:_ `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
+HEX: 0x53 0x74 0x61 0x64 0x69 0x75 0x6d 0x50
-DEC:  77   97   114  97   102  111  110  80
+DEC:  83   116  97   100  105  117  109  80
 ```
 
-Что соответствует строке "MarafonP" в кодировке ASCII.
+Что соответствует строке "StadiumP" в кодировке ASCII.

KLDR RESERVED KEYS.md

@@ -0,0 +1 @@
+TODO

OVERVIEW.md

@@ -1,8 +1,8 @@
-# Спецификация Marafon Protocol (MFP) v1.0
+# Спецификация протокола Stadium v1.0
 
-Marafon Protocol это протокол логического уровня общего назначения и работает поверх любого транспортного. Также является базой для одноимённого ("Marafon") полнофункционального мессенджера.
+Протокол Stadium это протокол для безопасной коммуникации общего назначения, работающий поверх любого поддерживаемого транспорта. Также является основой для полнофункционального мессенджера Marafon.
 
-_Здесь описана спецификация базового протокола; спецификация версии протокола используемая в мессенджере будет размещена в другом репозитории._ <!--за спецификацией протокола используемого в мессенджере - обратитесь к репозиторию с реализацией Marafon'а.-->
+_Здесь описана спецификация базового протокола; документация касательно версии протокола используемой в мессенджере размещена в другом репозитории._
 
 Основной фокус при работе над сим проектом идёт на:
 
@@ -21,8 +21,7 @@ _Здесь описана спецификация базового прото
 
 Сервер **обязан**:
 
-1. Оповещать клиент о всех ошибках, возникших во время его запроса, кроме:
+1. Оповещать клиент о всех ошибках, возникших во время его запроса, кроме связанных с безопасностью.
-	- Связанных с безопасностью
 2. Оповещать сервер в федерации о всех ошибках, возникших во время его запроса, кроме:
 	- Связанных с безопасностью
 	- Связанных с внутренними неполадками
@@ -52,16 +51,9 @@ _Здесь описана спецификация базового прото
 
 Пакеты с событиями всех категорий, кроме явно оговорённых или принадлежащих к надкатегории Server2Client, содержат идентификатор серверной сессии, являющийся четырёхбайтным числом без знака (`uint32_t`).
 
-Пакеты с событиями всех категорий из надкатегории Client2Server, кроме явно оговорённых, содержат хэш полезной нагрузки, зашифрованный с помощью закрытого ключа подписи клиента.
+Пакеты с событиями всех категорий из надкатегории Client2Server, кроме явно оговорённых, содержат хэш полезной нагрузки, зашифрованный с помощью закрытого ключа подписи клиента. Этот подписанный хэш гарантирует достоверность полезной нагрузки на уровне прямого подключения ("клиент-сервер" или "сервер-сервер").
 
-Пакеты с событиями всех категорий, кроме явно оговорённых, содержат формат полезной нагрузки, занимающий ровно 1 байт (`uint8_t`):
+Данные (AKA "полезная нагрузка") могут быть представлены в формате фиксированной схемы или в формате KLDR ("Key-Length-Data-Repeat"), которые являются расположенными последовательно парами "ключ-значение" и могут быть расположены в произвольном порядке относительно друг-друга. Формат целиком зависит от типа события. Все неизвестные ключи при парсинге игнорируются. Одна пара (AKA "ячейка") имеет следующий вид:
-
-- 0x01: фиксированная схема.
-- 0x02: "ячеистая" структура.
-<!-- - 0x03: вложенная "ячеистая" структура с зашифрованным содержимым -->
-- Остальные значения зарезервированы.
-
-Данные (AKA "полезная нагрузка") могут быть представлены в формате фиксированной схемы или в виде ячеек, которые являются расположенными последовательно парами "ключ-значение" и могут быть расположены в произвольном порядке относительно друг-друга. Все неизвестные ключи при парсинге игнорируются. Одна пара (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` (включительно)
 	- Все субкатегории: для событий ошибок и предупреждений.
 
-<!-- TODO? -->
-
 ### Зарезервированные ключи ячеек
 
-Скоро.
+У данных в формате KLDR также существуют зарезервированные ключи, которые аналогичным образом помещаются в минимальную размерность ключа:
 
-<!-- TODO? -->
+- `0x00`
+	- Запрещено к использованию.
+- `0x01-0x20` (включительно)
+	- Базовые примитивы.
+- `0x21-0x2F` (включительно)
+	- Для нужд криптографии.
+
+Подробное описание зарезервированных ключей есть в файле `KLDR RESERVED KEYS.md`.
 
 
 
@@ -121,12 +118,35 @@ _Здесь описана спецификация базового прото
 
 ### Сессии и подпись
 
+Пример работы подписи; при отправке сообщения клиентом другому клиенту, оно проходит следующую цепочку:
+
+1. Клиент-отправитель посылает пакет с подписанной полезной нагрузкой (далее - ППН) и подписанными основными данными (как часть содержания ППН), на свой хоумсервер (далее - ХС; место, где клиент аутентифицирован).
+2. ХС проверяет подпись ППН на валидность. Допустим, что подпись верна.
+3. ХС совершает релевантные действия, исходя из содержания и типа события.
+4. ХС переподписывает пакет с использованием свой подписи.
+5. ХС отправляет переподписанный пакет целевому серверу (далее - ЦС).
+6. ЦС проверяет подпись ППН на валидность. Допустим, что подпись верна.
+7. ЦС совершает релевантные действия, исходя из содержания и типа пакета.
+8. ЦС переподписывает пакет с использованием своей подписи.
+9. ЦС отправляет переподписанный пакет целевому клиенту (далее - ЦК).
+10. ЦК проверяет подпись ППН на валидность. Допустим, что подпись верна.
+11. ЦК проверяет подпись основных данных, на предмет соответствия подписи клиента-отправителя и совершает релевантные действия.
+
 Каждый принятый сервером пакет, содержащий хэш полезной нагрузки, должен проверяться на соответствие подписи. Если сервер обнаруживает, что подпись неверна - сервер отвечает ошибкой, соединение разрывается, а администратор сервера и владелец учётной записи уведомляются об инциденте.
 
 Каждый принятый клиентом пакет, содержащий хэш полезной нагрузки, может быть проверен на соответствие подписи. Если клиент обнаруживает, что подпись неверна - он должен оповестить пользователя.
 
-<!-- TODO: решить: должен ли сервер иметь свою подпись; как и нужно-ли, чтобы сервер являлся средой нулевого доверия в плане передачи подписей пользователей (скорее всего "Да." х 2) -->
+<!-- TODO: решить: как и нужно-ли, чтобы сервер являлся средой нулевого доверия в плане передачи подписей пользователей (скорее всего "Да.") -->
 
-Полезная нагрузка пакета может быть проверена на целостность сервером или клиентом с использованием подписанного хеша, но данная проверка может быть отключена, по усмотрению владельца сервера или пользователя клиента.
+Полезная нагрузка пакета может быть проверена на целостность сервером или клиентом с использованием хэша, но данная проверка может быть отключена, по усмотрению владельца сервера или пользователя клиента.
 
 Если при проверке ID серверной сессии обнаруживается несоответствие - сервер отвечает ошибкой, соединение разрывается.
+
+
+
+## Список ToDo (To Document)
+
+- Механизм пользовательский сессий, клиентские подписи и базовая аутентификация
+- Механизм синхронизации ключей для сквозного шифрования между юзерами
+- Манипуляции с файлами (скачивание/загрузка)
+- Стриминг аудио и видео

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._
+_См. Client2Server._