Документация по приложению OpenPGP GUI

Добро пожаловать в официальную документацию по приложению OpenPGP GUI.

Обзор

Это приложение предоставляет современный, удобный интерфейс для управления ключами OpenPGP, шифрования, дешифрования, подписи сообщений, их проверки и генерации SSL-сертификатов. Все криптографические операции выполняются локально для обеспечения максимальной конфиденциальности.

Возможности

• Современный интерфейс с использованием ttkbootstrap (тема Superhero)
• Генерация, загрузка и экспорт пар ключей OpenPGP
• Установка имени ключа, email, парольной фразы и просмотр отпечатка
• Шифрование и дешифрование сообщений
• Подпись и проверка сообщений (отсоединенные подписи)
• Экспорт открытого ключа в формате ASCII-armor (.asc)
• Визуализация отпечатка ключа для проверки подлинности
• Генерация SSL-сертификатов с пользовательским CN
• Очистка/сброс всех полей одним нажатием
• Централизованная система логирования (информация, предупреждения, ошибки, необработанные исключения)
• Просмотрщик логов с фильтрацией в реальном времени (ВСЕ, ИНФО, ПРЕДУПРЕЖДЕНИЕ, ОШИБКА)
• Использование log_info, log_warning, log_error для пользовательских записей
• Автоматический сбор и отображение трассировки стека в просмотрщике логов
• Динамическая строка меню с диалоговыми окнами “О программе”, “Помощь”, “Просмотр логов”, “Поддержка”, “Версия”
• Семантическое версионирование и информация о версии
• Модульная структура (struttura, gui и т.д.)
• Простота расширения и настройки темы (через ttkbootstrap)

Начало работы

Требования

• Python 3.9 или новее
• PySide6 (включен в requirements)
• pgpy (включен в requirements)
• cryptography (включен в requirements)
• pyperclip (включен в requirements)

Примечание: Приложение было перенесено с Tkinter/ttkbootstrap на PySide6 для более современного и поддерживаемого пользовательского интерфейса.

Установка

1. Клонируйте или загрузите этот репозиторий.
2. (Опционально) Создайте виртуальное окружение:

   python -m venv venv
   venv\Scripts\activate
   

3. Установите зависимости:

   pip install -r requirements.txt
   

Запуск приложения

Запустите из корневой директории проекта:

python main.py

Если возникают ошибки импорта, убедитесь, что вы запускаете из корневой директории, а не из подкаталога.

Руководство пользователя

Обзор главного окна

• Введите ваше имя, email и парольную фразу для генерации ключа.
• Выберите алгоритм (в настоящее время RSA; скоро будет больше).
• Используйте кнопки для генерации, загрузки или экспорта ключей.
• Отпечаток загруженного/сгенерированного ключа отображается для проверки.
• Используйте текстовую область для ввода сообщений для шифрования, дешифрования, подписи или проверки.
• Экспортируйте ваш открытый ключ для безопасного обмена.
• Генерируйте SSL-сертификаты прямо из интерфейса.
• Используйте кнопку ‘Очистить’ для сброса всех полей.

Строка меню

• Файл: Экспорт открытого ключа, Выход
• Журнал: Просмотр логов (с фильтрами ВСЕ, ИНФО, ПРЕДУПРЕЖДЕНИЕ, ОШИБКА)
• Помощь: Справка, О программе, Поддержка

Система логирования и просмотр логов

• Вся информация, предупреждения, ошибки и необработанные исключения логируются автоматически.
• Используйте log_info(msg), log_warning(msg), log_error(msg) в ваших скриптах для пользовательского логирования.
• Просмотрщик логов (Журнал > Просмотр логов) позволяет фильтровать и просматривать логи по уровню.
• Если файл лога отсутствует, отображается последняя трассировка стека, если она доступна.

Советы

• Все криптографические операции выполняются локально (без облака).
• Для лучшей безопасности используйте надежные парольные фразы.
• Окно лога предоставляет обратную связь и детали ошибок.

Продвинутое использование

Экспорт открытых ключей

• Используйте кнопку или пункт меню ‘Экспорт открытого ключа’ для сохранения вашего открытого ключа в формате ASCII-armor (.asc).

Проверка отпечатка

• Всегда проверяйте отпечаток перед обменом открытым ключом для дополнительной безопасности.

Генерация SSL-сертификатов

• Введите желаемое общее имя (CN) в поле имени.
• Нажмите кнопку ‘Сгенерировать SSL-сертификат’ для создания самоподписанного сертификата.

