swp-protocol 0.0.5

protocol for wrapping packets

Sekret Wrapper Protocol (SWP)

Протокол для оборачивания пакетов. Используется для передачи данных между узлами прокси.

Установка

pip install swp-protocol

---

Список объектов

• SWP
• ProtocolError
• AesGcmCrypto
• MessageType

---

SWP

Класс, реализующий функции упаковки данных в протокол SWP и распаковки обратно. Не создаёт объекты, работает с байтами.

Атрибуты класса:

Атрибут	Тип	Значение по умолчанию	Описание
AESGCM	bytes	b""	Ключ для AES-GCM шифрования
AUTO_ENCRYPT	bool	False	Флаг автоматического шифрования полезной нагрузки

---

ProtocolError

Базовый класс ошибок протокола.

Наследники:

• AesGcmKeyError — ошибка, связанная с AES-GCM ключом (неверная длина или отсутствие)
• HeaderNotCompliteError — заголовок SWP-пакета получен не полностью

---

AesGcmCrypto

Внутренний класс шифрования данных пакета. По умолчанию автоматическое шифрование выключено. Данный модуль не предполагает вмешательства разработчика.

---

MessageType

Класс-перечисление типов сообщений.

Тип	Значение	Описание
MSG_CONNECT	0x01	Соединение с сервером
MSG_DATA	0x02	Передача сообщения
MSG_CLOSE	0x03	Отключение от сервера

Note: Предназначен для использования в функции SWP.pack().

---

Формат пакета SWP

Поле	Размер (байт)	Тип	Описание
magic	3	bytes	Магическое число \x53\x57\x50
msg_type	1	byte	Тип сообщения
target_len	1	byte	Длина поля target
payload_len	2	short	Длина поля payload
target	target_len	bytes	Адрес получателя (домен, IP:port)
payload	payload_len	bytes	Полезная нагрузка

---

Пример использования

from swp import SWP, MessageType

# Загрузка ключа — автошифрование включается автоматически
SWP.load_aesgcm(b"32_byte_key_for_aes_gcm_encryption!!")

# Упаковка сообщения (будет зашифровано)
packet = SWP.pack(
    msg_type=MessageType.MSG_DATA,
    target=b"https://example-domain.ex",
    payload=b"Hello, world!"
)

# Распаковка
data = SWP.unpack(packet)
print(data["msg_type"], data["target"], data["payload"])

# Отключение шифрования
SWP.set_auto_encrypt(False)

---

Методы класса SWP

---

reset()

Сброс параметров класса до начальных значений.

Параметр	Тип	Описание
—	—	—

Возвращает:
None

---

set_auto_encrypt(value: bool) -> None

Включение или отключение автоматического шифрования тела пакетов.

Параметр	Тип	Описание
value	bool	True — включить автоматическое шифрование, False — выключить

Возвращает:
None

Исключения:
AesGcmKeyError — если не загружен AES-GCM ключ при попытке включить шифрование.

---

pack(msg_type, target, payload=b"") -> bytes

Создание SWP-пакета из переданных данных.

Параметр	Тип	Описание
msg_type	int	Тип сообщения (рекомендуется использовать MessageType)
target	bytes	Адрес получателя
payload	bytes	Полезная нагрузка (по умолчанию пустая строка)

Возвращает:
bytes — сформированный SWP-пакет (заголовок + target + payload).

Note: Если включён AUTO_ENCRYPT, payload будет зашифрован перед упаковкой.

---

unpack_header(buffer) -> tuple[bytes, int, int, int]

Извлечение данных заголовка из сырого пакета.

Параметр	Тип	Описание
buffer	bytes	Сырой SWP-пакет (полный или частичный)

Возвращает:
tuple[bytes, int, int, int] — кортеж из четырёх элементов:
(PROTOCOL_MAGIC, msg_type, target_len, payload_len)

Исключения:
HeaderNotCompliteError — если размер буфера меньше размера заголовка (HEADER_SIZE).

---

unpack(buffer) -> dict

Полная распаковка SWP-пакета с расшифровкой (если включена).

Параметр	Тип	Описание
buffer	bytes	Полный SWP-пакет

Возвращает:
dict — словарь с ключами:

• "msg_type" (int) — тип сообщения,
• "target" (bytes) — адрес получателя,
• "payload" (bytes) — полезная нагрузка (расшифрованная, если AUTO_ENCRYPT = True).

---

### `create_connect_package(target_address=b"") -> bytes`

Создание пакета для подключения к узлу.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `target_address` | `bytes` | Адрес целевого узла (по умолчанию пустая строка) |

**Возвращает:**  
`bytes` — SWP-пакет с типом `MSG_CONNECT`.

---

### `create_data_package(data, target_address=b"") -> bytes`

Создание пакета для передачи данных между узлами.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `data` | `bytes` | Данные для передачи |
| `target_address` | `bytes` | Адрес целевого узла (по умолчанию пустая строка) |

**Возвращает:**  
`bytes` — SWP-пакет с типом `MSG_DATA`.

---

### `create_close_package() -> bytes`

Создание пакета для отключения от узла.

| Параметр | Тип | Описание |
|----------|-----|----------|
| — | — | — |

**Возвращает:**  
`bytes` — SWP-пакет с типом `MSG_CLOSE` (пустые `target` и `payload`).

---

get_full_package_size(buffer) -> int

Определение полного размера пакета по его заголовку.

Параметр	Тип	Описание
buffer	bytes	Начало SWP-пакета (минимум размер заголовка)

Возвращает:
int — полный размер пакета (HEADER_SIZE + target_len + payload_len).
-1 — если переданных данных меньше размера заголовка.

---

load_aesgcm(key) -> None

Загрузка 32-байтного AES-GCM ключа и автоматическое включение шифрования.

Параметр	Тип	Описание
key	bytes	Ключ шифрования (должен быть ровно 32 байта)

Возвращает:
None

Исключения:
AesGcmKeyError — если длина ключа не равна 32.

Note: Метод загружает ключ в SWP.AESGCM и автоматически устанавливает SWP.AUTO_ENCRYPT = True.

---

_encode(message) -> bytes

Шифрование сообщения с использованием загруженного AES-GCM ключа.

Параметр	Тип	Описание
message	str или bytes	Исходное сообщение (строка автоматически кодируется в UTF-8)

Возвращает:
bytes — зашифрованное сообщение.

---

_decode(message) -> bytes

Расшифровка сообщения.

Параметр	Тип	Описание
message	bytes	Зашифрованное сообщение

Возвращает:
bytes — расшифрованное сообщение.

---

Информация о проекте

• Версия: 0.0.5
• Python: 3.8+
• Репозиторий: github.com/sekret01/SWP