diff --git a/DATA TYPES.md b/DATA TYPES.md new file mode 100644 index 0000000..de5a54c --- /dev/null +++ b/DATA TYPES.md @@ -0,0 +1,82 @@ +# Типы данных + +Сия спецификация, помимо всего прочего, также определяет некоторые необходимые типы и структуры данных. В данном файле вы найдёте их описание и декларации. + + + +#### ID + +Класс, реализующий абстракцию над более конкретными типами идентификаторов. В этой спецификации указывается в качестве типа в тех случаях, когда применим любой из трёх типов. + +```C++ +class ID { + private: + uint64_t object_id, server_id; + std::string server_domain; + public: + ID (uint64_t oid, uint64_t sid, std::string sd) { + this->object_id = oid; + this->server_id = sid; + this->server_domain = sd; + } + LocID GetValue () { return this->object_id; } + FedID GetValue () { + FedID fid; + fid.Object = this->object_id; + fid.Server = this->server_id; + return fid; + } + GlobID GetValue () { + GlobID gid; + gid.Object = this->object_id; + gid.Server = this->server_domain; + return gid; + } +} +``` + +#### LocID + +Идентификатор локального для конкретного сервера объекта. + +```C++ +typedef uint64_t LocID; +``` + +#### FedID + +Идентификатор объекта в пределах федерации. + +```C++ +typedef struct { + uint64_t Object; + uint64_t Server; +} FedID; +``` + +#### GlobID + +Идентификатор объекта за пределами федерации. + +```C++ +typedef struct { + uint64_t Object; + std::string Server; // Доменное имя целевого сервера +} GlobID; +``` + +#### Power + +Права доступа к какому-либо объекту. Представляет из себя набор следующих флагов: + +- `0b00000000000000000000000000000001`: чтение +- `0b00000000000000000000000000000010`: запись +- `0b00000000000000000000000000000100`: удаление +- `0b10000000000000000000000000000000`: изменение прав доступа +- `0b01111111111111111111111111111000`: нераспределено + +Нераспределённые флаги могут быть использованы в SPX. + +```C++ +typedef uint32_t Power; +``` \ No newline at end of file diff --git a/HANDSHAKE.md b/HANDSHAKE.md index 5a238e7..a8b4f26 100644 --- a/HANDSHAKE.md +++ b/HANDSHAKE.md @@ -2,7 +2,7 @@ После успешной установки защищённого соединения, происходит обмен характеристиками обоих сторон, AKA "рукопожатие". Запрашивающий соединение отправляет пакет следующего формата: -`[magic number: 8B][protocol version: 4B][sizes: 1B][reconnection flags: 2B]` +`[magic number: 8B][protocol version: 4B][sizes: 1B][crypto params: 2B][reconnection flags: 2B]` - Магическое число - _Тип:_ `uint64_t` diff --git a/KLDR RESERVED KEYS.md b/KLDR RESERVED KEYS.md index 30404ce..a98fb13 100644 --- a/KLDR RESERVED KEYS.md +++ b/KLDR RESERVED KEYS.md @@ -1 +1,49 @@ -TODO \ No newline at end of file +# Список зарезервированных ключей ячеек + + + +## Базовые примитивы + +- Data + - _Значение:_ `0x01` + - _Тип:_ любой + - Основные передаваемые данные. +- ObjectID + - _Значение:_ `0x02` + - _Тип:_ `ID` + - ID объекта в локальном контексте. Например, ID канала для отправки сообщения. +- EventAuthor + - _Значение:_ `0x03` + - _Тип:_ `LocID` или `FedID` + - Источник (автор) события. Например, если клиент отправляет сообщение в канал, то он должен указывать свой айди как значение этой ячейки. +- PrevEvent + - _Значение:_ `0x04` + - _Тип:_ `LocID` или `FedID` + - Предыдущее событие, логически связанное с текущим. +- NextEvent + - _Значение:_ `0x05` + - _Тип:_ `LocID` или `FedID` + - Следующее событие, логически связанное с текущим. +- BatchNumber + - _Значение:_ `0x06` + - _Тип:_ `uint32_t` + - Последовательный номер события в цепочке. +- Path + - _Значение:_ `0x07` + - _Тип:_ `char[]` + - Название загружаемого/запрашиваемого файла или URL. +- Power + - _Значение:_ `0x08` + - _Тип:_ `Power` + - Права доступа к конкретному объекту. + +## Криптография + +- CryptoAlgo + - _Значение:_ `0x11` + - _Тип:_ `uint32_t` + - Флаги используемых криптографических алгоритм(-ов) для шифрования данных. +- CryptoKeyID + - _Значение:_ `0x12` + - _Тип:_ `uint32_t` + - Идентификатор используемого криптографического ключа для шифрования данных. \ No newline at end of file diff --git a/OVERVIEW.md b/OVERVIEW.md index f04a66e..4c21979 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -1,6 +1,6 @@ # Спецификация протокола Stadium v1.0 -Протокол Stadium это протокол для безопасной коммуникации общего назначения, работающий поверх любого поддерживаемого транспорта. Также является основой для полнофункционального мессенджера Marafon. +Протокол Stadium это протокол для безопасной коммуникации общего назначения, работающий поверх любого поддерживаемого транспорта. Данная спецификация описывает лишь базу, поверх которой может быть реализованы расширения (SPX - Stadium Protocol eXtension) для более конкретных нужд. Помимо прочего, данный протокол служит основой для полнофункционального мессенджера Marafon, спецификация расширения которого находится в папке `Marafon SPX`. _Здесь описана спецификация базового протокола; документация касательно версии протокола используемой в мессенджере размещена в другом репозитории._ @@ -13,6 +13,8 @@ _Здесь описана спецификация базового прото - Совместимость со всеми мажорными оверлейными сетями (Tor, I2P и yggdrasil). - Расширяемость. +В сей спецификации вы иногда сможете встретить примеры кода и упоминание типов данных языка C++, так как без них обойтись моментами сложно. + @@ -51,9 +53,9 @@ _Здесь описана спецификация базового прото Пакеты с событиями всех категорий, кроме явно оговорённых или принадлежащих к надкатегории Server2Client, содержат идентификатор серверной сессии, являющийся четырёхбайтным числом без знака (`uint32_t`). -Пакеты с событиями всех категорий из надкатегории Client2Server, кроме явно оговорённых, содержат хэш полезной нагрузки, зашифрованный с помощью закрытого ключа подписи клиента. Этот подписанный хэш гарантирует достоверность полезной нагрузки на уровне прямого подключения ("клиент-сервер" или "сервер-сервер"). +Пакеты с событиями всех категорий, кроме явно оговорённых, содержат хэш полезной нагрузки, зашифрованный с помощью закрытого ключа подписи отправляющего. Этот подписанный хэш гарантирует достоверность полезной нагрузки на уровне прямого подключения ("клиент-сервер" или "сервер-сервер"). -Данные (AKA "полезная нагрузка") могут быть представлены в формате фиксированной схемы или в формате KLDR ("Key-Length-Data-Repeat"), которые являются расположенными последовательно парами "ключ-значение" и могут быть расположены в произвольном порядке относительно друг-друга. Формат целиком зависит от типа события. Все неизвестные ключи при парсинге игнорируются. Одна пара (AKA "ячейка") имеет следующий вид: +Данные (AKA "полезная нагрузка") могут быть представлены в формате фиксированной схемы или в формате KLDR ("Key-Length-Data-Repeat"), которые являются расположенными последовательно парами "ключ-значение" и могут быть расположены в произвольном порядке относительно друг-друга. Применяемый формат зависит от типа события, но чаще всего это KLDR. Все неизвестные ключи при его парсинге игнорируются. Одна пара (AKA "ячейка") имеет следующий вид: `[key][data length][data]` @@ -71,7 +73,7 @@ _Здесь описана спецификация базового прото ### Зарезервированные события -Некоторые категории событий зарезервированы под нужды базового протокола или просто для событий определённого рода. Второе носит рекомендательный характер; вы также можете использовать другие диапазоны для тех-же целей. +Некоторые категории событий зарезервированы под нужды базового протокола или просто для событий определённого рода. Второе носит рекомендательный характер; вы также можете использовать иные диапазоны для тех-же целей. Все из зарезервированных типов помещаются в минимальную размерность типа события (т.е. по одному байту на категорию и подкатегорию). Ниже приведены диапазоны зарезервированных значений. @@ -93,9 +95,9 @@ _Здесь описана спецификация базового прото - `0x00` - Запрещено к использованию. -- `0x01-0x20` (включительно) +- `0x01-0x10` (включительно) - Базовые примитивы. -- `0x21-0x2F` (включительно) +- `0x11-0x1F` (включительно) - Для нужд криптографии. Подробное описание зарезервированных ключей есть в файле `KLDR RESERVED KEYS.md`. @@ -132,21 +134,33 @@ _Здесь описана спецификация базового прото 10. ЦК проверяет подпись ППН на валидность. Допустим, что подпись верна. 11. ЦК проверяет подпись основных данных, на предмет соответствия подписи клиента-отправителя и совершает релевантные действия. -Каждый принятый сервером пакет, содержащий хэш полезной нагрузки, должен проверяться на соответствие подписи. Если сервер обнаруживает, что подпись неверна - сервер отвечает ошибкой, соединение разрывается, а администратор сервера и владелец учётной записи уведомляются об инциденте. +Каждый принятый сервером пакет, содержащий хэш полезной нагрузки, должен проверяться на соответствие подписи, путём расшифровки этого хэша открытом ключом подписи и последующего сравнения с реальным хэшем полезной нагрузки. Если сервер обнаруживает, что подпись неверна - сервер отвечает ошибкой, добавляет запись в журнал об инциденте, а обрабатываемый пакет игнорируется. -Каждый принятый клиентом пакет, содержащий хэш полезной нагрузки, может быть проверен на соответствие подписи. Если клиент обнаруживает, что подпись неверна - он должен оповестить пользователя. +Каждый принятый клиентом пакет, содержащий хэш полезной нагрузки, должен быть проверен на соответствие подписи. Если клиент обнаруживает, что подпись неверна - он уведомляет об этом пользователя, а обрабатываемый пакет игнорируется. -Полезная нагрузка пакета может быть проверена на целостность сервером или клиентом с использованием хэша, но данная проверка может быть отключена, по усмотрению владельца сервера или пользователя клиента. - Если при проверке ID серверной сессии обнаруживается несоответствие - сервер отвечает ошибкой, соединение разрывается. +## Система идентификаторов + +Практически каждый объект в Stadium имеет свой уникальный идентификатор, по которому к нему (объекту) следует обращаться. Идентификаторы делятся на два типа: локальные и федеративные. + +Первый тип является восьмибайтным числом без знака (`uint64_t`). Валидный объект не может иметь ID равный нулю. + +Второй тип является структурой из двух восьмибайтных чисел без знака, кои являют из себя ID объекта и ID федерируемого сервера соответственно. + +ID федерируемого сервера определяется сервером при первой попытке коммуникации и ассоциировано с его подписью, списком доменов и IP-адресов. + +Сервер должен проверять идентификатор на валидность и отвергать его, если он не валиден в текущем контексте. + + + ## Список ToDo (To Document) -- Механизм пользовательский сессий, клиентские подписи и базовая аутентификация +- Механизм пользовательских сессий, клиентские подписи и базовая аутентификация - Механизм синхронизации ключей для сквозного шифрования между юзерами - Манипуляции с файлами (скачивание/загрузка) - Стриминг аудио и видео \ No newline at end of file diff --git a/SPX/Marafon/README.md b/SPX/Marafon/README.md new file mode 100644 index 0000000..76ef3f8 --- /dev/null +++ b/SPX/Marafon/README.md @@ -0,0 +1,3 @@ +# Marafon SPX + +_Расширение протокола Stadium для мессенджера Marafon._ \ No newline at end of file