Расширение приложения

• Вы можете добавить поддержку большего количества алгоритмов (ECC, Ed25519), расширив логику генерации ключей в main_window.py.
• Интерфейс использует ttkbootstrap для простой настройки тем и кастомизации.

Логирование и отладка

• Все действия, предупреждения, ошибки и необработанные исключения сохраняются в traceback.log.
• Используйте log_info, log_warning, log_error для пользовательских записей в вашем коде.
• Просмотрщик логов поддерживает фильтрацию по ВСЕ, ИНФО, ПРЕДУПРЕЖДЕНИЕ, ОШИБКА.
• Необработанные исключения автоматически логируются и отображаются в Просмотрщике логов (с трассировкой стека).

Устранение неполадок

• При возникновении ошибок импорта убедитесь, что вы запускаете из корневой директории проекта.
• При проблемах с зависимостями проверьте requirements.txt или переустановите необходимые пакеты.

Руководство разработчика

Добро пожаловать, разработчик! Это руководство предоставляет основную информацию для внесения вклада в разработку и расширения приложения OpenPGP GUI.

Структура проекта

• main.py — Точка входа, запускает главное окно.
• gui/ — Все компоненты графического интерфейса (главное окно, виджеты, диалоговые окна).
• struttura/ — Основная логика, диалоговые окна, утилиты, управление версиями, справка/о программе и т.д.
• docs/ — Документация.
• requirements.txt — Зависимости Python.

Ключевые технологии

• Python 3.x
• Tkinter — Фреймворк для графического интерфейса (с ttkbootstrap для тем)
• pgpy — Криптография OpenPGP
• cryptography — Генерация SSL-сертификатов
• Pillow — (опционально) для иконок

Как внести вклад

1. Сделайте форк и клонируйте репозиторий.
2. Создайте виртуальное окружение и установите зависимости.
3. Следуйте PEP8 и сохраняйте код модульным.
4. Документируйте новые функции и обновляйте CHANGELOG.md.
5. Добавьте или обновите тесты, если это возможно.
6. Откройте pull request с четким описанием.

Добавление функций

• Чтобы добавить новые алгоритмы (например, ECC), расширьте логику генерации ключей в main_window.py.
• Для новых компонентов графического интерфейса добавляйте виджеты в gui/ и отделяйте логику от интерфейса.
• Используйте стили ttkbootstrap для единообразного внешнего вида.

Тестирование

• Добавляйте тесты для новых функций и исправлений ошибок.
• Ручное тестирование: запустите python main.py и протестируйте все функции интерфейса.
• (Опционально) Интегрируйте с CI/CD для автоматизированного тестирования.

Стиль кода

• Следуйте PEP8.
• Используйте строки документации для общедоступных функций/классов.
• Максимально разделяйте интерфейс и логику.

Логирование и отладка

• Используйте log_info(msg), log_warning(msg), log_error(msg) в любом месте кода для пользовательских записей.
• Все логи сохраняются в traceback.log и отображаются в Просмотрщике логов.
• Просмотрщик логов поддерживает фильтрацию по ВСЕ, ИНФО, ПРЕДУПРЕЖДЕНИЕ, ОШИБКА.
• Необработанные исключения автоматически логируются и отображаются в Просмотрщике логов (с трассировкой стека).

Поддержка и вопросы

• Открывайте issues на GitHub для сообщений об ошибках или запросов функций.
• См. README.md для контактной информации и информации о внесении вклада.

Продвинутые темы

Справочник по API

Приложение имеет модульную структуру: основная логика находится в struttura/, графический интерфейс — в gui/.

Основные классы и функции:

• MainWindow (gui/main_window.py): Основная логика графического интерфейса и обработка событий.
• gen_key, export_pubkey, clear_fields и др.: Методы для криптографических операций.
• Help, About, LogViewer и др.: Диалоговые окна и утилиты в struttura/.
• get_version() (struttura/version.py): Возвращает строку с текущей версией.

Для получения дополнительной информации читайте строки документации в коде и смотрите docs/user_guide.md для понимания потока использования.

Примеры расширений

Добавление нового алгоритма ключей

1. В gui/main_window.py найдите выпадающий список выбора алгоритма.
2. Добавьте ваш новый алгоритм (например, ECC, Ed25519) в список опций.
3. В логике генерации ключей реализуйте обработку нового алгоритма с использованием pgpy.
4. Тщательно протестируйте и обновите документацию.

Добавление пользовательского виджета

1. Создайте ваш виджет в gui/widgets.py или новом файле.