diff --git a/DATA TYPES.md b/DATA TYPES.md index de5a54c..17f26dd 100644 --- a/DATA TYPES.md +++ b/DATA TYPES.md @@ -4,37 +4,6 @@ -#### 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 Идентификатор локального для конкретного сервера объекта. @@ -43,25 +12,15 @@ class ID { 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; // Доменное имя целевого сервера + std::string Server; // Доменное имя сервера-владельца объекта } GlobID; ``` @@ -75,7 +34,7 @@ typedef struct { - `0b10000000000000000000000000000000`: изменение прав доступа - `0b01111111111111111111111111111000`: нераспределено -Нераспределённые флаги могут быть использованы в SPX. +Нераспределённые флаги могут быть использованы в расширениях протокола. ```C++ typedef uint32_t Power; diff --git a/HANDSHAKE.md b/HANDSHAKE.md index a8b4f26..64166b9 100644 --- a/HANDSHAKE.md +++ b/HANDSHAKE.md @@ -2,7 +2,7 @@ После успешной установки защищённого соединения, происходит обмен характеристиками обоих сторон, AKA "рукопожатие". Запрашивающий соединение отправляет пакет следующего формата: -`[magic number: 8B][protocol version: 4B][sizes: 1B][crypto params: 2B][reconnection flags: 2B]` +`[magic number: 8B][protocol version: 4B][sizes: 1B][crypto params: 2B][reconnection flags: 4B]` - Магическое число - _Тип:_ `uint64_t` @@ -33,17 +33,17 @@ - _Тип:_ `uint16_t` - Описывает используемые криптографические алгоритмы. - Если равно нулю, то используются опции данной версии протокола по умолчанию - + - Флаги переподключения - - _Тип:_ `uint16_t` + - _Тип:_ `uint32_t` - Описывает параметры нового подключения: - - `0b0000000000000000`: оставить текущее подключение - - `0b0000000000000001`: переподключиться к тому-же порту - - `0b0000000000000010`: запросить новый порт для подключения - - `0b0000000000000100`: использовать TCP - - `0b0000000000001000`: использовать TLS - - `0b0000111111110000`: резерв под расширение - - `0b1111000000000000`: резерв под под нужды сторонних реализаций + - `0b00000000000000000000000000000000`: оставить текущее подключение + - `0b00000000000000000000000000000001`: переподключиться к тому-же порту + - `0b00000000000000000000000000000010`: запросить новый порт для подключения + - `0b00000000000000000000000000000100`: использовать TCP + - `0b00000000000000000000000000010000`: использовать TLS + - `0b00001111111111111111111111101000`: резерв под расширение + - `0b11110000000000000000000000000000`: резерв под под нужды сторонних реализаций На что целевой сервер отвечает пакетом либо с согласием, либо ошибкой. diff --git a/KLDR RESERVED KEYS.md b/KLDR RESERVED KEYS.md index a98fb13..c4a40e2 100644 --- a/KLDR RESERVED KEYS.md +++ b/KLDR RESERVED KEYS.md @@ -6,7 +6,7 @@ - Data - _Значение:_ `0x01` - - _Тип:_ любой + - _Тип:_ не имеет значения - Основные передаваемые данные. - ObjectID - _Значение:_ `0x02` @@ -46,4 +46,8 @@ - CryptoKeyID - _Значение:_ `0x12` - _Тип:_ `uint32_t` - - Идентификатор используемого криптографического ключа для шифрования данных. \ No newline at end of file + - Идентификатор используемого криптографического ключа для шифрования данных. +- SignedHash + - _Значение:_ `0x13` + - _Тип:_ не имеет значения + - Хэш основных передаваемых данных, зашифрованный закрытым ключом отправителя. \ No newline at end of file diff --git a/OVERVIEW.md b/OVERVIEW.md index 4c21979..d635e42 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -1,6 +1,6 @@ # Спецификация протокола Stadium v1.0 -Протокол Stadium это протокол для безопасной коммуникации общего назначения, работающий поверх любого поддерживаемого транспорта. Данная спецификация описывает лишь базу, поверх которой может быть реализованы расширения (SPX - Stadium Protocol eXtension) для более конкретных нужд. Помимо прочего, данный протокол служит основой для полнофункционального мессенджера Marafon, спецификация расширения которого находится в папке `Marafon SPX`. +Протокол Stadium это протокол для безопасной коммуникации общего назначения, работающий поверх любого поддерживаемого транспорта. Данная спецификация описывает лишь базу, поверх которой может быть реализованы расширения (SPX - Stadium Protocol eXtension) для более конкретных нужд. Помимо прочего, данный протокол служит основой для полнофункционального мессенджера Marafon, спецификация расширения которого находится в папке `SPX/Marafon/`. _Здесь описана спецификация базового протокола; документация касательно версии протокола используемой в мессенджере размещена в другом репозитории._ @@ -89,6 +89,8 @@ _Здесь описана спецификация базового прото - Категории `0x12-0x1F` (включительно) - Все субкатегории: для событий ошибок и предупреждений. + + ### Зарезервированные ключи ячеек У данных в формате KLDR также существуют зарезервированные ключи, которые аналогичным образом помещаются в минимальную размерность ключа: @@ -106,7 +108,7 @@ _Здесь описана спецификация базового прото ## Соединение, аутентификация и сессии -Первичное подключение к серверу может выполнятся разными способами, в том числе подразумевающими маскировку траффика под существующие протоколы, но при использовании вне локальных сетей - должно сводиться к установке защищённого соединения. +Первичное подключение к серверу может выполнятся разными способами, в том числе подразумевающими маскировку траффика под существующие протоколы, но при использовании вне локальных сетей - должно сводиться к установке защищённого соединения. В будущем также будет реализован слой сквозного шифрования уровня "клиент-сервер", но, до этого момента, предполагается использование сторонних решений. ### Рукопожатие @@ -118,44 +120,28 @@ _Здесь описана спецификация базового прото -### Сессии и подпись +### Сессии и подписи -Пример работы подписи; при отправке сообщения клиентом другому клиенту, оно проходит следующую цепочку: - -1. Клиент-отправитель посылает пакет с подписанной полезной нагрузкой (далее - ППН) и подписанными основными данными (как часть содержания ППН), на свой хоумсервер (далее - ХС; место, где клиент аутентифицирован). -2. ХС проверяет подпись ППН на валидность. Допустим, что подпись верна. -3. ХС совершает релевантные действия, исходя из содержания и типа события. -4. ХС переподписывает пакет с использованием свой подписи. -5. ХС отправляет переподписанный пакет целевому серверу (далее - ЦС). -6. ЦС проверяет подпись ППН на валидность. Допустим, что подпись верна. -7. ЦС совершает релевантные действия, исходя из содержания и типа пакета. -8. ЦС переподписывает пакет с использованием своей подписи. -9. ЦС отправляет переподписанный пакет целевому клиенту (далее - ЦК). -10. ЦК проверяет подпись ППН на валидность. Допустим, что подпись верна. -11. ЦК проверяет подпись основных данных, на предмет соответствия подписи клиента-отправителя и совершает релевантные действия. - -Каждый принятый сервером пакет, содержащий хэш полезной нагрузки, должен проверяться на соответствие подписи, путём расшифровки этого хэша открытом ключом подписи и последующего сравнения с реальным хэшем полезной нагрузки. Если сервер обнаруживает, что подпись неверна - сервер отвечает ошибкой, добавляет запись в журнал об инциденте, а обрабатываемый пакет игнорируется. - -Каждый принятый клиентом пакет, содержащий хэш полезной нагрузки, должен быть проверен на соответствие подписи. Если клиент обнаруживает, что подпись неверна - он уведомляет об этом пользователя, а обрабатываемый пакет игнорируется. - - - -Если при проверке ID серверной сессии обнаруживается несоответствие - сервер отвечает ошибкой, соединение разрывается. +См. `SESSIONS.md`. ## Система идентификаторов -Практически каждый объект в Stadium имеет свой уникальный идентификатор, по которому к нему (объекту) следует обращаться. Идентификаторы делятся на два типа: локальные и федеративные. +Практически каждый объект в Stadium имеет свой уникальный идентификатор, по которому к нему (объекту) следует обращаться. Идентификаторы делятся на три типа: локальные и глобальные. Первый тип является восьмибайтным числом без знака (`uint64_t`). Валидный объект не может иметь ID равный нулю. -Второй тип является структурой из двух восьмибайтных чисел без знака, кои являют из себя ID объекта и ID федерируемого сервера соответственно. - -ID федерируемого сервера определяется сервером при первой попытке коммуникации и ассоциировано с его подписью, списком доменов и IP-адресов. +Второй тип является структурой из одного восьмибайтного числа без знака и строки в кодировке ASCII, кои являют из себя ID объекта и доменное имя сервера соответственно. Сервер должен проверять идентификатор на валидность и отвергать его, если он не валиден в текущем контексте. +### Доменные имена + +Доменное имя может быть ассоциированно как сервером, так и клиентом с несколькими другими альтернативными доменными именами, связанными с этим сервером. + +Сервер может отправить подписанное событие другому серверу, с целью ассоциировать новое доменное имя со старым, к примеру, если старое более не актуально. Сервер-получатель события обязан не только проверить подпись, но провести проверку доменного имени на его соответствие серверу-отправителю, путём отправки события с запросом подписи сервера. Это событие должно по умолчанию иметь жёсткий рейт-лимит по критерию запрашиваемого домена, т.е. не более 10 проверок одного доменного имени в час. + ## Список ToDo (To Document) diff --git a/README.md b/README.md index cc5e5cb..c9c69d2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -# marafon-proto-specs +# Stadium Protocol -Спецификация протокола "Марафона". +Спецификация протокола Stadium и его официального расширения для нашего мессенджера - Marafon SPX. -**ПРОЕКТ В АКТИВНОЙ РАЗРАБОТКЕ** \ No newline at end of file +**ПРОЕКТ В АКТИВНОЙ РАЗРАБОТКЕ/PROJECT UNDER ACTIVE DEVELOPMENT** \ No newline at end of file diff --git a/SESSIONS.md b/SESSIONS.md new file mode 100644 index 0000000..42ac2aa --- /dev/null +++ b/SESSIONS.md @@ -0,0 +1,53 @@ +# Сессии и все-все-все + +## Подпись + +### Обмен пакетами в неаутентифицированом соединении + +До выполнения аутентификации, сервер может, но не обязан, подписывать каждый свой пакет. Клиент может проверять подпись только в случае наличия у него открытого ключа сервера. Также клиент не должен подписывать свои пакеты и должен устанавливать хэш полезной нагрузки в нулевое значение. + +### Регистрация + +Перед инициированием процедуры регистрации, клиент запрашивает открытый ключ подписи сервера и тот отвечает событием, с открытым ключом в качестве основных данных и подписанным закрытым ключом хэшем полезной нагрузки. Клиент должен проверить подпись этого события. + +В случае успешной регистрации, клиент генерирует публичный и приватный ключи подписи, после чего отправляет событие с публичным ключом в качестве основных данных и подписанной закрытым ключом хэшем полезной нагрузки на сервер. Сервер должен проверить подпись этого события. + +### Обмен пакетами в аутентифицированном соединении + +Каждый принятый сервером пакет, содержащий хэш полезной нагрузки, должен проверяться на соответствие подписи, путём расшифровки этого хэша открытом ключом подписи и последующего сравнения с реальным хэшем полезной нагрузки. Если сервер обнаруживает, что подпись неверна - сервер отвечает ошибкой, добавляет запись в журнал об инциденте, а обрабатываемый пакет игнорируется. + +Каждый принятый клиентом пакет, содержащий хэш полезной нагрузки, должен быть проверен на соответствие подписи. Если клиент обнаруживает, что подпись неверна - он уведомляет об этом пользователя, а обрабатываемый пакет игнорируется. + +### Наглядные примеры работы с подписями + +#### Отправка подписанного пакета + +При отправке сообщения клиентом A клиенту Б, оно проходит следующую цепочку: + +1. Клиент А посылает пакет с подписанным хэшем полезной нагрузки (далее - ХПН) и подписанными основными данными (как часть содержания полезной нагрузки), на свой хоумсервер (место, где клиент А аутентифицирован, далее - ХС А). +2. ХС A проверяет ХПН на валидность. Допустим, что подпись верна. +3. ХС А совершает релевантные действия, исходя из содержания и типа события. +4. ХС А переподписывает ХПН с использованием свой подписи. +5. ХС А отправляет переподписанный пакет хоумсерверу клиента Б (далее - ХС Б). +6. ХС Б проверяет ХПН на валидность. Допустим, что подпись верна. +7. ХС Б совершает релевантные действия, исходя из содержания и типа пакета. +8. ХС Б переподписывает пакет с использованием своей подписи. +9. ХС Б отправляет переподписанный пакет клиенту Б. +10. Клиент Б проверяет ХПН на валидность. Допустим, что подпись верна. +11. Клиент Б проверяет подпись основных данных, на предмет соответствия подписи клиента А и совершает релевантные действия. + + + + + +## Серверные сессии и их идентификаторы + +При аутентификации клиента на сервере, сервер генерирует и отправляет клиенту уникальный идентификатор серверной сессии, который также ассоциирует с текущим подключением клиента. + +После успешной аутентификации, клиент обязан прилагать назначенный ему ID серверной сессии к каждому пакету. + +Если при проверке ID серверной сессии в пакете обнаруживается её отсутствие среди пулла серверных сессий - сервер отвечает ошибкой, соединение разрывается. + +Две серверные сессии не должны иметь одинаковое значение ID ни при каких условиях. + +Разные подключения одного клиента должны иметь одинаковую ассоциированную сессию. \ No newline at end of file